For tutorial type pages it doesn't make any sense to have a DESCRIPTION
section.
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21133)
Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/20369)
The way the links were parsed out of the contents caused a regexp
recursion. The easiest way to deal with it is to find all markup
using $markup_re, and then parsing out the L markups and add them to
the links array.
Fixes#15449
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15450)
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11481)
Ensure the same term is used for fallback
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13862)
From the Pod::Checker manual:
> RETURN VALUE
> podchecker returns the number of POD syntax errors found or
> -1 if there were no POD commands at all found in the file.
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/13416)
Our matching of C symbols here was inconsistent and could therefore
give false negatives when the SYNOPSIS was parsed. Now we have
$C_symbol, which is a simple regexp that matches the common C symbol.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12873)
The new lhash changes have confused some of the perl scripts so we add
some fixes.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12860)
This change applies the recommendation of the Linux Documentation Project
to the documentation files of OpenSSL. Additionally, util/find-doc-nits
was updated accordingly.
The change follows a suggestion of mspncp on https://github.com/openssl/openssl/pull/12370
and incoporates the requested changes on the pull request
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/12460)
The relaxation allows spaces between function name and argument list,
to allow line breaks like this when there are very long names:
int (fantastically_long_name_breaks_80char_limit)
(fantastically_long_name_breaks_80char_limit *something);
This revealed some other intricaties, such as documented internal
structures with function pointers inside, so a check of open
structures was also added, and they are now simply skipped over.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12494)
- The check that disallowed space before the argument list in a
function typedef is tentatively removed, allowing this kind of
construction:
typedef int (fantastically_long_name_breaks_80char_limit)
(fantastically_long_name_breaks_80char_limit *something);
- Accept the following style of function signature:
typedef TYPE (NAME)(args...)
- Accept space between '#' and 'defined' / 'undef'
- Accept other spaces than SPC in argument list comma check,
allowing declaration with line breaks.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12452)
name_synopsis was reading physical SYNOPSIS lines. This changes it to
consider a declaration at a time, so we treat a C declaration that's
been broken up in several lines as one.
This makes it mandatory to end all C declarations in the SYNOPSIS with
a semicolon. Those can be detected in two ways:
1. Parsing an individual .pod file outputs this error:
doc/man3/SOMETHING.pod:1: Can't parse rest of synopsis:
int SOMETHING_status(SOMETHING *s)
int SOMETHING_start(SOMETHING *s)
(declarations not ending with a semicolon (;)?)
2. Errors like this:
doc/man3/SOMETHING.pod:1: SOMETHING_status missing from SYNOPSIS
doc/man3/SOMETHING.pod:1: SOMETHING_start missing from SYNOPSIS
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12452)
CLA: trivial
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/12320)
It wasn't up to date with the new variables used to track information
on what's documented, what's in the .num files and what's in the
"missing" files.
Fixes#12117
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12125)
CLA: trivial
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/12161)
We didn't really distinguish internal and public documentation, or
matched that with the state of the documented symbols. we therefore
needed to rework the logic to account for the state of each symbol.
To simplify things, and make them consistent, we load all of
util/*.num, util/*.syms and util/missing*.txt unconditionally.
Also, we rework the reading of the manuals to happen only once (or
well, not quite, Pod::Checker reads from file too, but at the very
least, our script isn't reading the same file multiple times).
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11476)
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)
