Various groff error fixes and minor improvements to man pages
Created an attachment (id=298)
section 1 man pages patch
There are a number of places in the man pages where lines start with a period that aren't groff commands, which causes rendering errors (the line in question disappears from the output). Additionally, while minor, there are a lot of bare "-"s in CLI arguments that get interpreted as hyphens in Unicode environments, which should actually be dashes, "\-"; otherwise it causes problems if you copy-and-paste examples straight to the command line.
The attached patch fixes all of those. It also expands the .TH header/footer, adds a brief description of every command to the .SH NAME section (allowing tools like apropos(1) to work), and - this is the messy one - adds a SEE ALSO for gromacs(7) to every man page, to help tie the whole bundle together and make it clear where any given binary came from.
Attached separately is a possible gromacs.7 man page listing every binary in the suite. It starts with some fairly hideous auto-generated code yanked from Perl's POD setup to assist with the formatting further down. I expect you might want to adjust the text at the bottom, after the command list.
#2 Updated by David van der Spoel about 12 years ago
Thanks for that. Is there any reason not to mv the gromacs.7 into a gromacs.1 except that it is not an executable? It would make it a bit easier to handle. On the other hand maybe we will once have developer (3) man pages as well.
As regards your other fixes: these files are generated from the source code. (src/gmxlib/wman.c). There may be a bug in the code which generates erroneous man pages, but when I do man anadock or man mdrun it looks ok. Could you please point out where exactly the error is?
I found one in grompp.1 on line 108, is that what you mean?
#3 Updated by Nicholas Breen about 12 years ago
Section for gromacs: Yeah, 7 just because it's not an executable; "miscellaneous" seems like the right place to put it.
Man page errors:
do_dssp.1.gz 79: warning: `Together' not defined
editconf.1.gz 55: warning: `Both' not defined
g_anaeig.1.gz 141: warning: `The' not defined
g_analyze.1.gz 169: warning: `The' not defined
g_enemat.1.gz 62: warning: `LJ:Protein-SOL'' not defined
g_hbond.1.gz 59: warning: `Dummy' not defined
g_msd.1.gz 45: warning: `An' not defined
g_nmeig.1.gz 34: warning: `When' not defined
g_traj.1.gz 88: warning: `To' not defined
g_vanhove.1.gz 63: warning: `The' not defined
g_wham.1.gz 23: warning: `pdo' not defined
genbox.1.gz 83: warning: `Other' not defined
grompp.1.gz 126: warning: `Additionally,' not defined
mdrun.1.gz 118: warning: `By' not defined
protonate.1.gz 22: warning: `If' not defined
trjconv.1.gz 176: warning: `gro,' not defined
xpm2ps.1.gz 45: warning: `Reasonable' not defined
It may be an implementation-dependent detail; on my fairly current Linux box, man simply fails to display the offending lines. Using do_dssp as an example, it goes from these line of C source:
"[TT]ssdump.dat[tt] for usage in the program [TT]g_chi[tt]. Together",
"these two programs can be used to analyze dihedral properties as a",
...to these lines of groff:
for usage in the program
these two programs can be used to analyze dihedral properties as a
...to this output from man:
Finally, this program can dump the secondary structure in a special file
ssdump.dat for usage in the program g_chi these two programs can be used
The ". Together" gets silently dropped. Converting it to "\&. Together" returns it to normal display. It might be easiest to change the first four entries of wman.c's sandrNROFF to output \fB and \fR instead of newlines and .B, which sidesteps the problem entirely. I can work up a patch for wman.c that would do most of the work from the man page patch, if you'd like - though I don't see any way to autogenerate one-liner descriptions in .SH NAME, that info isn't in the source files?
#5 Updated by Nicholas Breen about 12 years ago
Created an attachment (id=303)
Thanks, I'd never looked in admin.
Attached tarball contains (1) patch to wman.c that renders all dashes* and leading-periods safe*; (2) patch to mknroff that parses programs.txt (path/filename given as the second argument) for short descriptions and adds a few missing entries to programs.txt; and (3) pared-down man pages patch that covers everything not generated by mknroff - mostly for the binaries from src/kernel.
(Unfortunately, it also converts things that really *were hyphens to dashes, since they're not readily distinguishable in a regexp, but that seems acceptable - and it still copy/pastes more readily from Unicode to non-Unicode environments.)
#6 Updated by David van der Spoel about 12 years ago
Thanks for that Nicholas. The wman.c and mknroff patches applied cleanly. I am somewhat hesitant about the other patch though. The programs gmxcheck and gmxdump, grompp, mdrun, ngmx, pdb2gmx, protonate, tpbconv, x2top and so should all be able to generate man pages. I will look into it.