docs: Generate documention in Markdown format as well

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index f964b990e8b879d597cb34911f7276758a7ddaa2..303e0ec51b755b13e78817b69fc25bc567dfba0d 100644 (file)
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -271,7 +271,7 @@ jobs:
         uses: actions/checkout@v4
       - name: Prepare environment
         run: |
-          sudo apt-get install -y asciidoctor
+          sudo apt-get install -y asciidoctor pandoc
       - name: Build documentation
         run: ci/build-docs
       - name: Upload documentation

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 1d860f2bbdba6101bcb6551b9964bb7574d52020..d77cea67137d3680b19610235f913975fe6201b2 100644 (file)
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,43 +1,42 @@
 find_program(ASCIIDOCTOR_EXE asciidoctor)
 mark_as_advanced(ASCIIDOCTOR_EXE) # Don't show in CMake UIs
 
+find_program(PANDOC_EXE pandoc)
+mark_as_advanced(PANDOC_EXE) # Don't show in CMake UIs
+
 if(NOT ASCIIDOCTOR_EXE)
   message(WARNING "Could not find asciidoctor; documentation will not be generated")
 else()
-  function(generate_doc backend adoc_file output_file)
+  function(generate_doc type adoc_file output_file)
     add_custom_command(
       OUTPUT "${output_file}"
       COMMAND
-        ${ASCIIDOCTOR_EXE}
-          -o "${output_file}"
-          -a revnumber="${CCACHE_VERSION}"
-          -a icons=font
-          -a toc=left
-          -a sectanchors
-          -a stylesheet="${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css"
-          -b "${backend}"
-          "${CMAKE_SOURCE_DIR}/${adoc_file}"
+        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate-${type}"
+        "${ASCIIDOCTOR_EXE}"
+        "${PANDOC_EXE}"
+        "${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css"
+        "${CCACHE_VERSION}"
+        "${CMAKE_SOURCE_DIR}/${adoc_file}"
+        "${output_file}"
       MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/${adoc_file}"
       DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css"
     )
-    if(${backend} STREQUAL manpage)
-      # Convert monospace to bold since that's typically rendered better when
-      # viewing the man page.
-      add_custom_command(
-        OUTPUT "${output_file}"
-        COMMAND perl -pi -e "'s!\\\\f\\(CR(.*?)\\\\fP!\\\\fB\\1\\\\fP!g'" "${output_file}"
-        APPEND
-      )
-    endif()
-    if("${backend}" STREQUAL manpage)
+
+    if("${type}" STREQUAL manpage)
       install(
         FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}"
         DESTINATION "${CMAKE_INSTALL_MANDIR}/man1"
       )
-    else()
+    elseif("${type}" STREQUAL html)
       set(html_doc_files "${html_doc_files}" "${output_file}" PARENT_SCOPE)
       install(
-        FILES "${CMAKE_SOURCE_DIR}/${adoc_file}" "${CMAKE_CURRENT_BINARY_DIR}/${output_file}"
+        FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}"
+        DESTINATION "${CMAKE_INSTALL_DOCDIR}"
+      )
+    elseif("${type}" STREQUAL markdown)
+      set(markdown_doc_files "${markdown_doc_files}" "${output_file}" PARENT_SCOPE)
+      install(
+        FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}"
         DESTINATION "${CMAKE_INSTALL_DOCDIR}"
       )
     endif()
@@ -52,6 +51,19 @@ else()
   generate_doc(html    doc/NEWS.adoc    NEWS.html)
   add_custom_target(doc-html DEPENDS "${html_doc_files}")
 
+  if(PANDOC_EXE)
+    #
+    # Markdown documentation
+    #
+    generate_doc(markdown LICENSE.adoc     LICENSE.md)
+    generate_doc(markdown doc/AUTHORS.adoc AUTHORS.md)
+    generate_doc(markdown doc/MANUAL.adoc  MANUAL.md)
+    generate_doc(markdown doc/NEWS.adoc    NEWS.md)
+    add_custom_target(doc-markdown DEPENDS "${markdown_doc_files}")
+  else()
+    message(WARNING "Could not find pandoc; markdown documentation will not be generated")
+  endif()
+
   #
   # Man page
   #
@@ -59,4 +71,7 @@ else()
   add_custom_target(doc-man-page DEPENDS ccache.1)
 
   add_custom_target(doc ALL DEPENDS doc-html doc-man-page)
+  if(PANDOC_EXE)
+    add_dependencies(doc doc-markdown)
+  endif()
 endif()

diff --git a/doc/INSTALL.md b/doc/INSTALL.md
index fb3fdcd308c175a9e11f879cba2b789e76f4c2d4..08a55da7c8ee6a6ea30df2bd0c7cf936e5fb5843 100644 (file)
--- a/doc/INSTALL.md
+++ b/doc/INSTALL.md
@@ -13,9 +13,11 @@ To build ccache you need:
 
 Optional:
 
-- GNU Bourne Again SHell (bash) for tests.
-- [Asciidoctor](https://asciidoctor.org) to build the HTML documentation.
-- [Python](https://www.python.org) to debug and run the performance test suite.
+- [Bash](https://www.gnu.org/software/bash) and [Python](https://www.python.org)
+  to run the test suite.
+- [Asciidoctor](https://asciidoctor.org) to build documentation in HTML and
+  Markdown format.
+- [Pandoc](https://pandoc.org) to build documentation in Markdown format.
 
 See also [CI configurations](../.github/workflows/build.yaml) for regularly
 tested build setups, including cross-compilation and dependencies required in

diff --git a/doc/scripts/generate-html b/doc/scripts/generate-html
new file mode 100755 (executable)
index 0000000..ce60a76
--- /dev/null
+++ b/doc/scripts/generate-html
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+set -euo pipefail
+
+asciidoctor=$1
+pandoc=$2
+stylesheet=$3
+version=$4
+input=$5
+output=$6
+
+"${asciidoctor}" \
+  -a revnumber="${version}" \
+  -a icons=font \
+  -a toc=left \
+  -a sectanchors \
+  -a stylesheet="${stylesheet}" \
+  -b html \
+  -o "${output}" \
+  "${input}"

diff --git a/doc/scripts/generate-manpage b/doc/scripts/generate-manpage
new file mode 100755 (executable)
index 0000000..10795bd
--- /dev/null
+++ b/doc/scripts/generate-manpage
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -euo pipefail
+
+asciidoctor=$1
+pandoc=$2
+stylesheet=$3
+version=$4
+input=$5
+output=$6
+
+tmpfile=$(mktemp)
+trap 'rm -f "${tmpfile}"' EXIT
+
+"${asciidoctor}" \
+  -a revnumber="${version}" \
+  -a icons=font \
+  -a toc=left \
+  -a sectanchors \
+  -a stylesheet="${stylesheet}" \
+  -b manpage \
+  -o "${tmpfile}" \
+  "${input}"
+
+# Convert monospace to bold since that's typically rendered better when viewing
+# the man page.
+perl -pe "'s!\\\\f\\(CR(.*?)\\\\fP!\\\\fB\\1\\\\fP!g'" "${tmpfile}" >"${output}"

diff --git a/doc/scripts/generate-markdown b/doc/scripts/generate-markdown
new file mode 100755 (executable)
index 0000000..c180d05
--- /dev/null
+++ b/doc/scripts/generate-markdown
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -euo pipefail
+
+asciidoctor=$1
+pandoc=$2
+stylesheet=$3
+version=$4
+input=$5
+output=$6
+
+tmpfile=$(mktemp)
+trap 'rm -f "${tmpfile}"' EXIT
+
+"${asciidoctor}" \
+  -a revnumber="${version}" \
+  -a icons=font \
+  -a toc=left \
+  -a sectanchors \
+  -a stylesheet="${stylesheet}" \
+  -b docbook \
+  -o "${tmpfile}" \
+  "${input}"
+
+# "\\-" -> "- " in tables, "-" otherwise
+pandoc -f docbook -t markdown "${tmpfile}" | \
+    sed -e 's/\\- /-  /' -e 's/\\-/-/' >"${output}"

diff --git a/misc/Makefile.posix-binary-release b/misc/Makefile.posix-binary-release
index da8c8c8b21481aefc31e194d71e37ec08787801a..1d7a7b49fa4abb16861a9daf99bec124d5c5d704 100644 (file)
--- a/misc/Makefile.posix-binary-release
+++ b/misc/Makefile.posix-binary-release
@@ -9,14 +9,14 @@ sysconfdir = $(prefix)/etc
 
 default_sysconfdir = /usr/local/etc
 doc_files = \
-    LICENSE.adoc \
+    LICENSE.md \
     LICENSE.html \
-    MANUAL.adoc \
+    MANUAL.md \
     MANUAL.html \
-    NEWS.adoc \
+    NEWS.md \
     NEWS.html \
     GPL-3.0.txt \
-    LICENSE.adoc \
+    LICENSE.md \
     README.md
 
 PYTHON = python3