The branch master has been updated via ea973d250e311c51c91217c2e6edf93370be0e43 (commit) from b8cbeb50101d64690eeee8769827e8b03cc7c382 (commit)
- Log ----------------------------------------------------------------- commit ea973d250e311c51c91217c2e6edf93370be0e43 Author: Richard Levitte <levi...@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 <m...@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@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@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>