doc: Use generic rules for man/html generation
PATCH 1/1 doc: Use generic rules for man/html generation
From: David Sommerseth <[email protected]...>
Prior to this patch, the Makefile.am needs to be modified multiple places to add a new man or HTML page to be generated. Since it is not too often we modify this, it is easy to miss these finer details.
This changes the man and HTML generator rules to be more generic and use variables as many places as possible. Also moved all the lines which should not need to be changed as much towards the bottom-half of the file.
--- doc/Makefile.am | 52 ++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 27 deletions(-)
doc/Makefile.am +25 -27
@@ -9,11 +9,17 @@ # Copyright (C) 2006-2012 Alon Bar-Lev <[email protected]...> # -MAINTAINERCLEANFILES = \ - $(srcdir)/Makefile.in - SUBDIRS = doxygen +# +# List of man and HTML pages we build when rst2man/rst2html is available +# +# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below +# This could be automated with GNU Make, but we need BSD Make support +# +build_man_pages = openvpn.8 openvpn-examples.5 +build_html_pages = openvpn.8.html openvpn-examples.5.html + dist_doc_DATA = \ management-notes.txt gui-notes.txt
@@ -47,49 +53,41 @@ dist_noinst_DATA = \ man-sections/vpn-network-options.rst \ man-sections/windows-options.rst -openvpn.8 : -if HAVE_PYDOCUTILS - $(RST2MAN) $(srcdir)/[email protected] > $@ -else - @echo "Missing python-docutils - skipping man page generation" -endif -openvpn-examples.5 : -if HAVE_PYDOCUTILS - $(RST2MAN) $(srcdir)/[email protected] > $@ -else - @echo "Missing python-docutils - skipping man page generation" -endif +###### GENERIC RULES ########## + +SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in -openvpn.8.html: +.8.rst.8 .5.rst.5 : if HAVE_PYDOCUTILS - $(RST2HTML) $(srcdir)/openvpn.8.rst > $@ + $(RST2MAN) $< > $@ else - @echo "Missing python-docutils - skipping man/html page generation" + @echo "Missing python-docutils - skipping man page generation ($@)" endif -openvpn-examples.5.html: +.8.rst.8.html .5.rst.5.html : if HAVE_PYDOCUTILS - $(RST2HTML) $(srcdir)/openvpn-examples.5.rst > $@ + $(RST2MAN) $< > $@ else - @echo "Missing python-docutils - skipping man/html page generation" + @echo "Missing python-docutils - skipping html page generation ($@)" endif if HAVE_PYDOCUTILS -dist_noinst_DATA += openvpn.8 openvpn-examples.5 -dist_html_DATA = openvpn.8.html openvpn-examples.5.html +dist_noinst_DATA += $(build_man_pages) +dist_html_DATA = $(build_html_pages) # Failsafe - do not delete these files unless we can recreate them -CLEANFILES = \ - openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html +CLEANFILES = $(build_man_pages) $(build_html_pages) endif if WIN32 else -dist_man_MANS = openvpn.8 +dist_man_MANS = $(build_man_pages) endif -dist-hook : openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html +dist-hook : $(build_man_pages) $(build_html_pages)
Signature · 1 line
2.27.0
PATCH v2 1/1 doc: Use generic rules for man/html generation
From: David Sommerseth <[email protected]...>
Prior to this patch, the Makefile.am needs to be modified multiple places to add a new man or HTML page to be generated. Since it is not too often we modify this, it is easy to miss these finer details.
This changes the man and HTML generator rules to be more generic and use variables as many places as possible. Also moved all the lines which should not need to be changed as much towards the bottom-half of the file.
---
v2 - Fix incorrect HTML generation, use rst2html
--- doc/Makefile.am | 52 ++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 27 deletions(-)
doc/Makefile.am +25 -27
@@ -9,11 +9,17 @@ # Copyright (C) 2006-2012 Alon Bar-Lev <[email protected]...> # -MAINTAINERCLEANFILES = \ - $(srcdir)/Makefile.in - SUBDIRS = doxygen +# +# List of man and HTML pages we build when rst2man/rst2html is available +# +# NOTE: Remember to add source .rst files to $(dist_noinst_DATA) below +# This could be automated with GNU Make, but we need BSD Make support +# +build_man_pages = openvpn.8 openvpn-examples.5 +build_html_pages = openvpn.8.html openvpn-examples.5.html + dist_doc_DATA = \ management-notes.txt gui-notes.txt
@@ -47,49 +53,41 @@ dist_noinst_DATA = \ man-sections/vpn-network-options.rst \ man-sections/windows-options.rst -openvpn.8 : -if HAVE_PYDOCUTILS - $(RST2MAN) $(srcdir)/[email protected] > $@ -else - @echo "Missing python-docutils - skipping man page generation" -endif -openvpn-examples.5 : -if HAVE_PYDOCUTILS - $(RST2MAN) $(srcdir)/[email protected] > $@ -else - @echo "Missing python-docutils - skipping man page generation" -endif +###### GENERIC RULES ########## + +SUFFIXES = .8.rst .8 .8.html .5.rst .5 .5.html +MAINTAINERCLEANFILES = \ + $(srcdir)/Makefile.in -openvpn.8.html: +.8.rst.8 .5.rst.5 : if HAVE_PYDOCUTILS - $(RST2HTML) $(srcdir)/openvpn.8.rst > $@ + $(RST2MAN) $< > $@ else - @echo "Missing python-docutils - skipping man/html page generation" + @echo "Missing python-docutils - skipping man page generation ($@)" endif -openvpn-examples.5.html: +.8.rst.8.html .5.rst.5.html : if HAVE_PYDOCUTILS - $(RST2HTML) $(srcdir)/openvpn-examples.5.rst > $@ + $(RST2HTML) $< > $@ else - @echo "Missing python-docutils - skipping man/html page generation" + @echo "Missing python-docutils - skipping html page generation ($@)" endif if HAVE_PYDOCUTILS -dist_noinst_DATA += openvpn.8 openvpn-examples.5 -dist_html_DATA = openvpn.8.html openvpn-examples.5.html +dist_noinst_DATA += $(build_man_pages) +dist_html_DATA = $(build_html_pages) # Failsafe - do not delete these files unless we can recreate them -CLEANFILES = \ - openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html +CLEANFILES = $(build_man_pages) $(build_html_pages) endif if WIN32 else -dist_man_MANS = openvpn.8 +dist_man_MANS = $(build_man_pages) endif -dist-hook : openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html +dist-hook : $(build_man_pages) $(build_html_pages)
Signature · 1 line
2.27.0
Tested on:
- Linux, with docutils, including "make distcheck" + tarball check
- FreeBSD 12, with no docutils, "make" succeeds, "distcheck" fails (ok)
- FreeBSD 13, with docutils, including "make distcheck"
Your patch has been applied to the master and release/2.5 branch (no code change, eases our future maintenance).
commit 37cf98fa224a2ae5fc5cfa380bdb291e90d6413d (master) commit 18211f1ba3124bde05ca11c5111989acdb27f957 (release/2.5)
Author: David Sommerseth Date: Wed Jun 30 20:51:34 2021 +0200
doc: Use generic rules for man/html generation
Signed-off-by: David Sommerseth <[email protected]...>
Acked-by: Gert Doering <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg22604.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering