Project

General

Profile

Bug #228

Various groff error fixes and minor improvements to man pages

Added by Nicholas Breen about 12 years ago. Updated about 12 years ago.

Status:
Closed
Priority:
Normal
Category:
documentation
Target version:
Affected version - extra info:
Affected version:
Difficulty:
uncategorized
Close

Description

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.

manpages-reformat.patch (433 KB) manpages-reformat.patch section 1 man pages patch Nicholas Breen, 10/15/2008 01:44 AM
gromacs.7 (13.9 KB) gromacs.7 gromacs.7 Nicholas Breen, 10/15/2008 01:45 AM
bug228.tar.gz (14.4 KB) bug228.tar.gz updated patches Nicholas Breen, 10/16/2008 01:25 AM

History

#1 Updated by Nicholas Breen about 12 years ago

Created an attachment (id=299)
gromacs.7

#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
.B g_chi
. Together
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?

#4 Updated by David van der Spoel about 12 years ago

It would be great if you could fix wman.c. The one-liner info is in admin/programs.txt which is processed with the mknroff script in the same directory.

#5 Updated by Nicholas Breen about 12 years ago

Created an attachment (id=303)
updated patches

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.

#7 Updated by David van der Spoel about 12 years ago

This has been fixed now with full support for man7 man pages. the mknroff script has been replaced by a mknroff.pl script.

Also available in: Atom PDF