Project

General

Profile

Task #677

Make sure manual uses consistent style throughout

Added by Mark Abraham over 8 years ago. Updated almost 5 years ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
documentation
Target version:
-
Difficulty:
uncategorized
Close

Description

I think we should have a style guide for the manual so that people don't re-invent wheels in LaTeX for how to do things, or choose to do similar things in different ways.

For the moment, in lieu of actually writing one, I'll put ideas here as they occur to me.

Associated revisions

Revision 87adb862 (diff)
Added by Justin Lemkul over 8 years ago

Grammar fix.

IssueID #677

Revision 86cfeedd (diff)
Added by Mark Abraham over 8 years ago

Removed duplicate functionality

A few places used the command '\type{blah}' to achieve the same result
as '{\tt blah}'. These were changed to the latter for consistency.

IssueID #677

Revision e293097f (diff)
Added by Mark Abraham over 8 years ago

Improved consistency of text style usage

All references to tool names, option names, and command line inputs
should be like '{\tt g_tool_name}' so that the monospace font conveys
the standard meaning, which is that this is something the user might
type.

IssueID #677

Revision e0cd15f3 (diff)
Added by Mark Abraham over 8 years ago

Improved consistency of text style usage

All references to tool names, option names, and command line inputs
should be like '[TT]g_tool_name[tt]' or '<tt>-rerun</tt>' (depending
on the type of file), so that when it reaches the LaTeX manual, the
monospace font conveys the standard meaning, which is that this is
something the user might type.

IssueID #677

Revision bb7b1d0b (diff)
Added by Mark Abraham over 8 years ago

Improved conversion of documentation to LaTeX

Sundry improvements to the way textual markup in the inline
documentation for GROMACS tools was converted into LaTeX markup via
'g_tool_name -man tex' for inclusion in the LaTeX manual.

IssueID #677

Revision 3af321c1 (diff)
Added by Justin Lemkul over 8 years ago

Small fix for editconf related to formatting consistency.

IssueID #677

Revision 2cf6ccda (diff)
Added by Rossen Apostolov almost 5 years ago

Use cosistent style when referring to force fields.

Refs #677.

Change-Id: I386c6d9782c88d5af929a3230cd3beb06f2cfbd2

History

#1 Updated by Mark Abraham over 8 years ago

When "force field" is used as a noun, e.g. "modifying the force field", it should not be hyphenated.

When "force field" is used as an adjective, e.g. "modifying the force-field files", it should be hyphenated. The general reason for this is to prevent misunderstanding, which is admittedly unlikely in this particular context. Formally, in this case, "force-field" is a compound modifier (http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers). Note that "modifying the files of the force field" should not be hyphenated.

#2 Updated by Justin Lemkul over 8 years ago

Mark Abraham wrote:

When "force field" is used as a noun, e.g. "modifying the force field", it should not be hyphenated.

When "force field" is used as an adjective, e.g. "modifying the force-field files", it should be hyphenated. The general reason for this is to prevent misunderstanding, which is admittedly unlikely in this particular context. Formally, in this case, "force-field" is a compound modifier (http://en.wikipedia.org/wiki/Hyphen#Compound_modifiers). Note that "modifying the files of the force field" should not be hyphenated.

Quite right. Normally I pick up on that, but somehow as I read through it seemed wrong. I'll fix this one.

As for the style guide, one issue that occurred to me while editing program descriptions is that there are a few annoying little inconsistencies:

1. Sometimes programs are formatted in plain text, i.e. [TT]g_covar[tt], other times program names are not. It would be more work to add the formatting than to remove the dozen or so instances where it does occur, although when juxtaposed next to command line options and example usage, probably looks better in the end.

2. File formats are not consistent just about anywhere. Similarly with #1, file types are alternatively referred to as [TT].pdb[tt], and sometimes just pdb, as an example. Again, plain typeface is probably nicer overall, but would require a fair bit of careful work.

I'm not opposed to combing through the source again to make changes, but before I invested that time I figured I'd solicit thoughts.

#3 Updated by Mark Abraham over 8 years ago

Justin Lemkul wrote:

1. Sometimes programs are formatted in plain text, i.e. [TT]g_covar[tt], other times program names are not. It would be more work to add the formatting than to remove the dozen or so instances where it does occur, although when juxtaposed next to command line options and example usage, probably looks better in the end.

That's easily standardized. I'll write a perl script to loop over the list of program names, grepping the lines out of the .tex files to see what usages exist. Then, adapt the script to do sed-style replacements with whatever style seems best. Then git add -i -p allows for easy case-by-case approval.

2. File formats are not consistent just about anywhere. Similarly with #1, file types are alternatively referred to as [TT].pdb[tt], and sometimes just pdb, as an example. Again, plain typeface is probably nicer overall, but would require a fair bit of careful work.

Again, seems like regexes will be a friend here. I'll see what we have in the .tex files.

I'm not opposed to combing through the source again to make changes, but before I invested that time I figured I'd solicit thoughts.

Perl's job, not yours ;-)

#4 Updated by Mark Abraham over 8 years ago

I did a lot of conversion of program and option names, etc. in the manual .tex files, program, bug and options descriptions in the code, and mdp_opt.html.

#5 Updated by Rossen Apostolov almost 5 years ago

  • Project changed from Documentation to GROMACS
  • Category set to documentation

the issue was moved to project "Gromacs", category "documentation", and the original sub-project "Documentation" was removed.

#6 Updated by Gerrit Code Review Bot almost 5 years ago

Gerrit received a related patchset '1' for Issue #677.
Uploader: Rossen Apostolov ()
Change-Id: I386c6d9782c88d5af929a3230cd3beb06f2cfbd2
Gerrit URL: https://gerrit.gromacs.org/3627

Also available in: Atom PDF