From: Daiki Ueno <ueno@gnu.org>
Date: Tue, 4 Jan 2022 08:06:21 +0000 (+0100)
Subject: doc: generate texinfo files from JSON
X-Git-Tag: 3.7.3~3^2~6
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=bf78b2258ea8c3392a85014bc828739b0a32e2c8;p=thirdparty%2Fgnutls.git

doc: generate texinfo files from JSON

This replaces texinfo generation previously provided by the autogen
-Tagtexi.tpl command with a Python script (gen-cmd-texi.py).

Signed-off-by: Daiki Ueno <ueno@gnu.org>
---

diff --git a/.gitignore b/.gitignore
index 2db1af4870..dd1373a57d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -110,7 +110,6 @@ doc/gnutls.vr
 doc/gnutls.vrs
 doc/gnutls.xml
 doc/ia-api.texi
-doc/invoke-*.menu
 doc/invoke-*.texi
 doc/latex/cha-tokens.tex
 doc/latex/cha-upgrade.tex
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ab414add8b..833c75ef6e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -40,108 +40,121 @@ endif
 
 -include $(top_srcdir)/doc/doc.mk
 
-invoke-gnutls-cli.texi: $(top_srcdir)/src/cli-args.def
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	mv -f $@.tmp $@
-
-invoke-gnutls-cli-debug.texi: $(top_srcdir)/src/cli-debug-args.def invoke-gnutls-cli.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	mv -f $@.tmp $@
-
-invoke-gnutls-serv.texi: $(top_srcdir)/src/serv-args.def invoke-gnutls-cli-debug.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	mv -f $@.tmp $@
-
-invoke-certtool.texi: $(top_srcdir)/src/certtool-args.def invoke-gnutls-serv.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) -e 's/@subheading/@subsubheading/g' \
-	    -e 's/@section/@subsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-ocsptool.texi: $(top_srcdir)/src/ocsptool-args.def invoke-certtool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) -e 's/@subheading/@subsubheading/g' \
-	    -e 's/@section/@subsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-danetool.texi: $(top_srcdir)/src/danetool-args.def invoke-ocsptool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) -e 's/@subheading/@subsubheading/g' \
-	    -e 's/@section/@subsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-srptool.texi: $(top_srcdir)/src/srptool-args.def invoke-danetool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) -e 's/@subheading/@subsubheading/g' \
-	    -e 's/@section/@subsubsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-psktool.texi: $(top_srcdir)/src/psktool-args.def invoke-srptool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) -e 's/@subheading/@subsubheading/g' \
-	    -e 's/@section/@subsubsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-p11tool.texi: $(top_srcdir)/src/p11tool-args.def invoke-psktool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) \
-	    -e 's/@subsection/@subsubheading/g' \
-	    -e 's/@section/@subsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
-
-invoke-tpmtool.texi: $(top_srcdir)/src/tpmtool-args.def invoke-p11tool.texi
-	PATH="$(top_builddir)/src/$(PATH_SEPARATOR)$${PATH}$(PATH_SEPARATOR)" $(AUTOGEN) -L$(top_builddir)/src -Tagtexi-cmd.tpl $<; \
-	if [ ! -e $@ ]; then \
-		cp $(srcdir)/$@ .; \
-	fi; \
-	$(srcdir)/scripts/cleanup-autogen.pl < $@ > $@.tmp && \
-	rm -f $@ && \
-	$(SED) \
-	    -e 's/@subsection/@subsubheading/g' \
-	    -e 's/@section/@subsection/g' $@.tmp > $@ && \
-	rm -f $@.tmp
+INVOKE_GNUTLS_CLI_TEXI_DEPS = gnutls-cli-see-also.texi gnutls-cli-examples.texi
+EXTRA_DIST += $(INVOKE_GNUTLS_CLI_TEXI_DEPS)
+invoke-gnutls-cli.texi: $(INVOKE_GNUTLS_CLI_TEXI_DEPS)
+invoke-gnutls-cli.texi: $(top_srcdir)/src/gnutls-cli-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/gnutls-cli-see-also.texi \
+		--examples $(srcdir)/gnutls-cli-examples.texi \
+		$< $@
+
+INVOKE_GNUTLS_CLI_DEBUG_TEXI_DEPS = gnutls-cli-debug-see-also.texi gnutls-cli-debug-examples.texi
+EXTRA_DIST += $(INVOKE_GNUTLS_CLI_DEBUG_TEXI_DEPS)
+invoke-gnutls-cli-debug.texi: $(INVOKE_GNUTLS_CLI_DEBUG_TEXI_DEPS)
+invoke-gnutls-cli-debug.texi: $(top_srcdir)/src/gnutls-cli-debug-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/gnutls-cli-debug-see-also.texi \
+		--examples $(srcdir)/gnutls-cli-debug-examples.texi \
+		$< $@
+
+INVOKE_GNUTLS_SERV_TEXI_DEPS = gnutls-serv-see-also.texi gnutls-serv-examples.texi
+EXTRA_DIST += $(INVOKE_GNUTLS_SERV_TEXI_DEPS)
+invoke-gnutls-serv.texi: $(INVOKE_GNUTLS_SERV_TEXI_DEPS)
+invoke-gnutls-serv.texi: $(top_srcdir)/src/gnutls-serv-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/gnutls-serv-see-also.texi \
+		--examples $(srcdir)/gnutls-serv-examples.texi \
+		$< $@
+
+INVOKE_CERTTOOL_TEXI_DEPS = certtool-see-also.texi certtool-examples.texi certtool-files.texi
+EXTRA_DIST += $(INVOKE_CERTTOOL_TEXI_DEPS)
+invoke-certtool.texi: $(INVOKE_CERTTOOL_TEXI_DEPS)
+invoke-certtool.texi: $(top_srcdir)/src/certtool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/certtool-see-also.texi \
+		--examples $(srcdir)/certtool-examples.texi \
+		--files $(srcdir)/certtool-files.texi \
+		--level 1 \
+		--section-node \
+		$< $@
+
+INVOKE_OCSPTOOL_TEXI_DEPS = ocsptool-see-also.texi ocsptool-examples.texi ocsptool-description.texi
+EXTRA_DIST += $(INVOKE_OCSPTOOL_TEXI_DEPS)
+invoke-ocsptool.texi: $(INVOKE_OCSPTOOL_TEXI_DEPS)
+invoke-ocsptool.texi: $(top_srcdir)/src/ocsptool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/ocsptool-see-also.texi \
+		--examples $(srcdir)/ocsptool-examples.texi \
+		--description $(srcdir)/ocsptool-description.texi \
+		--level 1 \
+		--section-node \
+		$< $@
+
+INVOKE_DANETOOL_TEXI_DEPS = danetool-see-also.texi danetool-examples.texi
+EXTRA_DIST += $(INVOKE_DANETOOL_TEXI_DEPS)
+invoke-danetool.texi: $(INVOKE_DANETOOL_TEXI_DEPS)
+invoke-danetool.texi: $(top_srcdir)/src/danetool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/danetool-see-also.texi \
+		--examples $(srcdir)/danetool-examples.texi \
+		--level 1 \
+		--section-node \
+		$< $@
+
+INVOKE_SRPTOOL_TEXI_DEPS = srptool-see-also.texi srptool-examples.texi
+EXTRA_DIST += $(INVOKE_SRPTOOL_TEXI_DEPS)
+invoke-srptool.texi: $(INVOKE_SRPTOOL_TEXI_DEPS)
+invoke-srptool.texi: $(top_srcdir)/src/srptool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/srptool-see-also.texi \
+		--examples $(srcdir)/srptool-examples.texi \
+		--level 2 \
+		--section-node \
+		$< $@
+
+INVOKE_PSKTOOL_TEXI_DEPS = psktool-see-also.texi psktool-examples.texi
+EXTRA_DIST += $(INVOKE_PSKTOOL_TEXI_DEPS)
+invoke-psktool.texi: $(INVOKE_PSKTOOL_TEXI_DEPS)
+invoke-psktool.texi: $(top_srcdir)/src/psktool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/psktool-see-also.texi \
+		--examples $(srcdir)/psktool-examples.texi \
+		--level 2 \
+		--section-node \
+		$< $@
+
+INVOKE_P11TOOL_TEXI_DEPS = p11tool-see-also.texi p11tool-examples.texi
+EXTRA_DIST += $(INVOKE_P11TOOL_TEXI_DEPS)
+invoke-p11tool.texi: $(INVOKE_P11TOOL_TEXI_DEPS)
+invoke-p11tool.texi: $(top_srcdir)/src/p11tool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/p11tool-see-also.texi \
+		--examples $(srcdir)/p11tool-examples.texi \
+		--level 1 \
+		--section-node \
+		$< $@
+
+INVOKE_TPMTOOL_TEXI_DEPS = tpmtool-see-also.texi tpmtool-examples.texi
+EXTRA_DIST += $(INVOKE_TPMTOOL_TEXI_DEPS)
+invoke-tpmtool.texi: $(INVOKE_TPMTOOL_TEXI_DEPS)
+invoke-tpmtool.texi: $(top_srcdir)/src/tpmtool-options.json
+	$(AM_V_GEN) PYTHONPATH='$(top_srcdir)/python' \
+		$(PYTHON) $(srcdir)/scripts/gen-cmd-texi.py \
+		--see-also $(srcdir)/tpmtool-see-also.texi \
+		--examples $(srcdir)/tpmtool-examples.texi \
+		--level 1 \
+		--section-node \
+		$< $@
 
 
 info_TEXINFOS = gnutls.texi gnutls-guile.texi
@@ -159,6 +172,8 @@ AUTOGENED_DOC = invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
 	invoke-ocsptool.texi invoke-psktool.texi invoke-p11tool.texi \
 	invoke-tpmtool.texi invoke-danetool.texi
 
+$(AUTOGENED_DOC): $(srcdir)/scripts/gen-cmd-texi.py
+
 gnutls_TEXINFOS += stamp_functions
 
 # Examples.
diff --git a/doc/certtool-examples.texi b/doc/certtool-examples.texi
new file mode 100644
index 0000000000..c24df9b706
--- /dev/null
+++ b/doc/certtool-examples.texi
@@ -0,0 +1,136 @@
+@subheading Generating private keys
+To create an RSA private key, run:
+@example
+$ certtool --generate-privkey --outfile key.pem --rsa
+@end example
+
+To create a DSA or elliptic curves (ECDSA) private key use the
+above command combined with 'dsa' or 'ecc' options.
+
+@subheading Generating certificate requests
+To create a certificate request (needed when the certificate is  issued  by
+another party), run:
+@example
+certtool --generate-request --load-privkey key.pem \
+   --outfile request.pem
+@end example
+
+If the private key is stored in a smart card you can generate
+a request by specifying the private key object URL.
+@example
+$ ./certtool --generate-request --load-privkey "pkcs11:..." \
+  --load-pubkey "pkcs11:..." --outfile request.pem
+@end example
+
+
+@subheading Generating a self-signed certificate
+To create a self signed certificate, use the command:
+@example
+$ certtool --generate-privkey --outfile ca-key.pem
+$ certtool --generate-self-signed --load-privkey ca-key.pem \
+   --outfile ca-cert.pem
+@end example
+
+Note that a self-signed certificate usually belongs to a certificate
+authority, that signs other certificates.
+
+@subheading Generating a certificate
+To generate a certificate using the previous request, use the command:
+@example
+$ certtool --generate-certificate --load-request request.pem \
+   --outfile cert.pem --load-ca-certificate ca-cert.pem \
+   --load-ca-privkey ca-key.pem
+@end example
+
+To generate a certificate using the private key only, use the command:
+@example
+$ certtool --generate-certificate --load-privkey key.pem \
+   --outfile cert.pem --load-ca-certificate ca-cert.pem \
+   --load-ca-privkey ca-key.pem
+@end example
+
+@subheading Certificate information
+To view the certificate information, use:
+@example
+$ certtool --certificate-info --infile cert.pem
+@end example
+
+@subheading Changing the certificate format
+To convert the certificate from PEM to DER format, use:
+@example
+$ certtool --certificate-info --infile cert.pem --outder --outfile cert.der
+@end example
+
+@subheading PKCS #12 structure generation
+To generate a PKCS #12 structure using the previous key and certificate,
+use the command:
+@example
+$ certtool --load-certificate cert.pem --load-privkey key.pem \
+   --to-p12 --outder --outfile key.p12
+@end example
+
+Some tools (reportedly web browsers) have problems with that file
+because it does not contain the CA certificate for the certificate.
+To work around that problem in the tool, you can use the
+--load-ca-certificate parameter as follows:
+
+@example
+$ certtool --load-ca-certificate ca.pem \
+  --load-certificate cert.pem --load-privkey key.pem \
+  --to-p12 --outder --outfile key.p12
+@end example
+
+@subheading Obtaining Diffie-Hellman parameters
+To obtain the RFC7919 parameters for Diffie-Hellman key exchange, use the command:
+@example
+$ certtool --get-dh-params --outfile dh.pem --sec-param medium
+@end example
+
+@subheading Verifying a certificate
+To verify a certificate in a file against the system's CA trust store
+use the following command:
+@example
+$ certtool --verify --infile cert.pem
+@end example
+
+It is also possible to simulate hostname verification with the following
+options:
+@example
+$ certtool --verify --verify-hostname www.example.com --infile cert.pem
+@end example
+
+
+@subheading Proxy certificate generation
+Proxy certificate can be used to delegate your credential to a
+temporary, typically short-lived, certificate.  To create one from the
+previously created certificate, first create a temporary key and then
+generate a proxy certificate for it, using the commands:
+
+@example
+$ certtool --generate-privkey > proxy-key.pem
+$ certtool --generate-proxy --load-ca-privkey key.pem \
+  --load-privkey proxy-key.pem --load-certificate cert.pem \
+  --outfile proxy-cert.pem
+@end example
+
+@subheading Certificate revocation list generation
+To create an empty Certificate Revocation List (CRL) do:
+
+@example
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+           --load-ca-certificate x509-ca.pem
+@end example
+
+To create a CRL that contains some revoked certificates, place the
+certificates in a file and use @code{--load-certificate} as follows:
+
+@example
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+  --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
+@end example
+
+To verify a Certificate Revocation List (CRL) do:
+
+@example
+$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
+@end example
diff --git a/doc/certtool-files.texi b/doc/certtool-files.texi
new file mode 100644
index 0000000000..56d3fbe03e
--- /dev/null
+++ b/doc/certtool-files.texi
@@ -0,0 +1,321 @@
+@subheading Certtool's template file format
+A template file can be used to avoid the interactive questions of
+certtool. Initially create a file named 'cert.cfg' that contains the information
+about the certificate. The template can be used as below:
+
+@example
+$ certtool --generate-certificate --load-privkey key.pem  \
+   --template cert.cfg --outfile cert.pem \
+   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
+@end example
+
+An example certtool template file that can be used to generate a certificate
+request or a self signed certificate follows.
+
+@example
+# X.509 Certificate options
+#
+# DN options
+
+# The organization of the subject.
+organization = "Koko inc."
+
+# The organizational unit of the subject.
+unit = "sleeping dept."
+
+# The locality of the subject.
+# locality =
+
+# The state of the certificate owner.
+state = "Attiki"
+
+# The country of the subject. Two letter code.
+country = GR
+
+# The common name of the certificate owner.
+cn = "Cindy Lauper"
+
+# A user id of the certificate owner.
+#uid = "clauper"
+
+# Set domain components
+#dc = "name"
+#dc = "domain"
+
+# If the supported DN OIDs are not adequate you can set
+# any OID here.
+# For example set the X.520 Title and the X.520 Pseudonym
+# by using OID and string pairs.
+#dn_oid = "2.5.4.12 Dr."
+#dn_oid = "2.5.4.65 jackal"
+
+# This is deprecated and should not be used in new
+# certificates.
+# pkcs9_email = "none@@none.org"
+
+# An alternative way to set the certificate's distinguished name directly
+# is with the "dn" option. The attribute names allowed are:
+# C (country), street, O (organization), OU (unit), title, CN (common name),
+# L (locality), ST (state), placeOfBirth, gender, countryOfCitizenship, 
+# countryOfResidence, serialNumber, telephoneNumber, surName, initials, 
+# generationQualifier, givenName, pseudonym, dnQualifier, postalCode, name, 
+# businessCategory, DC, UID, jurisdictionOfIncorporationLocalityName, 
+# jurisdictionOfIncorporationStateOrProvinceName,
+# jurisdictionOfIncorporationCountryName, XmppAddr, and numeric OIDs.
+
+#dn = "cn = Nikos,st = New\, Something,C=GR,surName=Mavrogiannopoulos,2.5.4.9=Arkadias"
+
+# The serial number of the certificate
+# The value is in decimal (i.e. 1963) or hex (i.e. 0x07ab).
+# Comment the field for a random serial number.
+serial = 007
+
+# In how many days, counting from today, this certificate will expire.
+# Use -1 if there is no expiration date.
+expiration_days = 700
+
+# Alternatively you may set concrete dates and time. The GNU date string 
+# formats are accepted. See:
+# https://www.gnu.org/software/tar/manual/html_node/Date-input-formats.html
+
+#activation_date = "2004-02-29 16:21:42"
+#expiration_date = "2025-02-29 16:24:41"
+
+# X.509 v3 extensions
+
+# A dnsname in case of a WWW server.
+#dns_name = "www.none.org"
+#dns_name = "www.morethanone.org"
+
+# An othername defined by an OID and a hex encoded string
+#other_name = "1.3.6.1.5.2.2 302ca00d1b0b56414e5245494e2e4f5247a11b3019a006020400000002a10f300d1b047269636b1b0561646d696e"
+#other_name_utf8 = "1.2.4.5.6 A UTF8 string"
+#other_name_octet = "1.2.4.5.6 A string that will be encoded as ASN.1 octet string"
+
+# Allows writing an XmppAddr Identifier
+#xmpp_name = juliet@@im.example.com
+
+# Names used in PKINIT
+#krb5_principal = user@@REALM.COM
+#krb5_principal = HTTP/user@@REALM.COM
+
+# A subject alternative name URI
+#uri = "https://www.example.com"
+
+# An IP address in case of a server.
+#ip_address = "192.168.1.1"
+
+# An email in case of a person
+email = "none@@none.org"
+
+# TLS feature (rfc7633) extension. That can is used to indicate mandatory TLS
+# extension features to be provided by the server. In practice this is used
+# to require the Status Request (extid: 5) extension from the server. That is,
+# to require the server holding this certificate to provide a stapled OCSP response.
+# You can have multiple lines for multiple TLS features.
+
+# To ask for OCSP status request use:
+#tls_feature = 5
+
+# Challenge password used in certificate requests
+challenge_password = 123456
+
+# Password when encrypting a private key
+#password = secret
+
+# An URL that has CRLs (certificate revocation lists)
+# available. Needed in CA certificates.
+#crl_dist_points = "https://www.getcrl.crl/getcrl/"
+
+# Whether this is a CA certificate or not
+#ca
+
+# Subject Unique ID (in hex)
+#subject_unique_id = 00153224
+
+# Issuer Unique ID (in hex)
+#issuer_unique_id = 00153225
+
+#### Key usage
+
+# The following key usage flags are used by CAs and end certificates
+
+# Whether this certificate will be used to sign data (needed
+# in TLS DHE ciphersuites). This is the digitalSignature flag
+# in RFC5280 terminology.
+signing_key
+
+# Whether this certificate will be used to encrypt data (needed
+# in TLS RSA ciphersuites). Note that it is preferred to use different
+# keys for encryption and signing. This is the keyEncipherment flag
+# in RFC5280 terminology.
+encryption_key
+
+# Whether this key will be used to sign other certificates. The
+# keyCertSign flag in RFC5280 terminology.
+#cert_signing_key
+
+# Whether this key will be used to sign CRLs. The
+# cRLSign flag in RFC5280 terminology.
+#crl_signing_key
+
+# The keyAgreement flag of RFC5280. Its purpose is loosely
+# defined. Not use it unless required by a protocol.
+#key_agreement
+
+# The dataEncipherment flag of RFC5280. Its purpose is loosely
+# defined. Not use it unless required by a protocol.
+#data_encipherment
+
+# The nonRepudiation flag of RFC5280. Its purpose is loosely
+# defined. Not use it unless required by a protocol.
+#non_repudiation
+
+#### Extended key usage (key purposes)
+
+# The following extensions are used in an end certificate
+# to clarify its purpose. Some CAs also use it to indicate
+# the types of certificates they are purposed to sign.
+
+
+# Whether this certificate will be used for a TLS client;
+# this sets the id-kp-clientAuth (1.3.6.1.5.5.7.3.2) of
+# extended key usage.
+#tls_www_client
+
+# Whether this certificate will be used for a TLS server;
+# this sets the id-kp-serverAuth (1.3.6.1.5.5.7.3.1) of
+# extended key usage.
+#tls_www_server
+
+# Whether this key will be used to sign code. This sets the
+# id-kp-codeSigning (1.3.6.1.5.5.7.3.3) of extended key usage
+# extension.
+#code_signing_key
+
+# Whether this key will be used to sign OCSP data. This sets the
+# id-kp-OCSPSigning (1.3.6.1.5.5.7.3.9) of extended key usage extension.
+#ocsp_signing_key
+
+# Whether this key will be used for time stamping. This sets the
+# id-kp-timeStamping (1.3.6.1.5.5.7.3.8) of extended key usage extension.
+#time_stamping_key
+
+# Whether this key will be used for email protection. This sets the
+# id-kp-emailProtection (1.3.6.1.5.5.7.3.4) of extended key usage extension.
+#email_protection_key
+
+# Whether this key will be used for IPsec IKE operations (1.3.6.1.5.5.7.3.17).
+#ipsec_ike_key
+
+## adding custom key purpose OIDs
+
+# for microsoft smart card logon
+# key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
+
+# for email protection
+# key_purpose_oid = 1.3.6.1.5.5.7.3.4
+
+# for any purpose (must not be used in intermediate CA certificates)
+# key_purpose_oid = 2.5.29.37.0
+
+### end of key purpose OIDs
+
+### Adding arbitrary extensions
+# This requires to provide the extension OIDs, as well as the extension data in
+# hex format. The following two options are available since GnuTLS 3.5.3.
+#add_extension = "1.2.3.4 0x0AAB01ACFE"
+
+# As above but encode the data as an octet string
+#add_extension = "1.2.3.4 octet_string(0x0AAB01ACFE)"
+
+# For portability critical extensions shouldn't be set to certificates.
+#add_critical_extension = "5.6.7.8 0x1AAB01ACFE"
+
+# When generating a certificate from a certificate
+# request, then honor the extensions stored in the request
+# and store them in the real certificate.
+#honor_crq_extensions
+
+# Alternatively only specific extensions can be copied.
+#honor_crq_ext = 2.5.29.17
+#honor_crq_ext = 2.5.29.15
+
+# Path length constraint. Sets the maximum number of
+# certificates that can be used to certify this certificate.
+# (i.e. the certificate chain length)
+#path_len = -1
+#path_len = 2
+
+# OCSP URI
+# ocsp_uri = https://my.ocsp.server/ocsp
+
+# CA issuers URI
+# ca_issuers_uri = https://my.ca.issuer
+
+# Certificate policies
+#policy1 = 1.3.6.1.4.1.5484.1.10.99.1.0
+#policy1_txt = "This is a long policy to summarize"
+#policy1_url = https://www.example.com/a-policy-to-read
+
+#policy2 = 1.3.6.1.4.1.5484.1.10.99.1.1
+#policy2_txt = "This is a short policy"
+#policy2_url = https://www.example.com/another-policy-to-read
+
+# The number of additional certificates that may appear in a
+# path before the anyPolicy is no longer acceptable.
+#inhibit_anypolicy_skip_certs 1
+
+# Name constraints
+
+# DNS
+#nc_permit_dns = example.com
+#nc_exclude_dns = test.example.com
+
+# EMAIL
+#nc_permit_email = "nmav@@ex.net"
+
+# Exclude subdomains of example.com
+#nc_exclude_email = .example.com
+
+# Exclude all e-mail addresses of example.com
+#nc_exclude_email = example.com
+
+# IP
+#nc_permit_ip = 192.168.0.0/16
+#nc_exclude_ip = 192.168.5.0/24
+#nc_permit_ip = fc0a:eef2:e7e7:a56e::/64
+
+
+# Options for proxy certificates
+#proxy_policy_language = 1.3.6.1.5.5.7.21.1
+
+
+# Options for generating a CRL
+
+# The number of days the next CRL update will be due.
+# next CRL update will be in 43 days
+#crl_next_update = 43
+
+# this is the 5th CRL by this CA
+# The value is in decimal (i.e. 1963) or hex (i.e. 0x07ab).
+# Comment the field for a time-based number.
+# Time-based CRL numbers generated in GnuTLS 3.6.3 and later
+# are significantly larger than those generated in previous
+# versions. Since CRL numbers need to be monotonic, you need
+# to specify the CRL number here manually if you intend to
+# downgrade to an earlier version than 3.6.3 after publishing
+# the CRL as it is not possible to specify CRL numbers greater
+# than 2**63-2 using hex notation in those versions.
+#crl_number = 5
+
+# Specify the update dates more precisely.
+#crl_this_update_date = "2004-02-29 16:21:42"
+#crl_next_update_date = "2025-02-29 16:24:41"
+
+# The date that the certificates will be made seen as
+# being revoked.
+#crl_revocation_date = "2025-02-29 16:24:41"
+
+@end example
+
diff --git a/doc/certtool-see-also.texi b/doc/certtool-see-also.texi
new file mode 100644
index 0000000000..f9b0e55734
--- /dev/null
+++ b/doc/certtool-see-also.texi
@@ -0,0 +1 @@
+    p11tool (1), psktool (1), srptool (1)
diff --git a/doc/danetool-examples.texi b/doc/danetool-examples.texi
new file mode 100644
index 0000000000..1c5ec786ef
--- /dev/null
+++ b/doc/danetool-examples.texi
@@ -0,0 +1,39 @@
+@subheading DANE TLSA RR generation
+
+To create a DANE TLSA resource record for a certificate (or public key) 
+that was issued localy and may or may not be signed by a CA use the following command.
+@example
+$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
+@end example
+
+To create a DANE TLSA resource record for a CA signed certificate, which will
+be marked as such use the following command.
+@example
+$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
+  --no-domain
+@end example
+
+The former is useful to add in your DNS entry even if your certificate is signed 
+by a CA. That way even users who do not trust your CA will be able to verify your
+certificate using DANE.
+
+In order to create a record for the CA signer of your certificate use the following.
+@example
+$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
+  --ca --no-domain
+@end example
+
+To read a server's DANE TLSA entry, use:
+@example
+$ danetool --check www.example.com --proto tcp --port 443
+@end example
+
+To verify an HTTPS server's DANE TLSA entry, use:
+@example
+$ danetool --check www.example.com --proto tcp --port 443 --load-certificate chain.pem
+@end example
+
+To verify an SMTP server's DANE TLSA entry, use:
+@example
+$ danetool --check www.example.com --proto tcp --starttls-proto=smtp --load-certificate chain.pem
+@end example
diff --git a/doc/danetool-see-also.texi b/doc/danetool-see-also.texi
new file mode 100644
index 0000000000..6647d5ae32
--- /dev/null
+++ b/doc/danetool-see-also.texi
@@ -0,0 +1 @@
+    certtool (1)
diff --git a/doc/gnutls-cli-debug-examples.texi b/doc/gnutls-cli-debug-examples.texi
new file mode 100644
index 0000000000..5114fc0673
--- /dev/null
+++ b/doc/gnutls-cli-debug-examples.texi
@@ -0,0 +1,56 @@
+@example
+$ gnutls-cli-debug localhost
+GnuTLS debug client 3.5.0
+Checking localhost:443
+                             for SSL 3.0 (RFC6101) support... yes
+                        whether we need to disable TLS 1.2... no
+                        whether we need to disable TLS 1.1... no
+                        whether we need to disable TLS 1.0... no
+                        whether %NO_EXTENSIONS is required... no
+                               whether %COMPAT is required... no
+                             for TLS 1.0 (RFC2246) support... yes
+                             for TLS 1.1 (RFC4346) support... yes
+                             for TLS 1.2 (RFC5246) support... yes
+                                  fallback from TLS 1.6 to... TLS1.2
+                        for RFC7507 inappropriate fallback... yes
+                                     for HTTPS server name... Local
+                               for certificate chain order... sorted
+                  for safe renegotiation (RFC5746) support... yes
+                     for Safe renegotiation support (SCSV)... no
+                    for encrypt-then-MAC (RFC7366) support... no
+                   for ext master secret (RFC7627) support... no
+                           for heartbeat (RFC6520) support... no
+                       for version rollback bug in RSA PMS... dunno
+                  for version rollback bug in Client Hello... no
+            whether the server ignores the RSA PMS version... yes
+whether small records (512 bytes) are tolerated on handshake... yes
+    whether cipher suites not in SSL 3.0 spec are accepted... yes
+whether a bogus TLS record version in the client hello is accepted... yes
+         whether the server understands TLS closure alerts... partially
+            whether the server supports session resumption... yes
+                      for anonymous authentication support... no
+                      for ephemeral Diffie-Hellman support... no
+                   for ephemeral EC Diffie-Hellman support... yes
+                    ephemeral EC Diffie-Hellman group info... SECP256R1
+                  for AES-128-GCM cipher (RFC5288) support... yes
+                  for AES-128-CCM cipher (RFC6655) support... no
+                for AES-128-CCM-8 cipher (RFC6655) support... no
+                  for AES-128-CBC cipher (RFC3268) support... yes
+             for CAMELLIA-128-GCM cipher (RFC6367) support... no
+             for CAMELLIA-128-CBC cipher (RFC5932) support... no
+                     for 3DES-CBC cipher (RFC2246) support... yes
+                  for ARCFOUR 128 cipher (RFC2246) support... yes
+                                       for MD5 MAC support... yes
+                                      for SHA1 MAC support... yes
+                                    for SHA256 MAC support... yes
+                              for ZLIB compression support... no
+                     for max record size (RFC6066) support... no
+                for OCSP status response (RFC6066) support... no
+              for OpenPGP authentication (RFC6091) support... no
+@end example
+
+You could also use the client to debug services with starttls capability.
+@example
+$ gnutls-cli-debug --starttls-proto smtp --port 25 localhost
+@end example
+
diff --git a/doc/gnutls-cli-debug-see-also.texi b/doc/gnutls-cli-debug-see-also.texi
new file mode 100644
index 0000000000..ab20906b44
--- /dev/null
+++ b/doc/gnutls-cli-debug-see-also.texi
@@ -0,0 +1 @@
+gnutls-cli(1), gnutls-serv(1)
diff --git a/doc/gnutls-cli-examples.texi b/doc/gnutls-cli-examples.texi
new file mode 100644
index 0000000000..9eec1aae8c
--- /dev/null
+++ b/doc/gnutls-cli-examples.texi
@@ -0,0 +1,99 @@
+@subheading Connecting using PSK authentication
+To connect to a server using PSK authentication, you need to enable the choice of PSK by using a cipher priority parameter such as in the example below. 
+@example
+$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
+    --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
+    --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
+Resolving 'localhost'...
+Connecting to '127.0.0.1:5556'...
+- PSK authentication.
+- Version: TLS1.1
+- Key Exchange: PSK
+- Cipher: AES-128-CBC
+- MAC: SHA1
+- Compression: NULL
+- Handshake was completed
+    
+- Simple Client Mode:
+@end example
+By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.
+
+@subheading Connecting using raw public-key authentication
+To connect to a server using raw public-key authentication, you need to enable the option to negotiate raw public-keys via the priority strings such as in the example below. 
+@example
+$ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK \
+    --rawpkkeyfile cli.key.pem \
+    --rawpkfile cli.rawpk.pem
+Processed 1 client raw public key pair...
+Resolving 'localhost'...
+Connecting to '127.0.0.1:5556'...
+- Successfully sent 1 certificate(s) to server.
+- Server has requested a certificate.
+- Certificate type: X.509
+- Got a certificate list of 1 certificates.
+- Certificate[0] info:
+ - skipped
+- Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
+- Options:
+- Handshake was completed
+    
+- Simple Client Mode:
+@end example
+
+@subheading Connecting to STARTTLS services
+
+You could also use the client to connect to services with starttls capability.
+@example
+$ gnutls-cli --starttls-proto smtp --port 25 localhost
+@end example
+
+@subheading Listing ciphersuites in a priority string
+To list the ciphersuites in a priority string:
+@example
+$ ./gnutls-cli --priority SECURE192 -l
+Cipher suites for SECURE192
+TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24	TLS1.2
+TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e	TLS1.2
+TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30	TLS1.2
+TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b	TLS1.2
+TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a	TLS1.2
+TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d	TLS1.2
+
+Certificate types: CTYPE-X.509
+Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
+Compression: COMP-NULL
+Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
+PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
+@end example
+
+@subheading Connecting using a PKCS #11 token
+To connect to a server using a certificate and a private key present in a PKCS #11 token you 
+need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
+
+Those can be found using "p11tool --list-tokens" and then listing all the objects in the
+needed token, and using the appropriate.
+@example
+$ p11tool --list-tokens
+
+Token 0:
+	URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
+	Label: Test
+	Manufacturer: EnterSafe
+	Model: PKCS15
+	Serial: 1234
+
+$ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
+
+Object 0:
+	URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
+	Type: X.509 Certificate
+	Label: client
+	ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
+
+$ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
+$ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
+$ export MYCERT MYKEY
+
+$ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
+@end example
+Notice that the private key only differs from the certificate in the type.
diff --git a/doc/gnutls-cli-see-also.texi b/doc/gnutls-cli-see-also.texi
new file mode 100644
index 0000000000..589896282f
--- /dev/null
+++ b/doc/gnutls-cli-see-also.texi
@@ -0,0 +1 @@
+gnutls-cli-debug(1), gnutls-serv(1)
diff --git a/doc/gnutls-serv-examples.texi b/doc/gnutls-serv-examples.texi
new file mode 100644
index 0000000000..6dd2d75c8f
--- /dev/null
+++ b/doc/gnutls-serv-examples.texi
@@ -0,0 +1,147 @@
+Running your own TLS server based on GnuTLS can be useful when
+debugging clients and/or GnuTLS itself.  This section describes how to
+use @code{gnutls-serv} as a simple HTTPS server.
+
+The most basic server can be started as:
+
+@example
+gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH"
+@end example
+
+It will only support anonymous ciphersuites, which many TLS clients
+refuse to use.
+
+The next step is to add support for X.509.  First we generate a CA:
+
+@example
+$ certtool --generate-privkey > x509-ca-key.pem
+$ echo 'cn = GnuTLS test CA' > ca.tmpl
+$ echo 'ca' >> ca.tmpl
+$ echo 'cert_signing_key' >> ca.tmpl
+$ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
+  --template ca.tmpl --outfile x509-ca.pem
+@end example
+
+Then generate a server certificate.  Remember to change the dns_name
+value to the name of your server host, or skip that command to avoid
+the field.
+
+@example
+$ certtool --generate-privkey > x509-server-key.pem
+$ echo 'organization = GnuTLS test server' > server.tmpl
+$ echo 'cn = test.gnutls.org' >> server.tmpl
+$ echo 'tls_www_server' >> server.tmpl
+$ echo 'encryption_key' >> server.tmpl
+$ echo 'signing_key' >> server.tmpl
+$ echo 'dns_name = test.gnutls.org' >> server.tmpl
+$ certtool --generate-certificate --load-privkey x509-server-key.pem \
+  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
+  --template server.tmpl --outfile x509-server.pem
+@end example
+
+For use in the client, you may want to generate a client certificate
+as well.
+
+@example
+$ certtool --generate-privkey > x509-client-key.pem
+$ echo 'cn = GnuTLS test client' > client.tmpl
+$ echo 'tls_www_client' >> client.tmpl
+$ echo 'encryption_key' >> client.tmpl
+$ echo 'signing_key' >> client.tmpl
+$ certtool --generate-certificate --load-privkey x509-client-key.pem \
+  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
+  --template client.tmpl --outfile x509-client.pem
+@end example
+
+To be able to import the client key/certificate into some
+applications, you will need to convert them into a PKCS#12 structure.
+This also encrypts the security sensitive key with a password.
+
+@example
+$ certtool --to-p12 --load-ca-certificate x509-ca.pem \
+  --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
+  --outder --outfile x509-client.p12
+@end example
+
+For icing, we'll create a proxy certificate for the client too.
+
+@example
+$ certtool --generate-privkey > x509-proxy-key.pem
+$ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
+$ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
+  --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
+  --load-certificate x509-client.pem --template proxy.tmpl \
+  --outfile x509-proxy.pem
+@end example
+
+Then start the server again:
+
+@example
+$ gnutls-serv --http \
+            --x509cafile x509-ca.pem \
+            --x509keyfile x509-server-key.pem \
+            --x509certfile x509-server.pem
+@end example
+
+Try connecting to the server using your web browser.  Note that the
+server listens to port 5556 by default.
+
+While you are at it, to allow connections using ECDSA, you can also
+create a ECDSA key and certificate for the server.  These credentials
+will be used in the final example below.
+
+@example
+$ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem
+$ certtool --generate-certificate --load-privkey x509-server-key-ecc.pem \
+  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
+  --template server.tmpl --outfile x509-server-ecc.pem
+@end example
+
+
+The next step is to add support for SRP authentication. This requires
+an SRP password file created with @code{srptool}.
+To start the server with SRP support:
+
+@example
+gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \
+            --srppasswdconf srp-tpasswd.conf \
+            --srppasswd srp-passwd.txt
+@end example
+
+Let's also start a server with support for PSK. This would require
+a password file created with @code{psktool}.
+
+@example
+gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \
+            --pskpasswd psk-passwd.txt
+@end example
+
+If you want a server with support for raw public-keys we can also add these
+credentials. Note however that there is no identity information linked to these
+keys as is the case with regular x509 certificates. Authentication must be done
+via different means. Also we need to explicitly enable raw public-key certificates
+via the priority strings.
+
+@example
+gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \
+            --rawpkfile srv.rawpk.pem \
+            --rawpkkeyfile srv.key.pem
+@end example
+
+
+Finally, we start the server with all the earlier parameters and you
+get this command:
+
+@example
+gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \
+            --x509cafile x509-ca.pem \
+            --x509keyfile x509-server-key.pem \
+            --x509certfile x509-server.pem \
+            --x509keyfile x509-server-key-ecc.pem \
+            --x509certfile x509-server-ecc.pem \
+            --srppasswdconf srp-tpasswd.conf \
+            --srppasswd srp-passwd.txt \
+            --pskpasswd psk-passwd.txt \
+            --rawpkfile srv.rawpk.pem \
+            --rawpkkeyfile srv.key.pem
+@end example
diff --git a/doc/gnutls-serv-see-also.texi b/doc/gnutls-serv-see-also.texi
new file mode 100644
index 0000000000..00d832b601
--- /dev/null
+++ b/doc/gnutls-serv-see-also.texi
@@ -0,0 +1 @@
+gnutls-cli-debug(1), gnutls-cli(1)
diff --git a/doc/ocsptool-description.texi b/doc/ocsptool-description.texi
new file mode 100644
index 0000000000..a7b080536c
--- /dev/null
+++ b/doc/ocsptool-description.texi
@@ -0,0 +1,6 @@
+@subheading On verification
+Responses are typically signed/issued by designated certificates or
+certificate authorities and thus this tool requires on verification
+the certificate of the issuer or the full certificate chain in order to
+determine the appropriate signing authority. The specified certificate
+of the issuer is assumed trusted.
diff --git a/doc/ocsptool-examples.texi b/doc/ocsptool-examples.texi
new file mode 100644
index 0000000000..38b5db7124
--- /dev/null
+++ b/doc/ocsptool-examples.texi
@@ -0,0 +1,128 @@
+@subheading Print information about an OCSP request
+
+To parse an OCSP request and print information about the content, the
+@code{-i} or @code{--request-info} parameter may be used as follows.
+The @code{-Q} parameter specify the name of the file containing the
+OCSP request, and it should contain the OCSP request in binary DER
+format.
+
+@example
+$ ocsptool -i -Q ocsp-request.der
+@end example
+
+The input file may also be sent to standard input like this:
+
+@example
+$ cat ocsp-request.der | ocsptool --request-info
+@end example
+
+@subheading Print information about an OCSP response
+
+Similar to parsing OCSP requests, OCSP responses can be parsed using
+the @code{-j} or @code{--response-info} as follows.
+
+@example
+$ ocsptool -j -Q ocsp-response.der
+$ cat ocsp-response.der | ocsptool --response-info
+@end example
+
+@subheading Generate an OCSP request
+
+The @code{-q} or @code{--generate-request} parameters are used to
+generate an OCSP request.  By default the OCSP request is written to
+standard output in binary DER format, but can be stored in a file
+using @code{--outfile}.  To generate an OCSP request the issuer of the
+certificate to check needs to be specified with @code{--load-issuer}
+and the certificate to check with @code{--load-cert}.  By default PEM
+format is used for these files, although @code{--inder} can be used to
+specify that the input files are in DER format.
+
+@example
+$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
+           --outfile ocsp-request.der
+@end example
+
+When generating OCSP requests, the tool will add an OCSP extension
+containing a nonce.  This behaviour can be disabled by specifying
+@code{--no-nonce}.
+
+@subheading Verify signature in OCSP response
+
+To verify the signature in an OCSP response the @code{-e} or
+@code{--verify-response} parameter is used.  The tool will read an
+OCSP response in DER format from standard input, or from the file
+specified by @code{--load-response}.  The OCSP response is verified
+against a set of trust anchors, which are specified using
+@code{--load-trust}.  The trust anchors are concatenated certificates
+in PEM format.  The certificate that signed the OCSP response needs to
+be in the set of trust anchors, or the issuer of the signer
+certificate needs to be in the set of trust anchors and the OCSP
+Extended Key Usage bit has to be asserted in the signer certificate.
+
+@example
+$ ocsptool -e --load-trust issuer.pem \
+           --load-response ocsp-response.der
+@end example
+
+The tool will print status of verification.
+
+@subheading Verify signature in OCSP response against given certificate
+
+It is possible to override the normal trust logic if you know that a
+certain certificate is supposed to have signed the OCSP response, and
+you want to use it to check the signature.  This is achieved using
+@code{--load-signer} instead of @code{--load-trust}.  This will load
+one certificate and it will be used to verify the signature in the
+OCSP response.  It will not check the Extended Key Usage bit.
+
+@example
+$ ocsptool -e --load-signer ocsp-signer.pem \
+           --load-response ocsp-response.der
+@end example
+
+This approach is normally only relevant in two situations.  The first
+is when the OCSP response does not contain a copy of the signer
+certificate, so the @code{--load-trust} code would fail.  The second
+is if you want to avoid the indirect mode where the OCSP response
+signer certificate is signed by a trust anchor.
+
+@subheading Real-world example
+
+Here is an example of how to generate an OCSP request for a
+certificate and to verify the response.  For illustration we'll use
+the @code{blog.josefsson.org} host, which (as of writing) uses a
+certificate from CACert.  First we'll use @code{gnutls-cli} to get a
+copy of the server certificate chain.  The server is not required to
+send this information, but this particular one is configured to do so.
+
+@example
+$ echo | gnutls-cli -p 443 blog.josefsson.org --save-cert chain.pem
+@end example
+
+The saved certificates normally contain a pointer to where the OCSP
+responder is located, in the Authority Information Access Information
+extension.  For example, from @code{certtool -i < chain.pem} there is
+this information:
+
+@example
+		Authority Information Access Information (not critical):
+			Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
+			Access Location URI: https://ocsp.CAcert.org/
+@end example
+
+This means that ocsptool can discover the servers to contact over HTTP.
+We can now request information on the chain certificates.
+
+@example
+$ ocsptool --ask --load-chain chain.pem
+@end example
+
+The request is sent via HTTP to the OCSP server address found in
+the certificates. It is possible to override the address of the
+OCSP server as well as ask information on a particular certificate
+using --load-cert and --load-issuer.
+
+@example
+$ ocsptool --ask https://ocsp.CAcert.org/ --load-chain chain.pem
+@end example
+
diff --git a/doc/ocsptool-see-also.texi b/doc/ocsptool-see-also.texi
new file mode 100644
index 0000000000..6647d5ae32
--- /dev/null
+++ b/doc/ocsptool-see-also.texi
@@ -0,0 +1 @@
+    certtool (1)
diff --git a/doc/p11tool-examples.texi b/doc/p11tool-examples.texi
new file mode 100644
index 0000000000..09871a94e1
--- /dev/null
+++ b/doc/p11tool-examples.texi
@@ -0,0 +1,34 @@
+To view all tokens in your system use:
+@example
+$ p11tool --list-tokens
+@end example
+
+To view all objects in a token use:
+@example
+$ p11tool --login --list-all "pkcs11:TOKEN-URL"
+@end example
+
+To store a private key and a certificate in a token run:
+@example
+$ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
+          --label "Mykey"
+$ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
+          --label "Mykey"
+@end example
+Note that some tokens require the same label to be used for the certificate
+and its corresponding private key.
+
+To generate an RSA private key inside the token use:
+@example
+$ p11tool --login --generate-privkey rsa --bits 1024 --label "MyNewKey" \
+          --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
+@end example
+The bits parameter in the above example is explicitly set because some
+tokens only support limited choices in the bit length. The output file is the
+corresponding public key. This key can be used to general a certificate
+request with certtool.
+@example
+certtool --generate-request --load-privkey "pkcs11:KEY-URL" \
+   --load-pubkey MyNewKey.pub --outfile request.pem
+@end example
+
diff --git a/doc/p11tool-see-also.texi b/doc/p11tool-see-also.texi
new file mode 100644
index 0000000000..6647d5ae32
--- /dev/null
+++ b/doc/p11tool-see-also.texi
@@ -0,0 +1 @@
+    certtool (1)
diff --git a/doc/psktool-examples.texi b/doc/psktool-examples.texi
new file mode 100644
index 0000000000..343464a2b8
--- /dev/null
+++ b/doc/psktool-examples.texi
@@ -0,0 +1,12 @@
+To add a user 'psk_identity' in @file{keys.psk} for use with GnuTLS run:
+@example
+$ ./psktool -u psk_identity -p keys.psk
+Generating a random key for user 'psk_identity'
+Key stored to keys.psk
+$ cat keys.psk
+psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
+$
+@end example
+
+This command will create @file{keys.psk} if it does not exist
+and will add user 'psk_identity'.
diff --git a/doc/psktool-see-also.texi b/doc/psktool-see-also.texi
new file mode 100644
index 0000000000..821c9e008a
--- /dev/null
+++ b/doc/psktool-see-also.texi
@@ -0,0 +1 @@
+    gnutls-cli-debug (1), gnutls-serv (1), srptool (1), certtool (1)
diff --git a/doc/scripts/Makefile.am b/doc/scripts/Makefile.am
index f7e192b98b..a310b626ce 100644
--- a/doc/scripts/Makefile.am
+++ b/doc/scripts/Makefile.am
@@ -17,4 +17,4 @@
 # along with this file; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
-EXTRA_DIST = gdoc sort2.pl split-texi.pl cleanup-autogen.pl getfuncs.pl getfuncs-map.pl
+EXTRA_DIST = gdoc sort2.pl split-texi.pl getfuncs.pl getfuncs-map.pl gen-cmd-texi.py
diff --git a/doc/scripts/cleanup-autogen.pl b/doc/scripts/cleanup-autogen.pl
deleted file mode 100755
index a6b19e9e08..0000000000
--- a/doc/scripts/cleanup-autogen.pl
+++ /dev/null
@@ -1,71 +0,0 @@
-#!/usr/bin/perl
-
-# Copyright (C) 2012 Free Software Foundation, Inc.
-#
-# This file is part of GnuTLS.
-#
-# This file is free software; you can redistribute it and/or modify it
-# under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# This file is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this file; if not, write to the Free Software Foundation,
-# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
-my $line;
-my $init = 0;
-my $menu = 0;
-my $i = 0;
-
-while ($line = <>) {
-
-  if ($line =~ /\@node (.*)/) {
-    if ($init == 0) {
-      $init = 1;
-    } else {
-      print "\@anchor\{$1\}\n";
-      next;
-    }
-  }
-
-  if ($line =~ /\@menu/) {
-    $menu = 1;
-    next;
-  }
-
-  if ($line =~ /\@end menu/) {
-    $menu = 0;
-    next;
-  }
-
-  next if ($menu != 0);
-
-  if ($line =~ /\@subsection\s(.*)/) {
-    $line = "\@subheading $1\n";
-  }
-
-  if ($line =~ /\@cindex\s(.*)/) {
-    if ($line !~ /help/) {
-      next;
-    }
-  }
-
-  if ($line =~ /^Please send bug reports.*/) {
-    next;
-  }
-
-  print $line;
-  $i++;
-}
-
-if ($i < 2) {
-  exit 1;
-}
-
-exit 0;
diff --git a/doc/scripts/gen-cmd-texi.py b/doc/scripts/gen-cmd-texi.py
new file mode 100644
index 0000000000..097eda81c1
--- /dev/null
+++ b/doc/scripts/gen-cmd-texi.py
@@ -0,0 +1,267 @@
+#!/usr/bin/python
+# Copyright (C) 2021 Daiki Ueno
+
+# This file is part of GnuTLS.
+
+# GnuTLS is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# GnuTLS is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see
+# <https://www.gnu.org/licenses/>.
+
+from typing import Mapping, Sequence, TextIO
+import io
+import jsonopts
+
+HEADINGS = ['@heading', '@subheading', '@subsubheading']
+
+
+def get_heading(level: int) -> str:
+    return HEADINGS[min(level, len(HEADINGS)-1)]
+
+
+SECTIONS = ['@section', '@subsection', '@subsubsection']
+
+
+def get_section(level: int) -> str:
+    return SECTIONS[min(level, len(SECTIONS)-1)]
+
+
+def shift_headings(s: str, level: int) -> str:
+    for (i, h) in reversed(list(enumerate(HEADINGS))):
+        r = get_heading(level+i)
+        s = s.replace(h, r)
+    return s
+
+
+def gen_option_docs(meta: Mapping[str, str],
+                    level: int,
+                    options: Sequence[Mapping[str, str]]) -> str:
+    prog_name = meta['prog-name']
+    docs = io.StringIO()
+    for option in options:
+        long_opt = option['long-option']
+        short_opt = option.get('short-option')
+        detail = option.get('detail')
+        desc = option.get('desc')
+        alias = option.get('aliases')
+        if alias:
+            docs.write(f'''\
+{get_heading(level+1)} {long_opt} option.
+@anchor{{{prog_name} {long_opt}}}
+
+This is an alias for the @code{{{alias}}} option,
+@pxref{{{prog_name} {alias}, the {alias} option documentation}}.
+
+''')
+            continue
+
+        if not detail or not desc:
+            continue
+        if short_opt:
+            docs.write(
+                f'{get_heading(level+1)} {long_opt} option (-{short_opt}).\n'
+            )
+        else:
+            docs.write(f'{get_heading(level+1)} {long_opt} option.\n')
+        docs.write(f'''\
+@anchor{{{prog_name} {long_opt}}}
+
+This is the ``{desc.lower()}'' option.
+''')
+        arg_type = option.get('arg-type')
+        if arg_type:
+            arg_name = option.get('arg-name')
+            if arg_name:
+                docs.write((
+                    f'This option takes a {arg_type} argument '
+                    f'@file{{{arg_name}}}.\n'
+                ))
+            else:
+                docs.write(f'This option takes a {arg_type} argument.\n')
+
+        conflict_opts = option.get('conflicts', '').split()
+        require_opts = option.get('requires', '').split()
+        disable_prefix = option.get('disable-prefix')
+        if len(conflict_opts) > 0 or len(require_opts) > 0 or \
+           ('enabled' in option):
+            docs.write('''
+@noindent
+This option has some usage constraints.  It:
+@itemize @bullet
+''')
+            if len(conflict_opts) > 0:
+                docs.write(f'''\
+@item
+must not appear in combination with any of the following options:
+{', '.join(conflict_opts)}.
+''')
+            if len(require_opts) > 0:
+                docs.write(f'''\
+@item
+must appear in combination with the following options:
+{', '.join(require_opts)}.
+''')
+            if disable_prefix:
+                docs.write(f'''\
+@item
+can be disabled with --{disable_prefix}{long_opt}.
+''')
+            if 'enabled' in option:
+                docs.write('''\
+@item
+It is enabled by default.
+''')
+            docs.write('@end itemize\n\n')
+
+        docs.write(f'''\
+{detail}
+''')
+        if 'deprecated' in option:
+            docs.write('\n@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}\n')
+
+    return docs.getvalue()
+
+
+LABELS = {
+    'see-also': 'See Also',
+    'examples': 'Examples',
+    'files': 'Files'
+}
+
+
+def include(meta: Mapping[str, str],
+            level: int,
+            name: str,
+            includes: Mapping[str, TextIO]) -> str:
+    prog_name = meta['prog-name']
+    docs = io.StringIO()
+    f = includes.get(name)
+    if f:
+        docs.write(f'''\
+@anchor{{{prog_name} {LABELS[name]}}}
+{get_heading(level+2)} {prog_name} {LABELS[name]}
+{shift_headings(f.read(), level)}\
+''')
+    return docs.getvalue()
+
+
+def escape_texi(s: str) -> str:
+    for c in ['@', '{', '}']:
+        s = s.replace(c, f'@{c}')
+    return s
+
+
+def gen(infile: TextIO,
+        level: int,
+        section_node: bool,
+        includes: Mapping[str, TextIO],
+        texi: TextIO):
+    sections = [jsonopts.Section.from_json(section)
+                for section in json.load(args.json)]
+    sections.append(jsonopts.Section.default())
+
+    prog_name = sections[0].meta['prog-name']
+    description = includes.get('description')
+    if description:
+        detail = description.read()
+    else:
+        detail = sections[0].meta['detail']
+
+    section_docs = io.StringIO()
+    for section in sections:
+        section_id = section.meta.get('id', '')
+        if section_id:
+            section_desc = section.meta['desc']
+            option_docs = gen_option_docs(sections[0].meta, level+1,
+                                          section.options)
+            section_docs.write(f'''\
+@anchor{{{prog_name} {section_id}}}
+{get_heading(level+1)} {section_id} options
+{section_desc if section_desc.endswith('.') else section_desc + '.'}
+{option_docs}\
+''')
+        else:
+            section_docs.write(gen_option_docs(sections[0].meta, level,
+                                               section.options))
+
+    heading = get_section(level) if section_node else get_heading(level)
+    texi.write(f'''\
+@node {prog_name} Invocation
+{heading} Invoking {prog_name}
+@pindex {prog_name}
+
+{detail}
+
+@anchor{{{prog_name} usage}}
+{get_heading(level+1)} {prog_name} help/usage (@option{{-?}})
+@cindex {prog_name} help
+
+The text printed is the same whether selected with the @code{{help}} option
+(@option{{--help}}) or the @code{{more-help}} option \
+(@option{{--more-help}}).  @code{{more-help}} will print
+the usage text by passing it through a pager program.
+@code{{more-help}} is disabled on platforms without a working
+@code{{fork(2)}} function.  The @code{{PAGER}} environment variable is
+used to select the program, defaulting to @file{{more}}.  Both will exit
+with a status code of 0.
+
+@exampleindent 0
+@example
+{escape_texi(jsonopts.usage(sections[0].meta, sections))}
+@end example
+@exampleindent 4
+
+{section_docs.getvalue()}\
+@anchor{{{prog_name} exit status}}
+{get_heading(level+1)} {prog_name} exit status
+
+One of the following exit values will be returned:
+@table @samp
+@item 0 (EXIT_SUCCESS)
+Successful program execution.
+@item 1 (EXIT_FAILURE)
+The operation failed or the command syntax was not valid.
+@end table
+''')
+    if 'see-also' in includes:
+        texi.write(include(sections[0].meta, level, 'see-also', includes))
+    if 'examples' in includes:
+        texi.write(include(sections[0].meta, level, 'examples', includes))
+    if 'files' in includes:
+        texi.write(include(sections[0].meta, level, 'files', includes))
+
+
+if __name__ == '__main__':
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(description='generate texinfo')
+    parser.add_argument('json', type=argparse.FileType('r'))
+    parser.add_argument('texi', type=argparse.FileType('w'))
+    parser.add_argument('--description', type=argparse.FileType('r'))
+    parser.add_argument('--see-also', type=argparse.FileType('r'))
+    parser.add_argument('--examples', type=argparse.FileType('r'))
+    parser.add_argument('--files', type=argparse.FileType('r'))
+    parser.add_argument('--level', type=int, default=0)
+    parser.add_argument('--section-node', action='store_true')
+
+    args = parser.parse_args()
+    includes = dict()
+    if args.see_also:
+        includes['see-also'] = args.see_also
+    if args.examples:
+        includes['examples'] = args.examples
+    if args.files:
+        includes['files'] = args.files
+    if args.description:
+        includes['description'] = args.description
+    gen(args.json, args.level, args.section_node, includes, args.texi)
diff --git a/doc/srptool-examples.texi b/doc/srptool-examples.texi
new file mode 100644
index 0000000000..1be2315fbd
--- /dev/null
+++ b/doc/srptool-examples.texi
@@ -0,0 +1,19 @@
+To create @file{tpasswd.conf} which holds the g and n values for SRP protocol
+(generator and a large prime), run:
+@example
+$ srptool --create-conf /etc/tpasswd.conf
+@end example
+
+This command will create @file{/etc/tpasswd} and will add user 'test' (you
+will also be prompted for a password). Verifiers are stored by default
+in the way libsrp expects.
+@example
+$ srptool --passwd /etc/tpasswd --passwd-conf /etc/tpasswd.conf -u test
+@end example
+
+
+This command will check against a password. If the password matches
+the one in @file{/etc/tpasswd} you will get an ok.
+@example
+$ srptool --passwd /etc/tpasswd --passwd\-conf /etc/tpasswd.conf --verify -u test
+@end example
diff --git a/doc/srptool-see-also.texi b/doc/srptool-see-also.texi
new file mode 100644
index 0000000000..d3c8678d5f
--- /dev/null
+++ b/doc/srptool-see-also.texi
@@ -0,0 +1 @@
+    gnutls-cli-debug (1), gnutls-serv (1), srptool (1), psktool (1), certtool (1)
diff --git a/doc/systemkey-tool-see-also.texi b/doc/systemkey-tool-see-also.texi
new file mode 100644
index 0000000000..d95af062b0
--- /dev/null
+++ b/doc/systemkey-tool-see-also.texi
@@ -0,0 +1 @@
+    p11tool (1), certtool (1)
diff --git a/doc/tpmtool-examples.texi b/doc/tpmtool-examples.texi
new file mode 100644
index 0000000000..fa70926ffc
--- /dev/null
+++ b/doc/tpmtool-examples.texi
@@ -0,0 +1,25 @@
+To generate a key that is to be stored in file system use:
+@example
+$ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem
+@end example
+
+To generate a key that is to be stored in TPM's flash use:
+@example
+$ tpmtool --generate-rsa --bits 2048 --register --user
+@end example
+
+To get the public key of a TPM key use:
+@example
+$ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \
+          --outfile pubkey.pem
+@end example
+
+or if the key is stored in the file system:
+@example
+$ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem
+@end example
+
+To list all keys stored in TPM use:
+@example
+$ tpmtool --list
+@end example
diff --git a/doc/tpmtool-see-also.texi b/doc/tpmtool-see-also.texi
new file mode 100644
index 0000000000..d95af062b0
--- /dev/null
+++ b/doc/tpmtool-see-also.texi
@@ -0,0 +1 @@
+    p11tool (1), certtool (1)