Make doc/man7/ and doc/internal/man3/ conform with man-pages(7) #10034
Conversation
It's all in the details, from man-pages(7):
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.
...
paulidale
left a comment
There was a problem hiding this comment.
Consistency is good!
A couple of mostly harmless comments.
|
Oh man. This is good work, but it's sure going to be painful on all the doc-nits changes I have waiting review :( |
|
How should I say this... I aim to please 😉 |
|
See it on the bright side: you'll get to learn real regexps 😉 |
We have a few pages where part of function names can be considered
variable. There are no normative guidelines for such a case, but if
we draw from the formatting convention of variable and argument names,
we can draw the conclusion that this variable part should be italized,
within already given conventions. In other words, we need to help the
POD processor along in cases like these:
SPARSE_ARRAY_OF(TYPE)
ossl_sa_TYPE_num()
These need explicit formatting:
B<SPARSE_ARRAY_OF>(I<TYPE>)
B<ossl_sa_I<TYPE>_num>()
Nah, learn something strictly more powerful. I'm a fan of PEGs but there are others. |
paulidale
left a comment
There was a problem hiding this comment.
Safestack and lhash could also do with the same treatment I suspect.
paulidale
left a comment
There was a problem hiding this comment.
I'm happy with the changes here, my prior comment can be a new PR or an extra commit here.
Yes. Do notice that it's not within the scope of this PR. I'll make another for doc/man3/, probably piece meal (i.e. a few other) as they are easier to digest. |
It's all in the details, from man-pages(7):
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.
...
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from #10034)
We have a few pages where part of function names can be considered
variable. There are no normative guidelines for such a case, but if
we draw from the formatting convention of variable and argument names,
we can draw the conclusion that this variable part should be italized,
within already given conventions. In other words, we need to help the
POD processor along in cases like these:
SPARSE_ARRAY_OF(TYPE)
ossl_sa_TYPE_num()
These need explicit formatting:
B<SPARSE_ARRAY_OF>(I<TYPE>)
B<ossl_sa_I<TYPE>_num>()
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from #10034)
It's all in the details, from man-pages(7):
Checklist