Tcl Library Source Code

View Ticket
Login
Ticket UUID: 3058654
Title: Incorrect nroff generation
Type: Bug Version: None
Submitter: dkf Created on: 2010-09-03 09:25:33
Subsystem: doctools Assigned To: andreas_kupries
Priority: 8 Severity:
Status: Open Last Modified: 2010-09-08 12:21:31
Resolution: None Closed By:
    Closed on:
Description:
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.)
User Comments: dkf added on 2010-09-08 12:21:31:
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.

andreas_kupries added on 2010-09-08 02:52:12:
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.

dkf added on 2010-09-05 04:18:11:
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]...

dkf added on 2010-09-05 04:06:01:
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.

dkf added on 2010-09-03 16:27:11:
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.