Re: openssl.1: Tag command names
Hi Klemens,
Ingo Schwarze wrote on Tue, Feb 18, 2020 at 04:30:53PM +0100:
> 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,
So, you did put this in, which is of course fine with me.
> 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.
I just fixed that two-line offset, mainly because it came almost
for free as a by-product of starting to systematically improve HTML
output, in particular starting to get rid of elements where
they are not really needed.
I'm appending the committed patch below such that people who want
can easily review how the HTML output now looks like for explicitly
tagged section headers (in the regress/mdoc/Sh/tag.out_html file
contained in the patch).
I also installed the new code on man.openbsd.org:
https://man.openbsd.org/openssl#s_client
https://man.openbsd.org/route#add
The following works unchanged because we already had automatic
tagging for section and subsection headers in HTML output:
https://man.openbsd.org/openssl#COMMON_NOTATION
In terminal output, i did not implement automatic tagging for section
and subsection headers yet. But given the current state of NODE_ID
support, that's now trivial to implement if people would like to see
it. The benefit isn't huge, but it might add a bit of consistency.
For example, right now, in ksh(1), these work:
/^ Quoting
/^FILES
Adding automatic tagging for .Sh and .Ss would make these two
do just the same:
:tQuoting
:tFILES
Yours,
Ingo
Log Message:
---
Fully support explicit tagging of .Sh and .Ss.
This fixes the offset of two lines in terminal output
and this improves HTML output by putting the id= attribute
and element into the respective or element rather
than writing an additional element.
To that end, introduce node flags NODE_ID (to make the node a link
target, for example by writing an HTML id= attribute or by calling
tag_put()) and NODE_HREF (to make the node a link source, used only
in HTML output, used only to write an element).
In particular:
* In the validator, generalize the concept of the "next node"
such that it also works before .Sh and .Ss.
* If the first argument of .Tg is empty, don't forget to complain
if there are additional arguments, which will be ignored.
* In the terminal formatter, support writing of explicit tags
for all kinds of nodes, not just for .Tg.
* In deroff(), allow nodes to have an explicit string representation
even when they aren't text nodes. Use this for explicitly tagged
section headers. Suprisingly, this is sufficient to make HTML
output work, without explicit code changes in the HTML formatter.
* In syntax tree output, display NODE_ID and NODE_HREF.
Modified Files:
--
mandoc:
mdoc_term.c
mdoc_validate.c
roff.c
roff.h
tree.c
mandoc/regress/mdoc/Sh:
Makefile
Added Files:
---
mandoc/regress/mdoc/Sh:
tag.in
tag.out_ascii
tag.out_html
tag.out_markdown
Revision Data
-
Index: roff.h
===
RCS file: /home/cvs/mandoc/mandoc/roff.h,v
retrieving revision 1.71
retrieving revision 1.72
diff -Lroff.h -Lroff.h -u -p -r1.71 -r1.72
--- roff.h
+++ roff.h
@@ -522,6 +522,8 @@ struct roff_node {
#defineNODE_NOFILL (1 << 8) /* Fill mode switched off. */
#defineNODE_NOSRC (1 << 9) /* Generated node, not in input
file. */
#defineNODE_NOPRT (1 << 10) /* Shall not print anything. */
+#defineNODE_ID (1 << 11) /* Target for deep linking. */
+#defineNODE_HREF(1 << 12) /* Link to another place in this
page. */
int prev_font; /* Before entering this node. */
int aux; /* Decoded node data, type-dependent. */
enum roff_tok tok; /* Request or macro ID. */
Index: tree.c
===
RCS file: /home/cvs/mandoc/mandoc/tree.c,v
retrieving revision 1.85
retrieving revision 1.86
diff -Ltree.c -Ltree.c -u -p -r1.85 -r1.86
--- tree.c
+++ tree.c
@@ -199,6 +199,13 @@ print_mdoc(const struct roff_node *n, in
putchar(')');
if (n->flags & NODE_EOS)
putchar('.');
+ if (n->flags & NODE_ID) {
+
Re: openssl.1: Tag command names
Hi Klemens, Ingo Schwarze wrote on Tue, Feb 18, 2020 at 04:30:53PM +0100: > Klemens Nanni wrote on Mon, Feb 17, 2020 at 05:19:27PM +0100: >> 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. So, i finally committed a patch for this class of issues. That patch turned out to be of somewhat scary size (+318 -252 lines touching 10 files), but even though i wasn't aware of it, all that was already broken before .Tg existed, so it needed fixing anyway. A patch of this size carries a certain risk of regressions, but given the nature of the changes, if there are any regressions, they will most likely be minor formatting glitches. Also, a significant fraction of the changes is half-mechanical, except that each individual place needed careful consideration whether or not it had to be changed (many superficially similar places should not be changed). Anyway, the significant amount of automated tests that i committed with the patch ought to further reduce the risk that anything goes wrong in some major way. I committed it right away because this is not the kind of patch that anybody would want to review. Even Kristaps would balk at that, i guess. Yours, Ingo
Re: openssl.1: Tag command names
Ingo Schwarze wrote in <20200218160703.gb27...@athene.usta.de>: |Hi, | |Steffen Nurpmeso wrote on Tue, Feb 18, 2020 at 04:52:48PM +0100: | |> i just want to add that there is still the mdocmx mdoc macro |> extension available, and is working fine for more than half |> a decade. I have not ported that to groff 1.22.4, but it is |> available for groff 1.22.3. It can much more than .Tg, of course, | |Yes, and i said half a decade ago that it was ill-designed |and the .Mx user interface is bloated. It deserves to die. | |Would you please delete me from the AUTHORS section in | | https://www.sdaoden.eu/code-mdocmx.html | |That was mere fooling around with immature ideas, and i clearly |said back then that what we ended up with in 2014 was not yet good |enough to consider implementing it, and i said that the time clearly |wasn't ripe to do a proper design. I totally disagree with you. It works wonderful, you get table of contents, inter- as well as intra-document links, freely defined anchors and links, and you get interactivity inside a TTY manual page with patched grotty. The effort is minimal, and only command options (for non-headers) could improve it. Not immature, not ill-designed, nonsense! But i can remove you from the list if you want to. --steffen | |Der Kragenbaer,The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)
Re: openssl.1: Tag command names
Hi, Steffen Nurpmeso wrote on Tue, Feb 18, 2020 at 04:52:48PM +0100: > i just want to add that there is still the mdocmx mdoc macro > extension available, and is working fine for more than half > a decade. I have not ported that to groff 1.22.4, but it is > available for groff 1.22.3. It can much more than .Tg, of course, Yes, and i said half a decade ago that it was ill-designed and the .Mx user interface is bloated. It deserves to die. Would you please delete me from the AUTHORS section in https://www.sdaoden.eu/code-mdocmx.html That was mere fooling around with immature ideas, and i clearly said back then that what we ended up with in 2014 was not yet good enough to consider implementing it, and i said that the time clearly wasn't ripe to do a proper design. Yours, Ingo
Re: openssl.1: Tag command names
Hello. I have not followed this thread but Ingo Schwarze wrote in <20200218153053.ga27...@athene.usta.de>: |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" shows me the synopsis right away. |> |> FWIW, some Linux distributions ship with separate manuals, e.g. x509(1SS\ |> L). ... |> 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. i just want to add that there is still the mdocmx mdoc macro extension available, and is working fine for more than half a decade. I have not ported that to groff 1.22.4, but it is available for groff 1.22.3. It can much more than .Tg, of course, you get cross references and a lot of other things. | troff: openssl.1:204: warning: macro 'Tg' not defined Of course that is with .Mx, too. --steffen | |Der Kragenbaer,The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)
Re: openssl.1: Tag command names
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" 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
Re: openssl.1: Tag command names
> I like the idea! I agree. > To me it would be more logical to put .Tg above .Sh, but that is a minor > thing. I also think that it would better to place .Tg above .Sh . On Mon, Feb 17, 2020 at 11:20:34PM +0100, Remi Locherer wrote: > On Mon, Feb 17, 2020 at 05:19:27PM +0100, Klemens Nanni wrote: > > > > I'd like to commit this soon, it allows me to jump to the command I'm > > looking for, e.g. ":tx509" shows me the synopsis right away. > > > > FWIW, some Linux distributions ship with separate manuals, e.g. x509(1SSL). > > > > 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. > > > > 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). > > > > I like the idea! > > To me it would be more logical to put .Tg above .Sh, but that is a minor > thing. > > > > > Index: openssl.1 > > === > > RCS file: /cvs/src/usr.bin/openssl/openssl.1,v > > retrieving revision 1.119 > > diff -u -p -U1 -r1.119 openssl.1 > > --- openssl.1 16 Feb 2020 16:39:01 - 1.119 > > +++ openssl.1 17 Feb 2020 16:11:22 - > > @@ -203,2 +203,3 @@ itself. > > .Sh ASN1PARSE > > +.Tg asn1parse > > .Bl -hang -width "openssl asn1parse" > > @@ -299,2 +300,3 @@ into a nested structure. > > .Sh CA > > +.Tg ca > > .Bl -hang -width "openssl ca" > > @@ -848,2 +850,3 @@ The same as > > .Sh CIPHERS > > +.Tg ciphers > > .Nm openssl ciphers > > @@ -880,2 +883,3 @@ but without cipher suite codes. > > .Sh CMS > > +.Tg cms > > .Bl -hang -width "openssl cms" > > @@ -1396,2 +1400,3 @@ is specified. > > .Sh CRL > > +.Tg crl > > .Bl -hang -width "openssl crl" > > @@ -1472,2 +1477,3 @@ Verify the signature on the CRL. > > .Sh CRL2PKCS7 > > +.Tg crl2pkcs7 > > .Bl -hang -width "openssl crl2pkcs7" > > @@ -1517,2 +1523,3 @@ The output format. > > .Sh DGST > > +.Tg dgst > > .Bl -hang -width "openssl dgst" > > @@ -1631,2 +1638,3 @@ If no files are specified then standard > > .Sh DHPARAM > > +.Tg dhparam > > .Bl -hang -width "openssl dhparam" > > @@ -1707,2 +1715,3 @@ parameters are generated instead. > > .Sh DSA > > +.Tg dsa > > .Bl -hang -width "openssl dsa" > > @@ -1795,2 +1804,3 @@ Print the public/private key in plain te > > .Sh DSAPARAM > > +.Tg dsaparam > > .Bl -hang -width "openssl dsaparam" > > @@ -1847,2 +1857,3 @@ If this option is included, the input fi > > .Sh EC > > +.Tg ec > > .Bl -hang -width "openssl ec" > > @@ -1959,2 +1970,3 @@ Print the public/private key in plain te > > .Sh ECPARAM > > +.Tg ecparam > > .Bl -hang -width "openssl ecparam" > > @@ -2054,2 +2066,3 @@ Print the EC parameters in plain text. > > .Sh ENC > > +.Tg enc > > .Bl -hang -width "openssl enc" > > @@ -2217,2 +2230,3 @@ Print extra details about the processing > > .Sh ERRSTR > > +.Tg errstr > > .Nm openssl errstr > > @@ -2247,2 +2261,3 @@ Print debugging statistics about various > > .Sh GENDSA > > +.Tg gendsa > > .Bl -hang -width "openssl gendsa" > > @@ -2293,2 +2308,3 @@ The parameters in this file determine th > > .Sh GENPKEY > > +.Tg genpkey > > .Bl -hang -width "openssl genpkey" > > @@ -2397,2 +2413,3 @@ Print the private/public key in plain te > > .Sh GENRSA > > +.Tg genrsa > > .Bl -hang -width "openssl genrsa" > > @@ -2454,2 +2471,3 @@ The default is 2048. > > .Sh NSEQ > > +.Tg nseq > > .Nm openssl nseq > > @@ -2484,2 +2502,3 @@ a Netscape certificate sequence is creat > > .Sh OCSP > > +.Tg ocsp > > .Bl -hang -width "openssl ocsp" > > @@ -2836,2 +2855,3 @@ option. > > .Sh PASSWD > > +.Tg passwd > > .Bl -hang -width "openssl passwd" > > @@ -2899,2 +2919,3 @@ to each password hash. > > .Sh PKCS7 > > +.Tg pkcs7 > > .Bl -hang -width "openssl pkcs7" > > @@ -2944,2 +2965,3 @@ Print certificate details in full rather > > .Sh PKCS8 > > +.Tg pkcs8 > > .Bl -hang -width "openssl pkcs8" > > @@ -3027,2 +3049,3 @@ It is recommended that des3 is used. > > .Sh PKCS12 > > +.Tg pkcs12 > > .Bl -hang -width "openssl pkcs12" > > @@ -3244,2 +3267,3 @@ is equivalent to > > .Sh PKEY > > +.Tg pkey > > .Bl -hang -width "openssl pkey" > > @@ -3307,2 +3331,3 @@ even if a private key is being processed > > .Sh PKEYPARAM > > +.Tg pkeyparam > > .Cm openssl pkeyparam > > @@ -3332,2 +3357,3 @@ Print the parameters in plain text. > > .Sh PKEYUTL > > +.Tg pkeyutl > > .Bl -hang -width "openssl pkeyutl" > > @@ -3484,2 +3510,3 @@ Verify the input data and output the rec > > .Sh PRIME > > +.Tg prime > > .Cm openssl prime > > @@ -3528,2 +3555,3 @@ is prime. > > .Sh RAND > > +.Tg rand > > .Bl -hang -width "openssl rand" > > @@ -3555,2 +3583,3 @@ or standard output if not specified. > > .Sh REQ > > +.Tg req > > .Bl -hang -width "openssl req" > > @@ -4004,2 +4033,3 @@ Any additional fields will be treated as > > .Sh RSA > > +.Tg rsa > >
Re: openssl.1: Tag command names
On Mon, Feb 17, 2020 at 11:42:48PM +0100, 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. This is not semantic search but rather best effort pattern matching. You need to use uppercase and or anchor to line start in order to reach that particular spot. With tags you can specifically ask for a proper definition.
Re: openssl.1: Tag command names
On Mon, Feb 17, 2020 at 05:19:27PM +0100, Klemens Nanni wrote: > > I'd like to commit this soon, it allows me to jump to the command I'm > looking for, e.g. ":tx509" shows me the synopsis right away. 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. ok
Re: openssl.1: Tag command names
On Mon, Feb 17, 2020 at 05:19:27PM +0100, Klemens Nanni wrote: > > I'd like to commit this soon, it allows me to jump to the command I'm > looking for, e.g. ":tx509" shows me the synopsis right away. > > FWIW, some Linux distributions ship with separate manuals, e.g. x509(1SSL). > > 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. > > 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). > I like the idea! To me it would be more logical to put .Tg above .Sh, but that is a minor thing. > > Index: openssl.1 > === > RCS file: /cvs/src/usr.bin/openssl/openssl.1,v > retrieving revision 1.119 > diff -u -p -U1 -r1.119 openssl.1 > --- openssl.1 16 Feb 2020 16:39:01 - 1.119 > +++ openssl.1 17 Feb 2020 16:11:22 - > @@ -203,2 +203,3 @@ itself. > .Sh ASN1PARSE > +.Tg asn1parse > .Bl -hang -width "openssl asn1parse" > @@ -299,2 +300,3 @@ into a nested structure. > .Sh CA > +.Tg ca > .Bl -hang -width "openssl ca" > @@ -848,2 +850,3 @@ The same as > .Sh CIPHERS > +.Tg ciphers > .Nm openssl ciphers > @@ -880,2 +883,3 @@ but without cipher suite codes. > .Sh CMS > +.Tg cms > .Bl -hang -width "openssl cms" > @@ -1396,2 +1400,3 @@ is specified. > .Sh CRL > +.Tg crl > .Bl -hang -width "openssl crl" > @@ -1472,2 +1477,3 @@ Verify the signature on the CRL. > .Sh CRL2PKCS7 > +.Tg crl2pkcs7 > .Bl -hang -width "openssl crl2pkcs7" > @@ -1517,2 +1523,3 @@ The output format. > .Sh DGST > +.Tg dgst > .Bl -hang -width "openssl dgst" > @@ -1631,2 +1638,3 @@ If no files are specified then standard > .Sh DHPARAM > +.Tg dhparam > .Bl -hang -width "openssl dhparam" > @@ -1707,2 +1715,3 @@ parameters are generated instead. > .Sh DSA > +.Tg dsa > .Bl -hang -width "openssl dsa" > @@ -1795,2 +1804,3 @@ Print the public/private key in plain te > .Sh DSAPARAM > +.Tg dsaparam > .Bl -hang -width "openssl dsaparam" > @@ -1847,2 +1857,3 @@ If this option is included, the input fi > .Sh EC > +.Tg ec > .Bl -hang -width "openssl ec" > @@ -1959,2 +1970,3 @@ Print the public/private key in plain te > .Sh ECPARAM > +.Tg ecparam > .Bl -hang -width "openssl ecparam" > @@ -2054,2 +2066,3 @@ Print the EC parameters in plain text. > .Sh ENC > +.Tg enc > .Bl -hang -width "openssl enc" > @@ -2217,2 +2230,3 @@ Print extra details about the processing > .Sh ERRSTR > +.Tg errstr > .Nm openssl errstr > @@ -2247,2 +2261,3 @@ Print debugging statistics about various > .Sh GENDSA > +.Tg gendsa > .Bl -hang -width "openssl gendsa" > @@ -2293,2 +2308,3 @@ The parameters in this file determine th > .Sh GENPKEY > +.Tg genpkey > .Bl -hang -width "openssl genpkey" > @@ -2397,2 +2413,3 @@ Print the private/public key in plain te > .Sh GENRSA > +.Tg genrsa > .Bl -hang -width "openssl genrsa" > @@ -2454,2 +2471,3 @@ The default is 2048. > .Sh NSEQ > +.Tg nseq > .Nm openssl nseq > @@ -2484,2 +2502,3 @@ a Netscape certificate sequence is creat > .Sh OCSP > +.Tg ocsp > .Bl -hang -width "openssl ocsp" > @@ -2836,2 +2855,3 @@ option. > .Sh PASSWD > +.Tg passwd > .Bl -hang -width "openssl passwd" > @@ -2899,2 +2919,3 @@ to each password hash. > .Sh PKCS7 > +.Tg pkcs7 > .Bl -hang -width "openssl pkcs7" > @@ -2944,2 +2965,3 @@ Print certificate details in full rather > .Sh PKCS8 > +.Tg pkcs8 > .Bl -hang -width "openssl pkcs8" > @@ -3027,2 +3049,3 @@ It is recommended that des3 is used. > .Sh PKCS12 > +.Tg pkcs12 > .Bl -hang -width "openssl pkcs12" > @@ -3244,2 +3267,3 @@ is equivalent to > .Sh PKEY > +.Tg pkey > .Bl -hang -width "openssl pkey" > @@ -3307,2 +3331,3 @@ even if a private key is being processed > .Sh PKEYPARAM > +.Tg pkeyparam > .Cm openssl pkeyparam > @@ -3332,2 +3357,3 @@ Print the parameters in plain text. > .Sh PKEYUTL > +.Tg pkeyutl > .Bl -hang -width "openssl pkeyutl" > @@ -3484,2 +3510,3 @@ Verify the input data and output the rec > .Sh PRIME > +.Tg prime > .Cm openssl prime > @@ -3528,2 +3555,3 @@ is prime. > .Sh RAND > +.Tg rand > .Bl -hang -width "openssl rand" > @@ -3555,2 +3583,3 @@ or standard output if not specified. > .Sh REQ > +.Tg req > .Bl -hang -width "openssl req" > @@ -4004,2 +4033,3 @@ Any additional fields will be treated as > .Sh RSA > +.Tg rsa > .Bl -hang -width "openssl rsa" > @@ -4101,2 +4131,3 @@ Print the public/private key components > .Sh RSAUTL > +.Tg rsautl > .Bl -hang -width "openssl rsautl" > @@ -4175,2 +4206,3 @@ Verify the input data and output the rec > .Sh S_CLIENT > +.Tg s_client > .Bl -hang -width "openssl s_client" > @@ -4473,2 +4505,3 @@ will be used. > .Sh S_SERVER > +.Tg s_server > .Bl -hang -width "openssl s_server" > @@ -4778,2 +4811,3 @@ a certificate is requested but the clien > .Sh S_TIME > +.Tg s_time > .Bl -hang -width "openssl s_time" > @@ -4888,2
openssl.1: Tag command names
I'd like to commit this soon, it allows me to jump to the command I'm looking for, e.g. ":tx509" shows me the synopsis right away. FWIW, some Linux distributions ship with separate manuals, e.g. x509(1SSL). 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. 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). Index: openssl.1 === RCS file: /cvs/src/usr.bin/openssl/openssl.1,v retrieving revision 1.119 diff -u -p -U1 -r1.119 openssl.1 --- openssl.1 16 Feb 2020 16:39:01 - 1.119 +++ openssl.1 17 Feb 2020 16:11:22 - @@ -203,2 +203,3 @@ itself. .Sh ASN1PARSE +.Tg asn1parse .Bl -hang -width "openssl asn1parse" @@ -299,2 +300,3 @@ into a nested structure. .Sh CA +.Tg ca .Bl -hang -width "openssl ca" @@ -848,2 +850,3 @@ The same as .Sh CIPHERS +.Tg ciphers .Nm openssl ciphers @@ -880,2 +883,3 @@ but without cipher suite codes. .Sh CMS +.Tg cms .Bl -hang -width "openssl cms" @@ -1396,2 +1400,3 @@ is specified. .Sh CRL +.Tg crl .Bl -hang -width "openssl crl" @@ -1472,2 +1477,3 @@ Verify the signature on the CRL. .Sh CRL2PKCS7 +.Tg crl2pkcs7 .Bl -hang -width "openssl crl2pkcs7" @@ -1517,2 +1523,3 @@ The output format. .Sh DGST +.Tg dgst .Bl -hang -width "openssl dgst" @@ -1631,2 +1638,3 @@ If no files are specified then standard .Sh DHPARAM +.Tg dhparam .Bl -hang -width "openssl dhparam" @@ -1707,2 +1715,3 @@ parameters are generated instead. .Sh DSA +.Tg dsa .Bl -hang -width "openssl dsa" @@ -1795,2 +1804,3 @@ Print the public/private key in plain te .Sh DSAPARAM +.Tg dsaparam .Bl -hang -width "openssl dsaparam" @@ -1847,2 +1857,3 @@ If this option is included, the input fi .Sh EC +.Tg ec .Bl -hang -width "openssl ec" @@ -1959,2 +1970,3 @@ Print the public/private key in plain te .Sh ECPARAM +.Tg ecparam .Bl -hang -width "openssl ecparam" @@ -2054,2 +2066,3 @@ Print the EC parameters in plain text. .Sh ENC +.Tg enc .Bl -hang -width "openssl enc" @@ -2217,2 +2230,3 @@ Print extra details about the processing .Sh ERRSTR +.Tg errstr .Nm openssl errstr @@ -2247,2 +2261,3 @@ Print debugging statistics about various .Sh GENDSA +.Tg gendsa .Bl -hang -width "openssl gendsa" @@ -2293,2 +2308,3 @@ The parameters in this file determine th .Sh GENPKEY +.Tg genpkey .Bl -hang -width "openssl genpkey" @@ -2397,2 +2413,3 @@ Print the private/public key in plain te .Sh GENRSA +.Tg genrsa .Bl -hang -width "openssl genrsa" @@ -2454,2 +2471,3 @@ The default is 2048. .Sh NSEQ +.Tg nseq .Nm openssl nseq @@ -2484,2 +2502,3 @@ a Netscape certificate sequence is creat .Sh OCSP +.Tg ocsp .Bl -hang -width "openssl ocsp" @@ -2836,2 +2855,3 @@ option. .Sh PASSWD +.Tg passwd .Bl -hang -width "openssl passwd" @@ -2899,2 +2919,3 @@ to each password hash. .Sh PKCS7 +.Tg pkcs7 .Bl -hang -width "openssl pkcs7" @@ -2944,2 +2965,3 @@ Print certificate details in full rather .Sh PKCS8 +.Tg pkcs8 .Bl -hang -width "openssl pkcs8" @@ -3027,2 +3049,3 @@ It is recommended that des3 is used. .Sh PKCS12 +.Tg pkcs12 .Bl -hang -width "openssl pkcs12" @@ -3244,2 +3267,3 @@ is equivalent to .Sh PKEY +.Tg pkey .Bl -hang -width "openssl pkey" @@ -3307,2 +3331,3 @@ even if a private key is being processed .Sh PKEYPARAM +.Tg pkeyparam .Cm openssl pkeyparam @@ -3332,2 +3357,3 @@ Print the parameters in plain text. .Sh PKEYUTL +.Tg pkeyutl .Bl -hang -width "openssl pkeyutl" @@ -3484,2 +3510,3 @@ Verify the input data and output the rec .Sh PRIME +.Tg prime .Cm openssl prime @@ -3528,2 +3555,3 @@ is prime. .Sh RAND +.Tg rand .Bl -hang -width "openssl rand" @@ -3555,2 +3583,3 @@ or standard output if not specified. .Sh REQ +.Tg req .Bl -hang -width "openssl req" @@ -4004,2 +4033,3 @@ Any additional fields will be treated as .Sh RSA +.Tg rsa .Bl -hang -width "openssl rsa" @@ -4101,2 +4131,3 @@ Print the public/private key components .Sh RSAUTL +.Tg rsautl .Bl -hang -width "openssl rsautl" @@ -4175,2 +4206,3 @@ Verify the input data and output the rec .Sh S_CLIENT +.Tg s_client .Bl -hang -width "openssl s_client" @@ -4473,2 +4505,3 @@ will be used. .Sh S_SERVER +.Tg s_server .Bl -hang -width "openssl s_server" @@ -4778,2 +4811,3 @@ a certificate is requested but the clien .Sh S_TIME +.Tg s_time .Bl -hang -width "openssl s_time" @@ -4888,2 +4922,3 @@ but not transfer any payload data. .Sh SESS_ID +.Tg sess_id .Bl -hang -width "openssl sess_id" @@ -4980,2 +5015,3 @@ debugging purposes. .Sh SMIME +.Tg smime .Bl -hang -width "openssl smime" @@ -5276,2 +5312,3 @@ An error occurred writing certificates. .Sh SPEED +.Tg speed .Bl -hang -width "openssl speed" @@ -5313,2 +5350,3 @@ benchmarks in parallel. .Sh SPKAC +.Tg spkac .Bl -hang -width "openssl spkac" @@ -5374,2 +5412,3 @@ Verify the digital signature
