Infrastructure for templated doc in POD files

Use new doc-build capabilities
Add -i flag to dofile.
Add doc/man1 to SUBDIRS for the new templated doc files
Rewrite commit a397aca (merged from PR 10118) to use the doc-template stuff.
Put template references in common place
Template options and text come at the end of command-specific options:
opt_x, opt_trust, opt_r (in that order).
Refactor xchain options.
Do doc-nits after building generated sources.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10159)

1 files changed, 109 insertions, 0 deletions

diff --git a/doc/man1/openssl-speed.pod.in b/doc/man1/openssl-speed.pod.in
new file mode 100644
index 0000000000..657a4156c6
--- /dev/null
+++ b/doc/man1/openssl-speed.pod.in
@@ -0,0 +1,109 @@
+=pod
+
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
+=head1 NAME
+
+openssl-speed - test library performance
+
+=head1 SYNOPSIS
+
+B<openssl speed>
+[B<-help>]
+[B<-engine> I<id>]
+[B<-elapsed>]
+[B<-evp> I<algo>]
+[B<-hmac> I<algo>]
+[B<-cmac> I<algo>]
+[B<-decrypt>]
+[B<-primes> I<num>]
+[B<-seconds> I<num>]
+[B<-bytes> I<num>]
+{- $OpenSSL::safe::opt_r_synopsis -}
+[I<algorithm> ...]
+
+=for openssl ifdef cmac multi async_jobs engine
+
+=head1 DESCRIPTION
+
+This command is used to test the performance of cryptographic algorithms.
+To see the list of supported algorithms, use C<openssl list -digest-commands>
+or C<openssl list -cipher-commands> command. The global CSPRNG is denoted by
+the B<rand> algorithm name.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-engine> I<id>
+
+Specifying an engine (by its unique I<id> string) will cause this command
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-elapsed>
+
+When calculating operations- or bytes-per-second, use wall-clock time
+instead of CPU user time as divisor. It can be useful when testing speed
+of hardware engines.
+
+=item B<-evp> I<algo>
+
+Use the specified cipher or message digest algorithm via the EVP interface.
+If I<algo> is an AEAD cipher, then you can pass B<-aead> to benchmark a
+TLS-like sequence. And if I<algo> is a multi-buffer capable cipher, e.g.
+aes-128-cbc-hmac-sha1, then B<-mb> will time multi-buffer operation.
+
+=item B<-hmac> I<digest>
+
+Time the HMAC algorithm using the specified message digest.
+
+=item B<-cmac> I<cipher>
+
+Time the CMAC algorithm using the specified cipher e.g.
+C<openssl speed -cmac aes128>.
+
+=item B<-decrypt>
+
+Time the decryption instead of encryption. Affects only the EVP testing.
+
+=item B<-primes> I<num>
+
+Generate a I<num>-prime RSA key and use it to run the benchmarks. This option
+is only effective if RSA algorithm is specified to test.
+
+=item B<-seconds> I<num>
+
+Run benchmarks for I<num> seconds.
+
+=item B<-bytes> I<num>
+
+Run benchmarks on I<num>-byte buffers. Affects ciphers, digests and the CSPRNG.
+
+{- $OpenSSL::safe::opt_r_item -}
+
+=item I<algorithm> ...
+
+If any I<algorithm> is given, then those algorithms are tested, otherwise a
+pre-compiled grand selection is tested.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut