Menu
▾
▴
#1213 Incorrect nroff generation
When generating nroff from a [titledesc] directive, it's important that the description of commands all be placed on a single line. This is because the apropos search tool assumes that these descriptions are on a single line following the ".SH NAME" directive. Right now, you generate output here that is multiline in some cases (found when preparing HTML documentation for the Thread package with Tcl's 'make html', which failed; that's now fixed, but even so...) It's also expected that the part of the NAME description before the \- will be a list of commands described by the manual page, and not the name of the manual page itself. This makes a difference when manual pages describe multiple commands or when the name is not a "good" filename (e.g., by containing a colon).
It would also be useful if the generation of nroff from [example] used .CS/.CE to surround the example code instead of .nf/.fi as that is converted better. (.CS always marks sample code in some sense, .nf is used for many purposes.)
Bumping priority because it impacts delivery of documentation for packages on which Tcl 8.6 depends; we want the changes fed in upstream rather than having to hold custom patches to the generated nroff.
Investigating further (reading the doctools code ;-) specifically fmt.nroff) I see that there's an assumption that the title of the manpage that is used with [nr_title] is the same as the title that is used with the NAME section. That's not generally true; a number of Tcl's manual pages document multiple things (e.g., the *.3 ones) because they're really documenting an API. However, the name part that ends up in the .TH header (i.e., that's used with [nr_title]) needs to be a single fairly-short word since it goes in a location that can't be word-wrapped when doing actual manpage formatting for an 80-column terminal.
On, and there needs to be some whitespace compaction when dealing with the $description for the NAME section. Trivial to add a little [regsub] and [string trim]...
Ok, I added the whitespace compaction at least, and switched examples to .CS/.CE formatting.
Regarding the other thing (nr_title vs NAME) you are basically saying that I cannot use the 'title' argument for NAME, and need some separate information (*) to allow for the documentation of multiple things. I might be able to use the title if the separate info for NAME is missing, as a fallback.
(*) Either as additional argument of manpage_begin, or via a new doctools command whose data I pull in in the second phase. Oh, or by using all the command names which will get put into the synopsis anyway, right ? The latter means a bit more data extraction to get the [cmd]'s in [call]'s and [usage] contexts.
That will take a bit more time.
This is driven by making the Thread extension have as good documentation as possible. The thing with NAME is particularly driven by wanting to make the derived contents page list the commands instead of just the pages. Critical? No. Important for getting a really good build of the docs? I think so.