Make manuals with TYPE conform with man-pages(7) #10041
Conversation
Details from man-pages(7) that are used:
Formatting conventions for manual pages describing functions
...
Variable names should, like argument names, be specified in italics.
...
Formatting conventions (general)
...
Special macros, which are usually in uppercase, are in bold.
Exception: don't boldface NULL.
...
Furthermore, for TYPE used as a placeholder for types and correponding
part of function names, we extrapolate that it's both a type and a
variable, and should therefore be bold (typical for types and function
names) and italic (typical for variables). POD processors don'e know
this, so we have to help them along. Therefore:
SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>)
ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>()
TYPE => B<I<TYPE>>
There are some other less typical uses where one simply has to give
formatting some extra though.
|
Oh man, the construct of It's also going to be confusing for developers who will backslide and start doing it for command flags, which took a lot of pain in #10022 to get right. I think flags and parameters are more important than the half-dozen manpages that use the |
|
Why do you mix up command line parameters (man1 pages) with function names (man3 and man7 pages)? Also, your idea breaks another detail from man-page(7): I only expand a little bit on that by making the variable part of the subject (i.e. the functions being described) italic as well, not instead of. Please read the commit message, where I'm describing by my reasoning. |
|
Now... if you need help figuring out regexps, all you have to do is ask. |
|
I think we need to talk about the TYPE controversy, I'd like to know what's your actual beef with formatting it the way I've done. See, there are two man-page conventions that are getting my attention here. One is about the name of the man-page subject, which actually says the same thing about commands and its options (applicable to man1) as well as for function names (man3) [italics mine for emphasis]:
However, we have things in our manual pages that are... unusual in the man-page world, such as variable options (-cipher) and function name specs with a variable part (i2d_TYPE or BIO_s_*). The convention is clear, since they are command options and function names, they should be bold, giving -cipher and i2d_TYPE or BIO_s_*. Fine according to the conventions, and yet not, because while we're making options and function names bold, this leads people to think that those should be used literally. We need a way to add to the convention while following it, and that's where making the variable part italic as well comes in. -cipher (on terminals, the italic part is often underlined instead) The counter proposal is to make them only italics: -cipher (on terminals, the italic part is often underlined instead) To me, that makes them not part of the name, but, er, something else, and it completely breaks the convention of having command options and function names / man-page subject in bold (do note that the conventions do not say only bold). Comments? |
|
There are a number of issues here: 1 Typography and display There are probably others (such as ego since I created the "TYPE" pages :). We treat these things with different importance, and we end up coming to two different conclusions. Oh well. |
|
I would say that 1 and 2 can be treated as one and the same, because the intention with the conventions with man-pages(7) as well as my proposal is better clarity. Re tooling, I would say tooling should adapt to what we decide is the best display of the manual, not the other way around. So at least in my mind, it has lower priority as a deciding factor. |
|
Yes, we disagree about the relative importance of (at least) those issues. |
Details from man-pages(7) that are used:
Formatting conventions for manual pages describing functions
...
Variable names should, like argument names, be specified in italics.
...
Formatting conventions (general)
...
Special macros, which are usually in uppercase, are in bold.
Exception: don't boldface NULL.
...
Furthermore, for TYPE used as a placeholder for types and correponding
part of function names, we extrapolate that it's both a type and a
variable, and should therefore be bold (typical for types and function
names) and italic (typical for variables). POD processors don'e know
this, so we have to help them along. Therefore:
SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>)
ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>()
TYPE => B<I<TYPE>>
There are some other less typical uses where one simply has to give
formatting some extra though.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #10041)
|
Merged. bbecf04 Make manuals with TYPE conform with man-pages(7) |
|
Like I suspected, |
Details from man-pages(7) that are used:
Furthermore, for TYPE used as a placeholder for types and correponding
part of function names, we extrapolate that it's both a type and a
variable, and should therefore be bold (typical for types and function
names) and italic (typical for variables). POD processors don'e know
this, so we have to help them along. Therefore:
There are some other less typical uses where one simply has to give
formatting some extra though.