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)
To avoid check failure, make dummy RETURN VALUES sections in the docs
which have no real functions decribed inside...
Reviewed-by: Andy Polyakov <appro@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4976)
Around 138 distinct errors found and fixed; thanks!
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3459)
Write missing prime.pod and srp.pod
Implement -c in find-doc-nits (for command options)
Other fixes to some manpages
Use B<-I<digest|cipher>> notation
Split up multiple flags into a single entry in the synopsis.
Add -1 and missing-help to list command.
Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4144)
Fix a =head1 section name
Fix a typo in POD label
Remove a spurious =back
Add a missing blank line
Avoid 'legacy' -- use 'deprecated' if still needed if we cannot just reword.
Always do strict checking
Do not warn about missing "RETURN VALUES" unless -s is set.
Change OpenSSL version 1.1 -> 1.1.0
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3830)
The search is approximate; look only for those that look like
functions.
[skip ci]
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3641)
Fix test for "documenting private functions"
And add -p flag to doc-nits recipe
Mark when things were deprecated, if doc'd as such
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3624)
Report if any non-public items are documented.
Add util/private.num that lists items that aren't in the public
(lib*.num) files that we do want to document.
Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3603)
