Because we generate an increasing number of POD files, some of them
end up in the build tree. This makes it difficult for find-doc-nits
to work as desired when the build tree is separate from the source
tree.
The best supported way to make it work in such an environment is to
run it from the build tree and let it use the build information from
configdata.pm to find all the POD files. To make this smooth enough,
we add a function 'files' that returns an array of file names
corresponding to criteria from the caller.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11045)
When we run "make doc-nits" (which happens during travis runs) it will
complain if we add any new symbols that aren't documented. However it
was suppressing anything starting with ASN1. There's no reason why we
should allow ASN1 symbols to go undocumented any more than any others.
Therefore we remove that exception.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10980)
Update CHANGES to have a complete and uniform description.
Fixes#9730
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/10972)
find-doc-nits can give a list of symbols that were added since 1.1.1 and
are undocumented (using -o). To do this it uses the missingcrypto111.txt
and missingssl111.txt files which give a snapshot of the undocumented
symbols at the time of the 1.1.1 release. Currently it complains about
symbols that are in those files that have subsequently been documented.
This isn't particularly helpful so we suppress that feature when "-o"
is being used.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10981)
Add cmd-nits make target.
Listing options should stop when it hits the "parameters" separator.
Add missing .pod.in files to doc/man1/build.info
Tweak find-doc-nits to try openssl-XXX before XXX for POD files and
change an error messavge to be more useful.
Fix the following pages: ca, cms, crl, dgst, enc,
engine, errstr, gendsa, genrsa, list, ocsp, passwd, pkcs7, pkcs12, rand,
rehash, req, rsautil, s_server, speed, s_time,
sess_id, smime, srp, ts, x509.
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10873)
Replace "=for openssl foreign manuals" with simpler syntax, it looks
like the "=for openssl ifdef" construct.
Fix some broken L<> links; add some missing foreign references and fixed
some typo's.
The WARNINGS in dhparam referred to non-existant commands so reword it.
Fixes#10109
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10256)
It may be that some "missing" manuals have been written since their
insertion in the "missing" files. Make sure to alert when such manual
references are found.
This works, because we collect all existing manual references into
%name_map first.
Fixes#10681
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10683)
The names collected in util/missing*.txt are not file names, but
symbol names, and to compare properly with script data, the section
name must be included.
All symbols found in util/lib*.num are library functions, so we know
that they are in manual section 3 and can simply add that info. The
same goes for all macros found in C headers.
Finally, we get rid of getdocced() and its associated hash table
%docced. We already have the appropriate information in %name_map.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10621)
Also, turn missing L<foo(3)> into foo(3)
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10104)
The prototype checks shouldn't be performed on SYNOPSIS lines that
aren't function prototypes.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10394)
When checking links, we need to peal away stuff that aren't part of
the link proper first. That makes it easier to check the link
itself.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10507)
Add sections (almost always "(3)" to L<> references that were missing
them. Among other things, this
Fixes: #10226
Also remove two references to non-existant manpages that have never
existed, and with the 3.0 structure, are unlikely to do so.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10240)
Also tweak find-doc-nits while fixing a bug (don't need .in files)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10239)
Options moved: -rand, -writerand, -CApath, -CAfile, -no-CApath, -no-CAfile
Added rand to dgst and srp manpages (they were missing them).
New sections in openssl.pod: Random State Options, Trusted Certificate
Options.
Cleanup and add comments to find-doc-nits
Remove ".in" file support; unless giving specific arguments, this
only runs after configuration
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10118)
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)
Use err() for find-doc-nits -e output
Doing this meant we could remove the -s flag, so we do so; move
option/help stuff to top of script.
Add a CHANGES entry.
Rename missing to other.syms
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10039)
Also patch find-doc-nits to ignore a Microsoft trademark and not
flag it as a spelling error.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10023)
The checks for our uses of 'B<' and 'I<' for options, and possibly
function names, was over-reaching quite a bit.
So we fine-tune it a bit:
- by only checking for options in man1 pages, and only in SYNOPSIS
and *OPTIONS sections.
- by only checking for function names in man3 pages.
The man1 option checker has the additional check that options found in
*OPTIONS are also found in SYNOPSIS andd vice versa.
In all cases, this also handles options and function names with
additional markup, such as 'B<-I<cipher>>' and 'B<sk_I<TYPE>_push>'.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10073)
Make find-doc-nits understand that
=for comment ifdef ssl3 ...
in a POD page means that the "-ssl3" flag might be ifdef'd out in the
local environment, and not to complain about it.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9974)
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)
Commit b6b66573 (PR #9679) renamed most POD files. This change causes
find-doc-nits to flag misnamed files.
Also fix the two misnamed files that it found.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10000)
Filter all output to a new &err() routine, which sets the global
exit status, $status.
Also, fix all subroutine definitions and references to be consistent:
no prototypes, no & before function calls.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
(Merged from https://github.com/openssl/openssl/pull/9733)
Change find-doc-nits to complain if a section header is repeated,
within a parent header (i.e., duplicate =head2 within a =head1).
In almost all cases, we just remove the duplicate header, as
it was a "continuation" of the =head1 that was already in affect.
In some cases, just remove "=head1 NOTES", possibly moving text
around, because the "NOTES" were really important parts of the
DESCRIPTION section.
No =headX sections should end with a period.
All =head1 labels should be in all uppercase.
No sub-head (=head2, etc) should be in all uppercase.
Update find-doc-nits to reject the above.
Fixup an internal POD link
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9631)
Also update find-doc-nits to reject "=head1 WARNING"
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)
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)
The find-doc-nits script only looked for EXAMPLES, not EXAMPLE.
Fix the pattern and then fix the errors that resulted.
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)
- Treat .pod.in files as well, and parse out the base name for those
too.
- Correct the detection of the description part in the NAME section
(the separating dash MUST be preceeded with a space)
- Allow slahes in names of the NAME section (convert them to dashes
for file name comparison). This allows manual pages for some of our
header files, such as openssl/core.h.
- Properly detect repeated names in the NAME section.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9407)
We only export functions, not global, so remove the config option
and some of the #ifdef stuff.
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9285)
A previous commit added the ability to find newly undocumented symbols.
We extend this capability to check anything that was newly added since
1.1.1 which is undocumented. A new option -o is added to find-doc-nits
to amend the behaviour of -v or -e to check symbols that were newly
added since the release of 1.1.1.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9094)
We create lists of undocumented functions and macros as they are now so
that find-doc-nits can check for newly introduced functions/macros that
are undocumented.
This works in a similar way to the -u and -d options to find-doc-nits.
These count undocumented symbols and print a detailed list of undocumented
symbols repsectively. This commit adds the -v and -e options to restrict
the count/detailed list to newly added undocumented symbols only.
There is also a new -s option that does the same as -e except that it
produces no output if there are no newly undocumented symbols.
We also amend "make doc-nits" to add the -s option which should cause
travis to fail if a PR adds undocumented symbols.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9094)
POD markup is only forbidden in the actual names, while permitted in
the description.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8878)
Check that the HISTORY section is located after the SEE ALSO section,
this is a much more frequent order in OpenSSL manual pages (and UNIX
manual pages in general).
Also check that SEE ALSO comes after EXAMPLES, so that the tool can
ensure the correct manual section sequence.
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8729)
Change to check_section_location(), a generic function to ensure that
section SECTION appears before section BEFORE in the man pages.
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8729)
This patch checks if the EXAMPLES section in a pod file is placed
before the RETURN VALUES section.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8338)
While we're at it, we also check for names that contain white-space,
as they are invalid.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/8269)
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/7724)
Expand the text on deprecation to be more descriptive and to refer
back to openssl_user_macros(7).
Incidently, this required a small change in util/find-doc-nits, to
have it skip over any line that isn't part of a block (i.e. that
hasn't been indented with at least one space. That makes it skip over
deprecation text.
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/7745)
