Documentation: Initial pandoc conversion

.github/workflows/quick.yaml

@@ -36,8 +36,11 @@ jobs:
     steps:
       - name: Install prerequisite packages
         run: |
+          # required for "apt-get build-dep" to work
+          sudo sed --in-place -E 's/# (deb-src.*updates main)/  \1/g' /etc/apt/sources.list
           sudo apt-get --quiet=2 update
-          sudo apt-get --quiet=2 install libtool-bin
+          sudo apt-get --quiet=2 build-dep squid
+          sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc
 
       - name: Setup a nodejs environment
         uses: actions/setup-node@v4
@@ -127,7 +130,7 @@ jobs:
           sudo sed --in-place -E 's/# (deb-src.*updates main)/  \1/g' /etc/apt/sources.list
           sudo apt-get --quiet=2 update
           sudo apt-get --quiet=2 build-dep squid
-          sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin ${{ matrix.compiler.CC }} ccache
+          sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc ${{ matrix.compiler.CC }} ccache
 
       - name: Checkout sources
         uses: actions/checkout@v4
@@ -163,7 +166,7 @@ jobs:
           sudo sed --in-place -E 's/# (deb-src.*updates main)/  \1/g' /etc/apt/sources.list
           sudo apt-get --quiet=2 update
           sudo apt-get --quiet=2 build-dep squid
-          sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin
+          sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc
 
       - name: Checkout repository
         uses: actions/checkout@v4

configure.ac

@@ -143,6 +143,9 @@ AC_PATH_PROG(AR, ar, $FALSE)
 AR_R="$AR r"
 AC_SUBST(AR_R)
 
+AC_PATH_PROG(PANDOC, pandoc, $FALSE)
+AM_CONDITIONAL(ENABLE_PANDOC_DOC, test "x${ac_cv_path_PANDOC}" != "x$FALSE")
+
 AC_PATH_PROG(LINUXDOC, linuxdoc, $FALSE)
 AM_CONDITIONAL(ENABLE_RELEASE_DOCS, test "x${ac_cv_path_LINUXDOC}" != "x$FALSE")
 

doc/manuals/Substitute.am

@@ -17,6 +17,7 @@ SUBSTITUTE=sed "\
 	s%@SYSCONFDIR@%$(sysconfdir)%g;\
 	"
 
-## Example of how to substitute:
-## squid.8: $(srcdir)/squid.8.in Makefile
-##	$(SUBSTITUTE) < $(srcdir)/squid.8.in > $@
+.md.8:
+	$(SUBSTITUTE) < $(srcdir)/`basename $<` | \
+	$(PANDOC) -t man -f gfm -s -o $@
+

src/Common.am

@@ -70,4 +70,5 @@ COMPAT_LIB = $(top_builddir)/compat/libcompatsquid.la $(LIBPROFILER)
 ## Some helpers are written in Perl and need the local shell defined properly
 subst_perlshell = sed -e 's,[@]PERL[@],$(PERL),g' <$(srcdir)/[email protected] >$@ || ($(RM) -f $@ ; exit 1)
 
+include $(top_srcdir)/doc/manuals/Substitute.am
 include $(top_srcdir)/src/TestHeaders.am

src/Makefile.am

@@ -7,6 +7,13 @@
 
 include $(top_srcdir)/src/Common.am
 
+dist_doc_DATA = squid.md
+
+if ENABLE_PANDOC_DOC
+man_MANS = squid.8
+CLEANFILES += squid.8
+endif
+
 DNSSOURCE = \
 	dns_internal.cc
 
@@ -689,15 +696,6 @@ cf.data: cf.data.pre Makefile
 repl_modules.cc: repl_modules.sh Makefile
 	$(SHELL) $(srcdir)/repl_modules.sh $(REPL_POLICIES) > repl_modules.cc
 
-include $(top_srcdir)/doc/manuals/Substitute.am
-
-squid.8: $(srcdir)/squid.8.in Makefile
-	$(SUBSTITUTE) < $(srcdir)/squid.8.in > $@
-
-man_MANS = squid.8
-EXTRA_DIST += squid.8.in
-CLEANFILES += squid.8
-
 install-data-local: install-sysconfDATA install-dataDATA
 	@if test -f $(DESTDIR)$(DEFAULT_MIME_TABLE) ; then \
 	  echo "$@ will not overwrite existing $(DESTDIR)$(DEFAULT_MIME_TABLE)" ; \

src/security/cert_generators/file/Makefile.am

@@ -6,7 +6,6 @@
 ##
 
 include $(top_srcdir)/src/Common.am
-include $(top_srcdir)/doc/manuals/Substitute.am
 
 security_file_certgen.8: $(srcdir)/security_file_certgen.8.in Makefile
 	$(SUBSTITUTE) < $(srcdir)/security_file_certgen.8.in > $@