[web] master update
Richard Levitte
levitte at openssl.org
Thu May 28 17:49:53 UTC 2020
The branch master has been updated
via ea973d250e311c51c91217c2e6edf93370be0e43 (commit)
from b8cbeb50101d64690eeee8769827e8b03cc7c382 (commit)
- Log -----------------------------------------------------------------
commit ea973d250e311c51c91217c2e6edf93370be0e43
Author: Richard Levitte <levitte at openssl.org>
Date: Thu Apr 23 19:44:05 2020 +0200
Adapt man-page making for OpenSSL master / 3.0
We use OpenSSL's rendering instead of our own, and just lightly strip
the result to fit in our page layout.
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/web/pull/175)
-----------------------------------------------------------------------
Summary of changes:
Makefile | 63 +++++++++++++++++++++++++++++++++++-----------
bin/all-html-man-names | 16 ++++++++++++
bin/from-tt | 6 ++---
bin/mk-manpages | 2 +-
bin/mk-manpages3 | 34 +++++++++++++++++++++++++
bin/strip-man-html | 17 +++++++++++++
inc/manpage-template.html5 | 46 +++++++++++++++++++++++++++++++++
7 files changed, 166 insertions(+), 18 deletions(-)
create mode 100755 bin/all-html-man-names
create mode 100755 bin/mk-manpages3
create mode 100755 bin/strip-man-html
create mode 100644 inc/manpage-template.html5
diff --git a/Makefile b/Makefile
index d31a473..4b1bd1f 100644
--- a/Makefile
+++ b/Makefile
@@ -21,11 +21,12 @@ SERIES=1.1.1
## Older series. The second type is for source listings
OLDSERIES=1.1.0 1.0.2 1.0.1 1.0.0 0.9.8 0.9.7 0.9.6
OLDSERIES2=1.1.0 1.0.2 1.0.1 1.0.0 0.9.x
+## Series for manual layouts
+MANSERIES1=1.1.1
+MANSERIES3=3.0
# All simple generated files.
SIMPLE = newsflash.inc sitemap.txt \
- community/committers.inc \
- community/otc.inc community/omc.inc community/omc-alumni.inc \
docs/faq.inc docs/fips.inc \
docs/OpenSSLStrategicArchitecture.html \
docs/OpenSSL300Design.html \
@@ -79,13 +80,19 @@ rebuild: all
##
## A lot of the work is made with generated rules.
-# makemanpages creates rules for targets like manpages-1.1.1, to
-# build the set of man-pages and indexes of man-pages for the given
-# OpenSSL release (such as 1.1.1)
+# makemanpages1 and makemanpages3 creates rules for targets like man-pages-1.1.1,
+# to build the set of man-pages. makemanpages1 is used for pre-3.0 OpenSSL,
+# while makemanpages3 is used for OpenSSL 3.0 and on.
+# makemanapropos creates rules for targets like man-apropos-1.1.1, to build
+# 'apropos' like indexes for all the manpages.
+# makemanindexes creates rules for targets like man-index-1.1.1, to build the
+# main HTML index for a set of man-pages.
#
# $(1) = input directory in CHECKOUTS, $(2) = release version
-define makemanpages
-manpages-$(2):
+
+# This variant is for pre-3.0 documentation
+define makemanpages1
+man-pages-$(2):
@rm -rf docs/man$(2)
@mkdir -p docs/man$(2) \
docs/man$(2)/man1 \
@@ -93,34 +100,62 @@ manpages-$(2):
docs/man$(2)/man5 \
docs/man$(2)/man7
./bin/mk-manpages $(CHECKOUTS)/$(1)/doc $(2) docs/man$(2)
+endef
+# This variant is for 3.0 documentation
+define makemanpages3
+man-pages-$(2):
+ @rm -rf docs/man$(2)
+ @mkdir -p docs/man$(2) \
+ docs/man$(2)/man1 \
+ docs/man$(2)/man3 \
+ docs/man$(2)/man5 \
+ docs/man$(2)/man7
+ ./bin/mk-manpages3 $(CHECKOUTS)/$(1) $(2) docs/man$(2)
+endef
+define makemanapropos
+man-apropos-$(2): man-pages-$(2)
./bin/mk-apropos docs/man$(2)/man1 > docs/man$(2)/man1/index.inc
./bin/mk-apropos docs/man$(2)/man3 > docs/man$(2)/man3/index.inc
./bin/mk-apropos docs/man$(2)/man5 > docs/man$(2)/man5/index.inc
./bin/mk-apropos docs/man$(2)/man7 > docs/man$(2)/man7/index.inc
+endef
+define makemanindexes
+man-index-$(2):
./bin/from-tt -d docs/man$(2)/man1 releases='$(SERIES)' release='$(2)' \
< docs/sub-man1-index.html.tt > docs/man$(2)/man1/index.html
- ./bin/from-tt -d docs/man$(2)/man1 releases='$(SERIES)' release='$(2)' \
+ ./bin/from-tt -d docs/man$(2)/man3 releases='$(SERIES)' release='$(2)' \
< docs/sub-man3-index.html.tt > docs/man$(2)/man3/index.html
- ./bin/from-tt -d docs/man$(2)/man1 releases='$(SERIES)' release='$(2)' \
+ ./bin/from-tt -d docs/man$(2)/man5 releases='$(SERIES)' release='$(2)' \
< docs/sub-man5-index.html.tt > docs/man$(2)/man5/index.html
- ./bin/from-tt -d docs/man$(2)/man1 releases='$(SERIES)' release='$(2)' \
+ ./bin/from-tt -d docs/man$(2)/man7 releases='$(SERIES)' release='$(2)' \
< docs/sub-man7-index.html.tt > docs/man$(2)/man7/index.html
./bin/from-tt -d docs/man$(2) releases='$(SERIES)' release='$(2)' \
< docs/sub-index.html.tt > docs/man$(2)/index.html
endef
+define makemanuals1
+$(eval $(call makemanpages1,$(1),$(2)))
+$(eval $(call makemanapropos,$(1),$(2)))
+$(eval $(call makemanindexes,$(1),$(2)))
+endef
+define makemanuals3
+$(eval $(call makemanpages3,$(1),$(2)))
+$(eval $(call makemanapropos,$(1),$(2)))
+$(eval $(call makemanindexes,$(1),$(2)))
+endef
# Now that we have the generating macros in place, let's use them!
#
# Start off with creating the 'manpages-master' target, taking the
# source from $(CHECKOUTS)/openssl/doc
-$(eval $(call makemanpages,openssl,master))
+$(eval $(call makemanuals3,openssl,master))
+#$(foreach S,$(MANSERIES3),$(eval $(call makemanuals3,openssl-$(S),$(S))))
# Next, create 'manpages-x.y.z' for all current releases, taking the
# source from $(CHECKOUTS)/openssl-x.y.z-stable/doc
-$(foreach S,$(SERIES),$(eval $(call makemanpages,openssl-$(S)-stable,$(S))))
+$(foreach S,$(MANSERIES1),$(eval $(call makemanuals1,openssl-$(S)-stable,$(S))))
-manmaster: manpages-master
-manpages: $(foreach S,$(SERIES),manpages-$(S))
+manmaster: man-apropos-master man-index-master
+manpages: $(foreach S,$(MANSERIES1),man-apropos-$(S) man-index-$(S))
mancross:
./bin/mk-mancross master $(SERIES)
diff --git a/bin/all-html-man-names b/bin/all-html-man-names
new file mode 100755
index 0000000..7f9ed22
--- /dev/null
+++ b/bin/all-html-man-names
@@ -0,0 +1,16 @@
+#! /usr/bin/env perl
+
+
+local $/; # Slurp the whole file
+my $contents = <STDIN>;
+
+$contents =~ m@^<h3 id="NAME">NAME</h3>@m;
+$contents = $'; # Everything before and including NAME is removed
+$contents =~ m@^<h3 at m;
+$contents = $`; # Everything including and efter the next h3 is removed
+$contents =~ s@</?p>@@g; # All paragraph tags are removed
+$contents =~ s@^\s+@@s; # All whitespace at the beginning is removed
+$contents =~ s@\s+$@@s; # All whitespace at the end is removed
+$contents =~ s@\s+@ @gs; # All whitespace blocks are collapsed to a space
+
+print $contents;
diff --git a/bin/from-tt b/bin/from-tt
index b5018b6..c302835 100755
--- a/bin/from-tt
+++ b/bin/from-tt
@@ -98,9 +98,9 @@ if [ $# -eq 0 ]; then
(
cd $dir
( cat $HERE/../inc/common.tt;
- if [ -n "$input" ]; then cat "$input"; else cat; fi ) \
- | eval "$tpagecmd --define 'dir=${dir:-filedir}'" \
- | ( if [ -n "$output" ]; then cat > "$output"; else cat; fi )
+ if [ -n "$input" ]; then cat "$HERE/../$input"; else cat; fi ) \
+ | eval "$tpagecmd --define 'dir=$HERE/../${dir:-filedir}'" \
+ | ( if [ -n "$output" ]; then cat > "$HERE/../$output"; else cat; fi )
)
else
errfiles=
diff --git a/bin/mk-manpages b/bin/mk-manpages
index 6b57ead..5911342 100755
--- a/bin/mk-manpages
+++ b/bin/mk-manpages
@@ -182,7 +182,7 @@ sub getdata {
while (<$fh>) {
chop;
s/\n/ /gm;
- if (/^=for comment openssl_manual_section:\s*(\d+)/) {
+ if (/^=for (?:comment|openssl) openssl_manual_section:\s*(\d+)/) {
$data{sectnum} = "$1";
}
elsif (/^=head1\s/) {
diff --git a/bin/mk-manpages3 b/bin/mk-manpages3
new file mode 100755
index 0000000..dba2772
--- /dev/null
+++ b/bin/mk-manpages3
@@ -0,0 +1,34 @@
+#! /bin/bash -e
+
+HERE=$(dirname $0)
+checkoutdir=$1
+series=$2
+destdir=$3
+
+rm -rf tmp
+mkdir tmp
+
+(cd tmp; $checkoutdir/Configure cc && make build_html_docs)
+
+srcdir=tmp/doc/html
+(cd $srcdir; find -type f) | while read F; do
+ Dn=$(dirname $F)
+ Fn=$(basename $F .html)
+ G=$Dn/$Fn.inc
+ $HERE/strip-man-html < $srcdir/$F > $destdir/$G
+
+ section=$(basename $Dn | sed -e 's|^man||')
+ description="$($HERE/all-html-man-names < $destdir/$G | sed 's|^.* - ||')"
+ names="$($HERE/all-html-man-names < $destdir/$G | sed -e 's| - .*||' -e 's|, *| |g' -e 's|/|-|g')"
+ for name in $names; do
+ G=$Dn/$name.html
+ cat $HERE/../inc/manpage-template.html5 \
+ | sed -E \
+ -e "s|\\\$release\\\$|$series|g" \
+ -e "s|\\\$sectnum\\\$|$section|g" \
+ -e "s|\\\$description\\\$|$description|g" \
+ -e "s|\\\$name\\\$|$name|g" \
+ -e "s|\\\$origname\\\$|$Fn|g" \
+ > $destdir/$G
+ done
+done
diff --git a/bin/strip-man-html b/bin/strip-man-html
new file mode 100755
index 0000000..c4842d1
--- /dev/null
+++ b/bin/strip-man-html
@@ -0,0 +1,17 @@
+#! /usr/bin/env perl
+
+# pod2html creates complete pages, but we want embeddable ones.
+# Fortunately, it's easy to find the stuff that need to go away.
+
+local $/; # Slurp the whole file
+my $contents = <STDIN>;
+
+$contents =~ m@^<h1 id="NAME">NAME</h1>@m;
+$contents = $&.$'; # Everything before NAME is stripped
+$contents =~ m@^</body>@m;
+$contents = $`; # </body> and everything after is stripped
+
+# Adapt all H tags to be wrapped inside H1 and H2
+$contents =~ s@(</?h)(\d)(\s|>)@$1.($2 + 2).$3 at emg;
+
+print $contents;
diff --git a/inc/manpage-template.html5 b/inc/manpage-template.html5
new file mode 100644
index 0000000..f38e698
--- /dev/null
+++ b/inc/manpage-template.html5
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<!-- OSSL: subdir: man$sectnum$ -->
+<!-- OSSL: section: $sectnum$ -->
+<!-- OSSL: description: $description$ -->
+<!--#include virtual="/inc/head.shtml" -->
+<body>
+<!--#include virtual="/inc/banner.shtml" -->
+ <div id="main">
+ <div id="content">
+ <div class="blog-index">
+ <article>
+ <header><h2>$name$</h2></header>
+ <div class="entry-content">
+ <p>
+<!--#include virtual="$origname$.inc" -->
+ </p>
+ </div>
+ <footer>
+ You are here: <a href="/">Home</a>
+ : <a href="/docs">Docs</a>
+ : <a href="/docs/manpages.html">Manpages</a>
+ : <a href="/docs/man$release$/">$release$</a>
+ : <a href="/docs/man$release$/man$sectnum$">man$sectnum$</a>
+ : <a href="/docs/man$release$/man$sectnum$/$name$.html">$name$</a>
+ <br/><a href="/sitemap.txt">Sitemap</a>
+ </footer>
+ </article>
+ </div>
+ <aside class="sidebar">
+ <section>
+ <h1><a href="/docs/man$release$/">$release$ manpages</a></h1>
+ <ul>
+ <li><a href="../man1">Commands</a></li>
+ <li><a href="../man3">Libraries</a></li>
+ <li><a href="../man5">File Formats</a></li>
+ <li><a href="../man7">Overviews</a></li>
+ </ul>
+ </section>
+<!--#include virtual="$name$.cross" -->
+ </aside>
+ </div>
+ </div>
+<!--#include virtual="/inc/footer.shtml" -->
+</body>
+</html>
More information about the openssl-commits
mailing list