Merge pull request #4053 from grandixximo/docs/asciidoctor-migration

docs: migrate documentation toolchain from asciidoc-py + dblatex to asciidoctor

Author: BsAtHome

.github/scripts/build-doc.sh

@@ -5,7 +5,9 @@ set -x
 
 cd src
 ./autogen.sh
-./configure --disable-check-runtime-deps --enable-build-documentation=html
+./configure --disable-check-runtime-deps \
+            --enable-build-documentation=html \
+            --enable-build-documentation-translation
 make -O -j$((1+$(nproc))) manpages
 make -O -j$((1+$(nproc))) translateddocs
 make -O -j$((1+$(nproc))) docs

.gitignore

@@ -50,10 +50,14 @@ position.txt
 # Ignore temp files
 *.swp
 *~
+# Ignore checkref leftover output (docs/src/checkref)
+.checklink.*.tmp
 # Ignore po4a temp files
 *.failed.po
 *-new_??.po
 # Ignore stamp files
 *.*-stamp
 # Ignore VSCode settings
 .vscode/settings.json
+# autoreconf cache from debian/configure
+/autom4te.cache/

debian/configure

@@ -110,19 +110,7 @@ elif [ -f /etc/lsb-release ]; then
 fi
 
 if [ -n "$ENABLE_BUILD_DOCUMENTATION" ]; then
-    DOC_DEPENDS="dblatex (>= 0.2.12),\n    dvipng,\n    fonts-dejavu,\n    graphviz,\n    groff,\n    inkscape,\n    librsvg2-bin,\n    python3-lxml,\n    source-highlight,\n    texlive-extra-utils,\n    texlive-font-utils,\n    texlive-fonts-recommended,\n    texlive-lang-cyrillic,\n    texlive-lang-european,\n    texlive-lang-french,\n    texlive-lang-german,\n    texlive-lang-polish,\n    texlive-lang-spanish,\n    texlive-latex-recommended,\n    w3c-linkchecker,\n    xsltproc"
-    
-
-    case $DISTRIB_NAME in
-        Debian-9)
-            ;; # No xetex in Debian 9 Stretch
-        *)
-            # Not quite sure which packages is needed for xetex, but
-            # texlive-xetex seem like a safe choice.  Need xetex to be
-            # able to build Chinese PDF.
-            DOC_DEPENDS="$DOC_DEPENDS,\n    texlive-xetex"
-            ;;
-    esac
+    DOC_DEPENDS="asciidoctor,\n    asciidoctor-pdf | ruby-asciidoctor-pdf,\n    fonts-dejavu,\n    fonts-noto-cjk,\n    ghostscript,\n    graphviz,\n    librsvg2-bin,\n    python3-fonttools,\n    ruby-rouge,\n    w3c-linkchecker"
 else
     DOC_DEPENDS=''
 fi

debian/control.top.in

@@ -12,12 +12,10 @@ Build-Depends:
     @KERNEL_HEADERS@,
     @MODUTILS_DEPENDS@,
     @EXTRA_BUILD@,
-    docbook-xsl <!nodoc>,
-    asciidoc,
-    ghostscript <!nodoc>,
     groff-base <!nodoc>,
     imagemagick <!nodoc>,
-    asciidoc-dblatex <!nodoc>,
+    asciidoctor <!nodoc>,
+    libunicode-linebreak-perl <!nodoc>,
     autoconf,
     automake,
     bwidget (>= 1.7),

debian/rules.in

@@ -33,7 +33,8 @@ export TIME:=$(shell LANG=C date --date='@$(TIMESTAMP)' '+%T')
 kernel_version = @KERNEL_VERSION@
 configure_realtime_arg = @CONFIGURE_REALTIME_ARG@
 ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
-enable_build_documentation = @ENABLE_BUILD_DOCUMENTATION@
+enable_build_documentation = @ENABLE_BUILD_DOCUMENTATION@ \
+    --enable-build-documentation-translation
 endif
 SRCDIR = $(CURDIR)/src
 DESTDIR=$(CURDIR)/debian/tmp
@@ -123,9 +124,14 @@ ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 	dh_installdocs --doc-main-package=@MAIN_PACKAGE_NAME@ --package=linuxcnc-doc-en
 	mv debian/linuxcnc-doc-en/usr/share/doc/@MAIN_PACKAGE_NAME@ debian/linuxcnc-doc-en/usr/share/doc/linuxcnc
 
-# Remove files for translations created where we do not want Debian packages.
-	for l in ar es fr ru uk zh_CN; do \
-		$(RM) -f debian/tmp/usr/share/doc/linuxcnc/LinuxCNC_*_$$l.pdf; \
+# Remove PDF files for translated locales that have no Debian package.
+# The authoritative locale list lives in docs/po4a.cfg's [po4a_langs]
+# line; only en and de get their own -doc package, every other locale
+# in that list has its PDFs dropped from the tmp staging area.
+	for l in $$(sed -e's/#.*//' docs/po4a.cfg | grep '^\[po4a_langs\]' | cut -d" " -f2-); do \
+		if [ "$$l" != "de" ]; then \
+			$(RM) -f debian/tmp/usr/share/doc/linuxcnc/LinuxCNC_*_$$l.pdf; \
+		fi; \
 	done
 	$(RM) -f debian/tmp/usr/share/doc/linuxcnc/*_es.adoc
 else

docs/help/tklinuxcnc.adoc

@@ -3,11 +3,6 @@
 
 = TkLinuxCNC
 
-// Custom lang highlight
-// must come after the doc title, to work around a bug in asciidoc 8.6.6
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
 
 == Menus
 
@@ -157,7 +152,7 @@ To change these settings, use the '@' key for Commanded/Actual, and
 the '#' key for Absolute/Relative. The default values can be set in
 the INI file, e.g.,
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 POSITION_OFFSET =   RELATIVE
@@ -166,7 +161,7 @@ POSITION_FEEDBACK = ACTUAL
 
 or
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 POSITION_OFFSET =   ABSOLUTE

docs/html/gcode.html

@@ -41,6 +41,7 @@
 tr.odd td { background: #d9d9d9; }
 tr.head td, tr.head th { background: black; color: white; }
 --></style>
+<link rel="stylesheet" href="lcnc-overrides.css"/>
 </head>
 
 <body>

docs/html/index.css

@@ -13,3 +13,9 @@ p {
   margin-top: 0em;
   margin-bottom: 0em;
 }
+summary {
+  margin-top: 0.65em;
+  margin-bottom: 0.15em;
+  font-family: sans-serif;
+  cursor: pointer;
+}

docs/html/linuxcnc.css

@@ -1,11 +1,18 @@
-:target { background: #DEF !important;  }
+:target { background: #DEF !important; }
+body { margin: 1em 5% 1em 5%; }
 tt {font-family: "Courier New", Courier, monospace; font-size: 0.95em;}
 pre { font-family: monospace !important; }
+h1, h2, h3, h4, h5, h6 { font-family: Arial, Helvetica, sans-serif; }
 h1, h2 { background: #c0c0f0; padding-left: 0.5em;}
+h3, h4, h5, h6 { background: #DEF; padding-left: 0.5em; }
 h2 { padding-top: 0.35em; padding-bottom:0.15em;}
 h1, h2, h3, h4, h5 { border-bottom: 2px solid #8080c0; color: black; }
+
+@media (max-width: 768px) {
+    body { margin: 0.5em 2% 0.5em 2%; }
+}
 div.nav { float: right; background: #ffffff; }
-dt { font-weight: bold; }
+dt { font-weight: bold; color: #527bbd; margin-top: 0.5em; }
 pre { margin-left: 4ex; auto; color: black; padding: 1ex; }
 div.float { text-align: center; margin: 2ex; padding: 1ex; }
 div.float span.caption { display: block; margin: 1em; }
@@ -28,8 +35,16 @@ table.tableblock { border-collapse: collapse; margin-left: auto; margin-right: a
 .clist { -moz-column-width: 40ex; -moz-column-gap: 4ex }
 .nclist { -moz-column-width: 20ex; -moz-column-gap: 4ex }
 .nclist li { list-style-type: none; text-indent: -.5ex; }
+#toctitle {
+    font-family: Arial, Helvetica, sans-serif;
+    color: #527bbd;
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 1em;
+    margin-bottom: 0.3em;
+}
 .toc li { list-style-type: none; }
-.toc li a { display: block; border: 1px solid transparent; text-indent: -1ex; }
+.toc li a { border: 1px solid transparent; text-indent: -1ex; }
 
 /* AsciiDoc stuff */
 div.note {

docs/man/images/Images_info.adoc

@@ -57,4 +57,4 @@ ASCII art diagrams can be drawn e.g., with link:https://asciiflow.com/[asciiflow
    │           │
  ──┤is-on   off├──
    └───────────┘
-----
+----