Hi Klemens, Klemens Nanni wrote on Mon, Feb 17, 2020 at 05:19:27PM +0100:
> I'd like to commit this soon, it allows me to jump to the command I'm > looking for, e.g. ":tx509<Enter>" shows me the synopsis right away. > > FWIW, some Linux distributions ship with separate manuals, e.g. x509(1SSL). Yes, that is how OpenSSL ships these manuals. Long before the LibreSSL project started, jmc@ already did the work of combining all the OpenSSL manual pages for subcommands into one single page, openssl(1). I think the rationale was that openssl(1) is one single command. We don't have separate manual pages for e.g. shell builtin commands either, like alias, cd, readonly, typeset, ... Besides, openssl(1) is mainly a testing tool, so that one in particular has no business squatting on lots of namespace. > Patch was done with a VIM macro by adding a new line after each `.Sh' > line with the respective name but lowercased, so no typos in the added > strings. That placement triggers an issue that already existed before .Tg arrived. In some places in the formatters, nodes are iterated (mainly backwards) to see whether there are any other nodes in the same parent, mostly for spacing purposes, but sometimes also for other purposes. Some nodes ought to be transparent to such iterations. Here are two examples; note the bogus blank line in the output after "DESCRIPTION" and before "text": $ mandoc -mdoc | ul .Sh DESCRIPTION .Sm off .Bl -tag -width Ds .It Cm text : Ar text text .El $ mandoc -mdoc | ul .Sh DESCRIPTION .ft B .Bd -unfilled text .Ed Yes, this mostly happens with code of dubious style, but the new .Tg macro can trigger the issue, too. With continuously improving low-level roff(7) support, more such nodes that need to be transparent in this way may appear in the future, so the issue is bound to become worse over time, and at least half a dozen such nodes already exist. Hence i'm working on a general solution, but that doesn't need to delay any commit, of course. > Specifying it is required since the markup following the `.Tg' markup > always starts with "openssl"; the tag must not include it (`.Tg' > accepts at most one word anyway). If we follow through on the idea of abandoning the rule that top level section headers must be all caps in the source code and instead do that formatting as appropriate for each formatter (groff has already gone that way, but we haven't fully concluded the discussion yet whether and how exactly we want to follow), the tagging in all these cases will become automatic. Besides, there may be value in waiting a bit before applying .Tg to manual pages of projects where the -portable version is particularly important, in particular OpenSSH and LibreSSL. Right now, groff(1) reacts as follows (still formatting the page correctly, of course): troff: openssl.1:204: warning: macro 'Tg' not defined I certainly intend to fix that warning in groff in the near future, but shipping pages in OpenSSH or LibreSSL -portable that throw warnings with the latest mandoc release and even with groff-current compiled straight from git might not yet be ideal. Theo Buehler wrote: > Without tags I currently achieve pretty much the same by doing "/^X509" > or "/^S_CLIENT" etc. However, having to know the special trick for each > page (if there is one) is annoying, so I think this is an improvement. That's exactly why i implemented no automatic tagging for .Sh in the past: it doesn't provide much practical benefit. Besides, the rule that .Sh arguments must be all caps further diminshed the value of automatically tagging .Sh. If that rule gets lifted, automatic tagging of .Sh becomes more useful (and almost free in terms of implementation effort). While i don't strongly object to the patch, it might be worth holding off a bit on manually tagging of .Sh given that even automatic tagging isn't done for that macro yet. Which would mean postponing this patch until automatic tagging for .Sh has been decided and implemented. Given that this is essentially manual tagging of .Sh, if you decide to put this in for the time being until automatic tagging of .Sh may arrive, i agree with the two developers who said that .Tg asn1parse .Sh ASN1PARSE would feel more natural, even though for now, that puts the tag two lines early in terminal output. But at the latest when automatic tagging for .Sh gets implemented, i will certainly fix that offset. Yours, Ingo
