OpenSSL uses some POD directives masquerading as 'comment'
('=for comment' etc). This is abusive and confusing. Instead, we use
our own keyword.
=for openssl whatever
=begin openssl
whatever
=end openssl
(we have never used the multiline form, but might start one day)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10048)
For documentation of all commands with "-flag arg" format them
consistently: "B<-flag> I<arg>", except when arg is literal
(for example "B<-inform> B<PEM>|B<DER>")
Update find-doc-nits to complain if badly formatted strings are found.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10022)
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 https://github.com/openssl/openssl/pull/10034)
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 https://github.com/openssl/openssl/pull/10034)
And update find-doc-nits to complain if "=head1 EXAMPLE" is found.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
Move manpages to manX directories
Add Windows/VMS install fix from Richard Levitte
Update README
Fix typo's
Remove some duplicates
Reviewed-by: Richard Levitte <levitte@openssl.org>
