From 6b4d436e840798016da5f024704638687c481c9c Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 30 May 2026 09:23:03 +0800 Subject: [PATCH 01/10] docs: add Rouge syntax highlighters for HAL, NGC, INI Three custom Rouge lexers for LinuxCNC's domain-specific languages, loaded by asciidoctor via -r flags in the build rules. - rouge_hal.rb: HAL component / pin / signal syntax - rouge_ngc.rb: G-code (RS-274NGC) with special-case handling for LinuxCNC #<_ini[...]NAME> and #<_hal[...]> parameter references - rouge_ini.rb: INI config syntax with # comment support --- docs/src/extensions/rouge_hal.rb | 90 ++++++++++++++++++++ docs/src/extensions/rouge_ini.rb | 48 +++++++++++ docs/src/extensions/rouge_ngc.rb | 136 +++++++++++++++++++++++++++++++ 3 files changed, 274 insertions(+) create mode 100644 docs/src/extensions/rouge_hal.rb create mode 100644 docs/src/extensions/rouge_ini.rb create mode 100644 docs/src/extensions/rouge_ngc.rb diff --git a/docs/src/extensions/rouge_hal.rb b/docs/src/extensions/rouge_hal.rb new file mode 100644 index 00000000000..5ce2e3416fc --- /dev/null +++ b/docs/src/extensions/rouge_hal.rb @@ -0,0 +1,90 @@ +# docs/src/extensions/rouge_hal.rb +# +# Rouge lexer for LinuxCNC HAL (Hardware Abstraction Layer) script files. +# Ported from docs/src/source-highlight/hal.lang (Michael Haberler, 2011). +# +# Highlights: +# - halcmd commands (loadrt, net, setp, addf, ...) +# - pin / signal names of the form component.pin-name +# - INI substitutions of the form [SECTION]NAME (any case) +# - environment variables $VAR $(VAR) +# - assignment operators = => <= +# - numbers in decimal, hex (0x..), octal (0o..), and binary (0b..) +# - comments (# ...) +# +# Loaded via the asciidoctor -r flag from the docs Submakefile. + +require 'rouge' + +module Rouge + module Lexers + class HAL < RegexLexer + title 'HAL' + desc 'LinuxCNC Hardware Abstraction Layer (halcmd)' + tag 'hal' + filenames '*.hal', '*.tcl.hal', '*.postgui.hal' + mimetypes 'text/x-hal' + + COMMANDS = %w[ + loadrt unloadrt loadusr waitusr unloadusr + newsig delsig sets gets stype ptype getp setp + linkps linksp linkpp net unlinkp + addf delf start stop + show item save source + alias unalias list + lock unlock status help + echo + initf + ].join('|').freeze + + identifier = /[a-zA-Z_][a-zA-Z0-9_]*/ + + state :root do + rule %r/\s+/, Text + rule %r/#.*$/, Comment::Single + + # Commands as the first non-space token of a line + rule %r/(?<=^|\s)(?:#{COMMANDS})\b/i, Keyword + + # Assignment operators + rule %r/=>|<=|=/, Operator + + # INI substitution: [SECTION]NAME -- LinuxCNC accepts any case + # for both the section name and the variable name (it normalises + # internally), so the lexer follows the source-highlight ini.lang + # convention of taking any letter/digit/underscore. + rule %r/(\[)(#{identifier})(\])(#{identifier})/ do + groups Punctuation, Name::Namespace, Punctuation, Name::Property + end + + # Environment variables (POSIX shell rules: any case allowed) + rule %r/\$\([A-Za-z_]\w*\)/, Name::Variable + rule %r/\$[A-Za-z_]\w*/, Name::Variable + + # Pin/signal names: token with at least one dot + rule %r/[A-Za-z_][\w-]*(?:\.[\w-]+)+/, Name::Attribute + + # Numbers + # - hex / octal / binary integers (halcmd accepts 0x.., 0o.., 0b..) + rule %r/[+-]?0[xX][0-9a-fA-F]+/, Num::Hex + rule %r/[+-]?0[oO][0-7]+/, Num::Oct + rule %r/[+-]?0[bB][01]+/, Num::Bin + # - floats: must have either a decimal point or an exponent + rule %r/[+-]?\d+\.\d+(?:[eE][+-]?\d+)?/, Num::Float + rule %r/[+-]?\d+[eE][+-]?\d+/, Num::Float + # - decimal integers (no exponent) + rule %r/[+-]?\d+/, Num::Integer + + # Quoted strings (rare in HAL but used in echo / save args) + rule %r/"[^"\n]*"/, Str::Double + rule %r/'[^'\n]*'/, Str::Single + + # Bare token: signal or component name without dots + rule %r/[A-Za-z_][\w-]*/, Name + + # Anything else + rule %r/./, Text + end + end + end +end diff --git a/docs/src/extensions/rouge_ini.rb b/docs/src/extensions/rouge_ini.rb new file mode 100644 index 00000000000..a3c4ff3630e --- /dev/null +++ b/docs/src/extensions/rouge_ini.rb @@ -0,0 +1,48 @@ +# docs/src/extensions/rouge_ini.rb +# +# Fixes Rouge's default INI lexer for LinuxCNC INI files: +# - accepts `#`/`;` comments without a trailing newline (end of file/block), +# - accepts leading whitespace before `key = value` lines, +# - highlights the `#INCLUDE` directive as a preprocessor token. +# +# Reopening `state :basic do` would replace the upstream rules and lose the +# whitespace handler, so we rebuild it explicitly here. +# +# Loaded via the asciidoctor -r flag from the docs Submakefile. + +require "rouge" + +module Rouge + module Lexers + class INI < RegexLexer + title "INI" + desc "INI with LinuxCNC #INCLUDE + tolerant comments / whitespace" + + identifier = /[a-zA-Z_][a-zA-Z0-9_]*/ + + state :includefile do + # An include directive must start at the first character on the line + # and has a strict line format with mandatory leading and optional + # trailing whitespace arround the filename. + rule %r/^(#INCLUDE)(\s+)(.*)(\s*)$/ do + groups Keyword, Text, Str, Text + end + end + + state :root do + mixin :includefile + mixin :basic + + rule %r/(#{identifier})(\s*)(=)/ do + groups Name::Property, Text, Punctuation + push :value + end + + rule %r/^[ \t]*[;#][^\n]*(?=\n|\z)/, Comment + rule %r/(\[)(#{identifier})(\])(\s*)([;#].*)?/ do + groups Punctuation, Name::Namespace, Punctuation, Text, Comment + end + end + end + end +end diff --git a/docs/src/extensions/rouge_ngc.rb b/docs/src/extensions/rouge_ngc.rb new file mode 100644 index 00000000000..5ba7311b0e4 --- /dev/null +++ b/docs/src/extensions/rouge_ngc.rb @@ -0,0 +1,136 @@ +# docs/src/extensions/rouge_ngc.rb +# +# Rouge lexer for LinuxCNC NGC (RS-274/EMC dialect G-code) files. +# Ported from docs/src/source-highlight/ngc.lang (Michael Haberler 2011, +# originally adapted from Jan Van Gilsen's gedit highlight definition). +# +# Highlights: +# - line numbers N123 +# - G / M / T / H / F / S codes +# - axis letters X Y Z A B C U V W (Name::Attribute) +# - parameter letters I J K P Q R L D E (Name::Decorator) +# - numeric, named, and indexed parameters #1 #5421 # +# - LinuxCNC system parameters #<_ini[SECTION]NAME> / #<_hal[pin.name]> +# - O-word blocks with their keywords (sub, while, if, call, ...) +# - math functions and boolean operators +# - comments: ( ... ) ; rest-of-line (DEBUG, ...) +# +# Loaded via the asciidoctor -r flag from the docs Submakefile. + +require 'rouge' + +module Rouge + module Lexers + class NGC < RegexLexer + title 'NGC' + desc 'RS-274 G-code, LinuxCNC dialect' + tag 'ngc' + aliases 'gcode', 'rs274ngc' + filenames '*.ngc', '*.nc', '*.tap' + mimetypes 'text/x-ngc' + + MATH = %w[ + cos sin tan acos asin atan + exp ln sqrt + fup fix round + abs exists + ].join('|').freeze + + BOOL = %w[and or xor not mod gt lt ge le eq ne].join('|').freeze + + OWORD = %w[ + sub endsub return + if elseif else endif + while endwhile do break continue + repeat endrepeat + call + ].join('|').freeze + + identifier = /[a-zA-Z_][a-zA-Z0-9_]*/ + + # This definition limits hal pin names to minimum 2 characters. + # Should be no problem. + halpinname = /[a-zA-Z][a-zA-Z0-9_.-]*[a-zA-Z0-9]/ + + state :root do + rule %r/\s+/, Text + + # Line numbers (N123 at start of statement) + rule %r/(?<=^|\s)[nN]\d+/, Comment::Preproc + + # Comments + rule %r/;.*$/, Comment::Single + rule %r/\([dD][eE][bB][uU][gG],/, Comment::Special, :debug_comment + rule %r/\([^)]*\)/, Comment::Multiline + + # LinuxCNC system parameters that read live values from outside + # the gcode scope. These are very LinuxCNC-flavoured so they + # get a dedicated token split that highlights the section / + # pin name distinctly from the surrounding parameter wrapper: + # + # #<_ini[SECTION]NAME> - value of NAME in [SECTION] of the INI + # #<_hal[pin.or.signal]> - current value of a HAL pin or signal + rule %r/(#<)(_ini)(\[)(#{identifier})(\])(#{identifier})(>)/i do + groups Punctuation, Name::Builtin, Punctuation, + Name::Namespace, Punctuation, Name::Property, Punctuation + end + rule %r/(#<)(_hal)(\[)(#{halpinname})(\])(>)/i do + groups Punctuation, Name::Builtin, Punctuation, + Name::Namespace, Punctuation, Punctuation + end + + # Parameters (named / numbered, generic) + rule %r/#<[^>]+>/, Name::Variable + rule %r/#\d+/, Name::Variable + + # O-word lines: O sub or O100 if + rule %r/(?i:[oO])(?:\d+|<[A-Za-z_][\w-]*>)/, Name::Label + rule %r/(?i:#{OWORD})\b/, Keyword::Reserved + + # Math + boolean operator names + rule %r/(?i:#{MATH})\b/, Name::Builtin + rule %r/(?i:#{BOOL})\b/, Operator::Word + + # G / M codes (G33.1, G92.2, M62, ...) + rule %r/(?i:g)\d+(?:\.\d+)?/, Keyword + rule %r/(?i:m)\d+/, Keyword + + # T H F S codes + rule %r/(?i:[tfsh])-?\d+(?:\.\d+)?/, Keyword + + # Axis letters X Y Z A B C U V W followed by a value or expression + rule %r/(?i:[xyzabcuvw])(?=\s*[-+\[\d#])/, Name::Attribute + + # Argument / parameter letters I J K L P Q R D E + # (call-by-name arguments, arc centres, dwell times, etc.). + # Highlighted differently from the axes so users can see at a + # glance which letters move the tool vs. which configure the move. + rule %r/(?i:[ijklpqrde])(?=\s*[-+\[\d#])/, Name::Decorator + + # Arithmetic / brackets + rule %r{[+\-*/=]}, Operator + rule %r/[\[\]]/, Punctuation + + # Numbers: floats must have a decimal point or an exponent; + # integers are decimal only (LinuxCNC's RS-274 dialect does not + # accept hex or other radixes for numeric literals). + rule %r/[+-]?\d+\.\d*(?:[eE][+-]?\d+)?/, Num::Float + rule %r/[+-]?\.\d+(?:[eE][+-]?\d+)?/, Num::Float + rule %r/[+-]?\d+[eE][+-]?\d+/, Num::Float + rule %r/[+-]?\d+/, Num::Integer + + rule %r/./, Text + end + + # (DEBUG, ...): same as a comment, but parameter references inside + # should still be highlighted as variables (DEBUG expands them at + # run time). + state :debug_comment do + rule %r/\)/, Comment::Special, :pop! + rule %r/#<[^>]+>/, Name::Variable + rule %r/#\d+/, Name::Variable + rule %r/[^)#]+/, Comment::Special + end + end + end +end From 64920485074805c31cbe558bf30d9da251e590f4 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 30 May 2026 09:23:10 +0800 Subject: [PATCH 02/10] docs: add asciidoctor extensions for image lookup and cross-doc xrefs - image_resolver.rb: treeprocessor that resolves image targets the way the asciidoc-py build did (per-language tree with English fallback). Auto-substitutes foo_en.ext -> foo_.ext. No DEFAULT_LANGS fallback; requires the doc-languages attribute set from po4a.cfg. - xref_resolver.rb: preprocessor that resolves bare <> cross-document references to the right per-document HTML target. --- docs/src/extensions/image_resolver.rb | 225 ++++++++++++++++++++++++++ docs/src/extensions/xref_resolver.rb | 130 +++++++++++++++ 2 files changed, 355 insertions(+) create mode 100644 docs/src/extensions/image_resolver.rb create mode 100644 docs/src/extensions/xref_resolver.rb diff --git a/docs/src/extensions/image_resolver.rb b/docs/src/extensions/image_resolver.rb new file mode 100644 index 00000000000..2756bca5f02 --- /dev/null +++ b/docs/src/extensions/image_resolver.rb @@ -0,0 +1,225 @@ +# docs/src/extensions/image_resolver.rb +# +# Asciidoctor treeprocessor that resolves image targets the way the +# asciidoc-py + docs/src/image-wildcard pair did, plus a LinuxCNC- +# specific language-suffix swap: +# - relative image paths in an included file are resolved relative to +# that included file's directory (not the top-level master) +# - missing extension is filled in by trying png/svg/jpg/jpeg +# - when the .adoc being processed lives under docs/src// and +# the macro points at `foo_en.ext`, the resolver looks for +# `foo_.ext` first and falls back to `foo_en.ext` if the +# translated variant is not in the tree. Implements the naming +# convention BsAtHome proposed on #4053: img_en.ext is the default, +# img_.ext (when it exists) is the translated override. +# +# Requires the document to be loaded with sourcemap: true (passed on the +# CLI as -a sourcemap=true) so blocks expose .file. + +require 'asciidoctor' +require 'asciidoctor/extensions' + +module LinuxCNCDocs + class ImageResolver < Asciidoctor::Extensions::Treeprocessor + IMAGE_EXTS = %w[.png .svg .jpg .jpeg].freeze + # Inline image: macros, with target as captured group 1. Skip the + # block image:: form (handled by find_by(:image)) and anything that + # already looks like a URL or absolute path. + INLINE_IMAGE_RE = /(?` filename to `*_.`. The check + # is anchored to the basename so paths that happen to contain `_en` + # earlier are not touched. + def swap_lang(target, lang) + target.sub(/_en(\.[A-Za-z0-9]+)\z/, "_#{lang}\\1") + end + + # Try the requested path; fall back to the canonical English source + # if the request points into a translated tree. Image directories + # under docs/src// are not always populated for every macro a + # translated file references, but the English original at + # docs/src/.../ usually exists. + def resolve_candidate(path, lang_re) + probe = ->(p) { + return p if File.file?(p) + r = resolve_extension(p) + return r if r && File.file?(r) + nil + } + r = probe.call(path) + return r if r + return nil unless lang_re + fallback = path.sub(lang_re, '/src/') + fallback != path ? probe.call(fallback) : nil + end + + def rewrite_inline_in_block(block) + base_dir = File.dirname(File.expand_path(block.file)) + lang_re = lang_re_for(block.document) + lang = lang_re && (m = lang_re.match(block.file.to_s)) ? m[1] : 'en' + pdf = block.document.backend == 'pdf' + + # :paragraph / :literal / :sidebar etc. carry source in .lines (Array). + if block.respond_to?(:lines=) && block.lines.is_a?(Array) && !block.lines.empty? + changed = false + new_lines = block.lines.map { |ln| rewrite_inline(ln, base_dir, lang, lang_re, pdf) { changed = true } } + block.lines = new_lines if changed + end + + # :list_item carries source in .text (String). + if block.respond_to?(:text=) && block.instance_variable_defined?(:@text) + old = block.instance_variable_get(:@text) + if old.is_a?(String) && !old.empty? + changed = false + new_text = rewrite_inline(old, base_dir, lang, lang_re, pdf) { changed = true } + block.text = new_text if changed + end + end + end + + def rewrite_inline(text, base_dir, lang, lang_re, pdf) + text.gsub(INLINE_IMAGE_RE) do + full = Regexp.last_match(0) + target = Regexp.last_match(1) + next full if target.start_with?('http://', 'https://', '/') + next full if target.include?('{') + + if lang != 'en' + swapped = swap_lang(target, lang) + if swapped != target + abs = resolve_candidate(File.expand_path(swapped, base_dir), lang_re) + if abs + yield if block_given? + next "image:#{pdf ? abs : swapped}[" + end + end + end + + next full unless pdf + candidate = resolve_candidate(File.expand_path(target, base_dir), lang_re) + if candidate + yield if block_given? + "image:#{candidate}[" + else + full + end + end + end + + # asciidoctor-pdf renders raster images at native pixel dimensions + # interpreted as 72 DPI, then caps at content width. Most of our + # source PNGs are screenshots/diagrams sized for ~150 DPI display, so + # the default behaviour blows them up to full text column width and + # leaves big half-blank pages where they break across a page boundary. + # dblatex defaulted to a smaller fit. Approximate that by setting a + # default pdfwidth when the source did not pin width/scaledwidth/pdfwidth. + def apply_default_width(node) + return if node.context == :inline_image + return if node.attr('pdfwidth') + return if node.attr('scaledwidth') + return if node.attr('width') + node.set_attr('pdfwidth', '75%') + end + + def resolve_extension(path) + return path if File.file?(path) + return nil unless File.extname(path).empty? + IMAGE_EXTS.each do |e| + c = path + e + return c if File.file?(c) + end + nil + end + end +end + +Asciidoctor::Extensions.register do + treeprocessor LinuxCNCDocs::ImageResolver +end diff --git a/docs/src/extensions/xref_resolver.rb b/docs/src/extensions/xref_resolver.rb new file mode 100644 index 00000000000..0cd6a75921a --- /dev/null +++ b/docs/src/extensions/xref_resolver.rb @@ -0,0 +1,130 @@ +# docs/src/extensions/xref_resolver.rb +# +# Asciidoctor preprocessor that resolves bare <> cross-doc +# references to qualified <> form, the way +# asciidoc-py used to do via objects/xref_.links. +# +# Wire-up (in Submakefile): +# asciidoctor -r $(DOC_SRCDIR)/extensions/xref_resolver.rb \ +# -a xref-root=$(DOC_SRCDIR) \ +# ... +# For translated trees pass xref-root=$(DOC_SRCDIR)/ so anchors from +# de/ don't leak into en/ etc. + +require 'asciidoctor' +require 'asciidoctor/extensions' +require 'pathname' +require 'digest' +require 'json' +require 'fileutils' + +module LinuxCNCDocs + class XrefResolver < Asciidoctor::Extensions::Preprocessor + INDEX_CACHE = {} + + # Anchor definition forms recognised: + # [[id]] block anchor + # [[id,reftext]] block anchor with reference text + # [#id] shorthand id + # [id="foo"] block-attribute id (single or double quotes) + # :id: foo document-level id attribute (rare) + ANCHOR_DEF = / + \[\[ ([A-Za-z_][\w:.-]*) (?:,[^\]]*)? \]\] | + \[\# ([A-Za-z_][\w:.-]*) (?:[.%][^\]]*)? \] | + \[ (?:[^,\]]*,\s*)* id\s*=\s*["']? ([A-Za-z_][\w:.-]*) ["']? [,\]] | + ^:id:\s* ([A-Za-z_][\w:.-]*) + /x + + XREF_USE = / + << + ([A-Za-z_][\w:.-]*) # bare anchor (no path) + (,[^>]*?)? # optional ,title + >> + /xm + + CACHE_DIR = ENV['LINUXCNC_DOCS_XREF_CACHE'] || '/tmp/lcnc-xref-cache' + + def self.build_index(root, exclude_re = nil) + cache_key = [root, exclude_re&.source].compact.join('|') + key = File.expand_path(cache_key) + return INDEX_CACHE[key] if INDEX_CACHE.key?(key) + + cache_file = File.join(CACHE_DIR, "#{Digest::SHA1.hexdigest(key)}.json") + paths = Pathname.glob(File.join(root, '**', '*.adoc')) + if exclude_re + root_p = Pathname.new(File.expand_path(root)) + paths = paths.reject do |p| + rel = p.expand_path.relative_path_from(root_p).to_s + exclude_re.match?(rel) + end + end + mtime_max = paths.map { |p| p.mtime.to_f }.max || 0.0 + if File.exist?(cache_file) + cached = JSON.parse(File.read(cache_file)) rescue nil + if cached && cached['mtime'].to_f >= mtime_max + INDEX_CACHE[key] = cached['index'] + return cached['index'] + end + end + + idx = {} + paths.each do |path| + path.each_line do |line| + line.scan(ANCHOR_DEF) do |a, b, c, d| + anchor = a || b || c || d + next unless anchor + target = path.expand_path.to_s + if idx[anchor] && idx[anchor] != target + warn "xref_resolver: duplicate anchor '#{anchor}' in " \ + "#{path} (already in #{idx[anchor]})" + next + end + idx[anchor] = target + end + end + end + + FileUtils.mkdir_p(CACHE_DIR) + File.write(cache_file, JSON.dump('mtime' => mtime_max, 'index' => idx)) + INDEX_CACHE[key] = idx + end + + def process(document, reader) + docfile = document.attr 'docfile' + return reader unless docfile + + root = document.attr('xref-root') || + document.attr('docdir') || + File.dirname(docfile) + exclude_pat = document.attr('xref-exclude') + exclude_re = exclude_pat && !exclude_pat.empty? ? Regexp.new(exclude_pat) : nil + idx = self.class.build_index(File.expand_path(root), exclude_re) + src_dir = Pathname.new(File.dirname(File.expand_path(docfile))) + self_path = File.expand_path(docfile) + + # Join lines first so multi-line <<...\n...>> is matched as one. + joined = reader.lines.join("\n") + + rewritten = joined.gsub(XREF_USE) do + full = Regexp.last_match(0) + anchor = Regexp.last_match(1) + tail = Regexp.last_match(2) || '' + # Pass through if line already looks qualified. + next full if full.include?('.adoc#') + target = idx[anchor] + if target && target != self_path + relpath = Pathname.new(target).relative_path_from(src_dir).to_s + "<<#{relpath}##{anchor}#{tail}>>" + else + full + end + end + + Asciidoctor::PreprocessorReader.new(document, rewritten.split("\n", -1), reader.cursor) + end + end +end + +Asciidoctor::Extensions.register do + preprocessor LinuxCNCDocs::XrefResolver +end From 3c0364eb6faa55d9d4e8af423a68e89d33e7f8e8 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 30 May 2026 09:23:31 +0800 Subject: [PATCH 03/10] docs: HTML/PDF theme CSS overrides and docinfo - lcnc-overrides.css: theme on top of asciidoctor's default stylesheet. Light + dark via prefers-color-scheme (no toggle, no JS). Heading colors #1a3a6c (incl. #header h1 per hansu). Uniform listing background, inline code rounding, dark-mode SVG card wrapper. - pdf-theme.yml: asciidoctor-pdf theme; CJK + DejaVu fonts. - docinfo.html: shared docinfo for asciidoctor (docinfo=shared). - docs/html/index.css, linuxcnc.css, gcode.html: static landing-page styling refresh; removes external font fetches. - docs/src/index.tmpl: master HTML index template polish (JS-free per bertho's patch); @TRANSLATIONS@ / @ENDTRANSLATIONS@ gated by build. --- docs/html/gcode.html | 1 + docs/html/index.css | 6 + docs/html/linuxcnc.css | 21 +- docs/src/docinfo.html | 1 + docs/src/index.tmpl | 208 +++++++------------ docs/src/lcnc-overrides.css | 394 ++++++++++++++++++++++++++++++++++++ docs/src/pdf-theme.yml | 130 ++++++++++++ 7 files changed, 621 insertions(+), 140 deletions(-) create mode 100644 docs/src/docinfo.html create mode 100644 docs/src/lcnc-overrides.css create mode 100644 docs/src/pdf-theme.yml diff --git a/docs/html/gcode.html b/docs/html/gcode.html index c0a62e00f50..92d304f2ca8 100644 --- a/docs/html/gcode.html +++ b/docs/html/gcode.html @@ -41,6 +41,7 @@ tr.odd td { background: #d9d9d9; } tr.head td, tr.head th { background: black; color: white; } --> + diff --git a/docs/html/index.css b/docs/html/index.css index 64412577086..e044b029dbd 100644 --- a/docs/html/index.css +++ b/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; +} diff --git a/docs/html/linuxcnc.css b/docs/html/linuxcnc.css index aeb046f1c43..d9cf981f413 100644 --- a/docs/html/linuxcnc.css +++ b/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 { diff --git a/docs/src/docinfo.html b/docs/src/docinfo.html new file mode 100644 index 00000000000..50c9ce175fd --- /dev/null +++ b/docs/src/docinfo.html @@ -0,0 +1 @@ + diff --git a/docs/src/index.tmpl b/docs/src/index.tmpl index 4d2df8f1ab5..e6f2d57b049 100644 --- a/docs/src/index.tmpl +++ b/docs/src/index.tmpl @@ -1,91 +1,13 @@ - - - + + + LinuxCNC - + - - + @@ -119,14 +41,12 @@ function setup_page(){ Source • G-Code Quick Reference

-

-

Getting Started & Configuration

-

+Getting Started with LinuxCNC

-
+
+Getting Started with LinuxCNC +
+
-

+General User Information

-
+
+General User Information +
+
-

+Configuration Wizards

-
+
+Configuration Wizards +
+
-

+Configuration

-
+
+Configuration +
+
-

+HAL (Hardware Abstraction Layer)

-
+
+HAL (Hardware Abstraction Layer) +
+
-

+Hardware Drivers

-
+
+Hardware Drivers +
+
-

+Hardware Examples

-
+
+Hardware Examples +
+
-

+ClassicLadder

-
+
+ClassicLadder +
  • ClassicLadder is a software PLC (Programmable Logic Controller) built into LinuxCNC.
    • @@ -247,10 +174,11 @@ function setup_page(){
  • ClassicLadder Examples
+
-

+Advanced Topics

-
+
+Advanced Topics +
+
-

+Integrator Information

-
+
+Integrator Information +
+

Usage

-

+User Interfaces

-
+
+User Interfaces +
+
-

+G-code Programming

-
+
+G-code Programming +
+

Customization & Development

-

+Virtual Control Panels

-
+
+Virtual Control Panels +
+
-

+User Interface Programming

-
+
+User Interface Programming +
+
-

+Developer Information

-
+
+Developer Information +
+

General Information

-

+Glossary, Copyright, History & Overview

-
+
+Glossary, Copyright, History & Overview +
-
+ +
+

Man Pages

For more information about man pages see the Linux FAQ

-

-

diff --git a/docs/src/lcnc-overrides.css b/docs/src/lcnc-overrides.css new file mode 100644 index 00000000000..e41b7e43dc8 --- /dev/null +++ b/docs/src/lcnc-overrides.css @@ -0,0 +1,394 @@ +/* LinuxCNC HTML theme overrides. + + Sits on top of asciidoctor's default stylesheet (linked separately + as asciidoctor.css). Dark mode follows the OS / browser preference + via @media (prefers-color-scheme: dark); no toggle, no JS. + + Asciidoctor vs static landing pages are distinguished by the + asciidoctor-set body classes (.article / .book / .manpage); the + static rules use :not() of those classes so they target only + index.html / gcode.html. +*/ + +/* ====================================================================== + * Asciidoctor pages (light) + * ====================================================================== */ + +/* Asciidoctor caps #header / #content / #footnotes / #footer at + 62.5em (1000px) which leaves big empty margins on HD screens. + Use up to 95% of the viewport, capped at 100em (1600px), so wide + monitors get a wider content area without losing the line-length + ceiling on ultra-wide displays. #footer is excluded: the dark + footer bar spans the full viewport width. */ +body:is(.article,.book,.manpage) #header, +body:is(.article,.book,.manpage) #content, +body:is(.article,.book,.manpage) #footnotes { + max-width: min(95%, 100em); +} +body:is(.article,.book,.manpage) #footer { + max-width: none; +} + +/* #text# in compat-mode -> ; drop yellow. */ +body:is(.article,.book,.manpage) mark { + background: transparent; + color: inherit; +} + +/* Headings + block titles: asciidoctor default is #ba3925 (brick red). + Use near-black / very dark blue. Apply to h1..h6 and to .title + (image/listing/table captions) so figure captions like + "Figure 1. ..." stop rendering in red. */ +body:is(.article,.book,.manpage) #header h1, +body:is(.article,.book,.manpage) h1, +body:is(.article,.book,.manpage) h2, +body:is(.article,.book,.manpage) h3, +body:is(.article,.book,.manpage) h4, +body:is(.article,.book,.manpage) h5, +body:is(.article,.book,.manpage) h6, +body:is(.article,.book,.manpage) #toctitle, +body:is(.article,.book,.manpage) .title { + color: #1a3a6c; + font-weight: 400; +} + +/* Uniform grey background on every listing block (hal/ini/ngc/plain). */ +body:is(.article,.book,.manpage) .listingblock > .content, +body:is(.article,.book,.manpage) .literalblock > .content, +body:is(.article,.book,.manpage) .listingblock pre, +body:is(.article,.book,.manpage) .literalblock pre, +body:is(.article,.book,.manpage) .listingblock > .content > pre[class^="highlight"], +body:is(.article,.book,.manpage) .listingblock > .content > pre:not(.highlight), +body:is(.article,.book,.manpage) .literalblock pre.highlight { + background: #f7f7f7; +} + +/* ====================================================================== + * Asciidoctor pages (dark, opt-in via system preference) + * ====================================================================== */ +@media (prefers-color-scheme: dark) { + body:is(.article,.book,.manpage) { + background: #1e1e1e; + color: #e0e0e0; + } + body:is(.article,.book,.manpage) #header h1, + body:is(.article,.book,.manpage) h1, + body:is(.article,.book,.manpage) h2, + body:is(.article,.book,.manpage) h3, + body:is(.article,.book,.manpage) h4, + body:is(.article,.book,.manpage) h5, + body:is(.article,.book,.manpage) h6, + body:is(.article,.book,.manpage) #toctitle, + body:is(.article,.book,.manpage) .title { + color: #7fb8e8; + font-weight: 400; + } + body:is(.article,.book,.manpage) #preamble > .sectionbody > .paragraph p, + body:is(.article,.book,.manpage) #preamble > .sectionbody > .paragraph.lead > p { + color: #d0d0d0; + } + body:is(.article,.book,.manpage) a { color: #6fa8dc; } + body:is(.article,.book,.manpage) a:visited { color: #b48ead; } + + /* Single dark wrapper around listings: paint .content only, make + the inner 
 transparent.  Painting both gives a double-box. */
+  body:is(.article,.book,.manpage) .listingblock > .content,
+  body:is(.article,.book,.manpage) .literalblock > .content {
+    background: #2a2a2a;
+    color: #f0f0f0;
+  }
+  body:is(.article,.book,.manpage) .listingblock pre,
+  body:is(.article,.book,.manpage) .literalblock pre,
+  body:is(.article,.book,.manpage) .listingblock > .content > pre[class^="highlight"],
+  body:is(.article,.book,.manpage) .listingblock > .content > pre:not(.highlight),
+  body:is(.article,.book,.manpage) .literalblock pre.highlight,
+  body:is(.article,.book,.manpage) pre.rouge {
+    background: transparent !important;
+    background-color: transparent !important;
+    color: inherit;
+  }
+
+  /* Inline code/tt only.  pre code inside listingblock would
+     otherwise paint a second box inside the listing wrapper. */
+  body:is(.article,.book,.manpage) p code,
+  body:is(.article,.book,.manpage) li code,
+  body:is(.article,.book,.manpage) td code,
+  body:is(.article,.book,.manpage) tt {
+    background: #3a3a3a;
+    color: #f0f0f0;
+    padding: 1px 4px;
+    border-radius: 3px;
+  }
+  body:is(.article,.book,.manpage) pre code,
+  body:is(.article,.book,.manpage) .listingblock code,
+  body:is(.article,.book,.manpage) .literalblock code {
+    background: transparent !important;
+    padding: 0 !important;
+    color: inherit;
+  }
+
+  body:is(.article,.book,.manpage) table.tableblock,
+  body:is(.article,.book,.manpage) table.tableblock th,
+  body:is(.article,.book,.manpage) table.tableblock td {
+    border-color: #444;
+    color: #e0e0e0;
+    background: #1e1e1e;
+  }
+  body:is(.article,.book,.manpage) table.tableblock tbody tr th,
+  body:is(.article,.book,.manpage) table.tableblock tfoot tr th,
+  body:is(.article,.book,.manpage) table.tableblock thead tr th {
+    background: #2a2a2a;
+    color: #f0f0f0;
+  }
+  body:is(.article,.book,.manpage) table.tableblock tbody tr th p,
+  body:is(.article,.book,.manpage) table.tableblock tfoot tr th p {
+    color: #f0f0f0;
+  }
+  body:is(.article,.book,.manpage) table.stripes-all > * > tr,
+  body:is(.article,.book,.manpage) table.stripes-odd > * > tr:nth-of-type(odd),
+  body:is(.article,.book,.manpage) table.stripes-even > * > tr:nth-of-type(even),
+  body:is(.article,.book,.manpage) table.stripes-hover > * > tr:hover {
+    background: #2a2a2a;
+  }
+  body:is(.article,.book,.manpage) .admonitionblock > table td.content {
+    color: #d0d0d0;
+    border-left-color: #444;
+  }
+  body:is(.article,.book,.manpage) .admonitionblock > table td.icon,
+  body:is(.article,.book,.manpage) .admonitionblock > table td.icon .title {
+    color: #e06464;
+    font-weight: bold;
+  }
+
+  /* Inkscape-exported SVG figures are transparent with black strokes
+     and disappear on dark page bg.  Wrap SVGs only in a white card;
+     PNGs/JPEGs usually carry their own background so leave them be. */
+  body:is(.article,.book,.manpage) .imageblock img[src$=".svg"],
+  body:is(.article,.book,.manpage) .image img[src$=".svg"] {
+    background: #fff;
+    padding: 0.5em;
+    border-radius: 4px;
+  }
+
+  /* Asciidoctor's default stylesheet sets explicit dark-on-white colors
+     on these text blocks; without an override they stay black on the
+     dark page bg and become unreadable. */
+  body:is(.article,.book,.manpage) .quoteblock,
+  body:is(.article,.book,.manpage) .quoteblock blockquote,
+  body:is(.article,.book,.manpage) .quoteblock p,
+  body:is(.article,.book,.manpage) .quoteblock dt,
+  body:is(.article,.book,.manpage) .quoteblock .hdlist1,
+  body:is(.article,.book,.manpage) .quoteblock .attribution,
+  body:is(.article,.book,.manpage) .quoteblock .attribution cite,
+  body:is(.article,.book,.manpage) .quoteblock cite,
+  body:is(.article,.book,.manpage) .verseblock,
+  body:is(.article,.book,.manpage) .verseblock pre,
+  body:is(.article,.book,.manpage) .sidebarblock,
+  body:is(.article,.book,.manpage) .exampleblock > .content,
+  body:is(.article,.book,.manpage) dt,
+  body:is(.article,.book,.manpage) .hdlist1 {
+    color: #e0e0e0;
+  }
+  body:is(.article,.book,.manpage) .sidebarblock,
+  body:is(.article,.book,.manpage) .exampleblock > .content {
+    background: #2a2a2a;
+    border-color: #444;
+  }
+  body:is(.article,.book,.manpage) .quoteblock blockquote::before {
+    color: #888;
+  }
+}
+
+
+/* ======================================================================
+ *  Static landing pages (index.html / gcode.html)
+ *
+ *  Mirror asciidoctor's defaults so landing pages blend with the doc
+ *  pages.  Asciidoctor uses Noto Serif body / Open Sans headings /
+ *  #ba3925 heading color / #2156a5 links; we use the dark-blue accent
+ *  in line with the doc pages.
+ * ====================================================================== */
+body:not(.article):not(.book):not(.manpage) {
+  font-family: "Noto Serif", "DejaVu Serif", Georgia, serif;
+  font-weight: 400;
+  font-style: normal;
+  line-height: 1;
+  background: #fff;
+  color: rgba(0, 0, 0, 0.85);
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  /* Match the asciidoctor content cap (min 95% viewport, max 100em /
+     1600px) so the static landing pages and the doc pages line up at
+     the same width on HD screens. */
+  max-width: min(95%, 100em);
+  margin: 0 auto;
+  padding: 1em 1.5em;
+}
+/* Override index.css { body { padding-left: 50px } } */
+body:not(.article):not(.book):not(.manpage) { padding-left: 1.5em !important; }
+/* Caption acts as the page title in gcode.html; render it like
+   asciidoctor's h2. */
+body:not(.article):not(.book):not(.manpage) caption {
+  font-family: "Open Sans", "DejaVu Sans", sans-serif;
+  font-weight: 400;
+  font-style: normal;
+  font-size: 2.3125em;
+  color: #1a3a6c;
+  text-rendering: optimizeLegibility;
+  text-align: left;
+  margin: 0.5em 0;
+  caption-side: top;
+}
+body:not(.article):not(.book):not(.manpage) p,
+body:not(.article):not(.book):not(.manpage) dd {
+  font-family: inherit;
+  font-size: 1.0625em;
+  line-height: 1.6;
+  text-rendering: optimizeLegibility;
+}
+/* Link lists on index.html act as a TOC; match asciidoctor's #toc ul
+   styling (Open Sans, tight line-height). */
+body:not(.article):not(.book):not(.manpage) ul,
+body:not(.article):not(.book):not(.manpage) ol {
+  font-family: "Open Sans", "DejaVu Sans", sans-serif;
+}
+body:not(.article):not(.book):not(.manpage) li {
+  line-height: 1.3334;
+  margin-top: 0.3334em;
+}
+body:not(.article):not(.book):not(.manpage) h1,
+body:not(.article):not(.book):not(.manpage) h2,
+body:not(.article):not(.book):not(.manpage) h3,
+body:not(.article):not(.book):not(.manpage) h4,
+body:not(.article):not(.book):not(.manpage) h5,
+body:not(.article):not(.book):not(.manpage) h6 {
+  font-family: "Open Sans", "DejaVu Sans", sans-serif;
+  font-weight: 400;
+  font-style: normal;
+  color: #1a3a6c;
+  line-height: 1.2;
+  text-rendering: optimizeLegibility;
+}
+/* Sizes pulled from asciidoctor's desktop cascade. */
+body:not(.article):not(.book):not(.manpage) h2 { font-size: 2.3125em; }
+body:not(.article):not(.book):not(.manpage) h3 { font-size: 1.6875em; }
+body:not(.article):not(.book):not(.manpage) h4 { font-size: 1.4375em; }
+body:not(.article):not(.book):not(.manpage) a {
+  color: #2156a5;
+  text-decoration: none;
+}
+body:not(.article):not(.book):not(.manpage) a:hover {
+  text-decoration: underline;
+}
+body:not(.article):not(.book):not(.manpage) a:visited {
+  color: #1d4b8f;
+}
+body:not(.article):not(.book):not(.manpage) code,
+body:not(.article):not(.book):not(.manpage) pre,
+body:not(.article):not(.book):not(.manpage) tt {
+  font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace;
+}
+
+/* gcode.html table: redo to mirror asciidoctor's table look.
+   gcode.html ships hard black borders / black header inline; strip
+   the vertical rules, soften horizontals, lighten the header
+   background.  !important overrides inline style="..." on the
+   section-divider rows in the static markup. */
+body:not(.article):not(.book):not(.manpage) table {
+  border-collapse: collapse;
+  border: 1px solid #dddddf !important;
+  margin: 1em auto;
+}
+body:not(.article):not(.book):not(.manpage) td,
+body:not(.article):not(.book):not(.manpage) th {
+  border: none !important;
+  border-bottom: 1px solid #dddddf !important;
+  padding: 0.5em 0.625em !important;
+  vertical-align: top;
+}
+body:not(.article):not(.book):not(.manpage) td {
+  background: #fff;
+  color: rgba(0, 0, 0, 0.85);
+}
+body:not(.article):not(.book):not(.manpage) th {
+  background: #f7f7f8;
+  color: rgba(0, 0, 0, 0.85);
+  font-weight: bold;
+  text-align: left;
+}
+body:not(.article):not(.book):not(.manpage) tr.odd td {
+  background: #f8f8f7;
+}
+body:not(.article):not(.book):not(.manpage) tr.head td,
+body:not(.article):not(.book):not(.manpage) tr.head th {
+  background: #f7f7f8;
+  color: rgba(0, 0, 0, 0.85);
+}
+/* Section divider rows in gcode.html.  Two shapes appear:
+     Secdesc    (Motion, Canned cycles)
+     Sec                 (Distance Mode, ...)
+   Paint the row background and let the cells fall through, so the
+   tint covers any colgroup column not spanned by the th/td. */
+body:not(.article):not(.book):not(.manpage) tr:has(> th:first-child:not(:only-child)),
+body:not(.article):not(.book):not(.manpage) tr:has(> th:only-child) {
+  background: #ececef;
+}
+body:not(.article):not(.book):not(.manpage) tr:has(> th:first-child:not(:only-child)) > *,
+body:not(.article):not(.book):not(.manpage) tr:has(> th:only-child) > * {
+  background: transparent !important;
+  font-weight: bold;
+}
+
+/* ======================================================================
+ *  Static landing pages (dark, opt-in via system preference)
+ * ====================================================================== */
+@media (prefers-color-scheme: dark) {
+  body:not(.article):not(.book):not(.manpage) {
+    background: #1e1e1e;
+    color: #e0e0e0;
+  }
+  body:not(.article):not(.book):not(.manpage) h1,
+  body:not(.article):not(.book):not(.manpage) h2,
+  body:not(.article):not(.book):not(.manpage) h3,
+  body:not(.article):not(.book):not(.manpage) h4,
+  body:not(.article):not(.book):not(.manpage) h5,
+  body:not(.article):not(.book):not(.manpage) h6,
+  body:not(.article):not(.book):not(.manpage) caption {
+    color: #7fb8e8;
+  }
+  body:not(.article):not(.book):not(.manpage) a         { color: #6fa8dc; }
+  body:not(.article):not(.book):not(.manpage) a:visited { color: #b48ead; }
+
+  body:not(.article):not(.book):not(.manpage) table {
+    border-color: #444 !important;
+  }
+  body:not(.article):not(.book):not(.manpage) td,
+  body:not(.article):not(.book):not(.manpage) th {
+    border-bottom-color: #444 !important;
+  }
+  body:not(.article):not(.book):not(.manpage) td {
+    background: #2a2a2a;
+    color: #e0e0e0;
+  }
+  body:not(.article):not(.book):not(.manpage) th {
+    background: #1a1a1a;
+    color: #f0f0f0;
+  }
+  body:not(.article):not(.book):not(.manpage) tr.odd td {
+    background: #333;
+  }
+  body:not(.article):not(.book):not(.manpage) tr.head td,
+  body:not(.article):not(.book):not(.manpage) tr.head th {
+    background: #1a1a1a;
+    color: #f0f0f0;
+  }
+  body:not(.article):not(.book):not(.manpage) tr:has(> th:first-child:not(:only-child)),
+  body:not(.article):not(.book):not(.manpage) tr:has(> th:only-child) {
+    background: #161616;
+  }
+  body:not(.article):not(.book):not(.manpage) tr:has(> th:first-child:not(:only-child)) > *,
+  body:not(.article):not(.book):not(.manpage) tr:has(> th:only-child) > * {
+    background: transparent !important;
+    color: #f0f0f0;
+  }
+}
diff --git a/docs/src/pdf-theme.yml b/docs/src/pdf-theme.yml
new file mode 100644
index 00000000000..7af6feff8d0
--- /dev/null
+++ b/docs/src/pdf-theme.yml
@@ -0,0 +1,130 @@
+# asciidoctor-pdf theme for LinuxCNC docs.
+# Approximates the look and feel of the dblatex output (emc2.sty).
+# Extends the asciidoctor-pdf "default" theme; only set overrides here.
+
+extends: default
+
+font:
+  catalog:
+    merge: true
+    DejaVu Sans Mono:
+      normal: DejaVuSansMono.ttf
+      bold: DejaVuSansMono-Bold.ttf
+      italic: DejaVuSansMono-Oblique.ttf
+      bold_italic: DejaVuSansMono-BoldOblique.ttf
+    Noto Serif CJK SC:
+      normal: NotoSerifCJKsc-Regular.ttf
+      bold: NotoSerifCJKsc-Bold.ttf
+      italic: NotoSerifCJKsc-Regular.ttf
+      bold_italic: NotoSerifCJKsc-Bold.ttf
+  fallbacks:
+    - Noto Serif CJK SC
+
+page:
+  size: A4
+  margin: [0.85in, 0.67in, 0.55in, 0.67in]
+
+base:
+  font_family: Noto Serif
+  font_size: 10
+  line_height_length: 12
+  line_height: $base_line_height_length / 10
+  font_color: 000000
+  text_align: justify
+
+heading:
+  font_family: $base_font_family
+  font_color: 000000
+  font_style: bold
+  text_align: left
+  line_height: 1.2
+  margin_top: 12
+  margin_bottom: 6
+  h1_font_size: 22
+  h2_font_size: 18
+  h3_font_size: 14
+  h4_font_size: 12
+  h5_font_size: 11
+  h6_font_size: 10
+
+title_page:
+  align: center
+  title:
+    top: 55%
+    font_size: 28
+    font_color: 000000
+    font_style: bold
+  subtitle:
+    font_size: 18
+    font_color: 000000
+  authors:
+    margin_top: 12
+    font_size: 12
+    font_color: 000000
+  revision:
+    margin_top: 12
+    font_size: 10
+    font_color: 000000
+
+header:
+  height: 0.6in
+  font_size: 9
+  font_color: 000000
+  border_width: 0.5
+  border_color: 000000
+  vertical_align: middle
+  columns: <40% =20% >40%
+  recto: &header_content
+    left:
+      content: '{document-title}'
+    center:
+      content: '{chapter-title}'
+    right:
+      content: '{page-number} / {page-count}'
+  verso: *header_content
+
+footer:
+  height: 0.4in
+  border_width: 0.5
+  border_color: 000000
+  recto: &footer_content
+    left:
+      content: ''
+    center:
+      content: ''
+    right:
+      content: ''
+  verso: *footer_content
+
+toc:
+  indent: 18
+  line_height: 1.4
+
+codespan:
+  font_family: DejaVu Sans Mono
+  font_color: B12146
+
+code:
+  font_family: DejaVu Sans Mono
+  font_size: 9
+  background_color: F5F5F5
+  border_color: DDDDDD
+  border_width: 0.5
+  border_radius: 2
+  padding: [6, 6, 6, 6]
+
+kbd:
+  font_family: DejaVu Sans Mono
+
+button:
+  font_family: DejaVu Sans Mono
+
+link:
+  font_color: 0000FF
+
+table:
+  head:
+    background_color: E8E8E8
+    border_bottom_width: 1
+  border_color: CCCCCC
+  cell_padding: 4

From 96863d746d879b5175931a68e92f9376bfc1ccf5 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:23:39 +0800
Subject: [PATCH 04/10] docs: portable CJK font (CFF -> TTF) converter

Builds a TrueType (glyf-based) copy of the Simplified Chinese cut of
Noto Serif CJK from the system .ttc collection.  prawn 2.4 (used by
asciidoctor-pdf) corrupts the PDF when asked to embed CFF outlines, so
we convert the curves with cu2qu (python3-fonttools) first.

Subsets to the glyph set actually used by the docs to keep the font
small.  Scans both docs/src and the po catalogues, so the subset
holds the translated text too.  Without this, a fresh build's subset
would come up empty and the converter would fall back to the full
~65k-glyph face (~200s vs ~1.5s).
---
 docs/src/otf2ttf.py | 112 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 docs/src/otf2ttf.py

diff --git a/docs/src/otf2ttf.py b/docs/src/otf2ttf.py
new file mode 100644
index 00000000000..ca50214458d
--- /dev/null
+++ b/docs/src/otf2ttf.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# Build a small TrueType (glyf-based) subset of a CFF-based OTF/TTC for
+# prawn-pdf (used by asciidoctor-pdf) to embed.  Debian ships
+# Noto Serif CJK only as a CFF/OTF TrueType Collection and prawn 2.4
+# (the version on bookworm) corrupts the PDF when asked to embed CFF
+# outlines directly, so we convert the curves with cu2qu first.
+#
+# Subsetting before conversion keeps the build under a second: a full
+# Noto Serif CJK face is ~65 k glyphs (~45 s convert); the docs use a
+# few hundred CJK characters at most.
+#
+# Usage:
+#   otf2ttf.py   [--ttc-index N] [--text-from DIR]
+#
+# Built for the docs build only.  Not a general font tool.
+
+import argparse, os, re, sys, time
+from fontTools.ttLib import TTCollection, TTFont, newTable
+from fontTools.pens.ttGlyphPen import TTGlyphPen
+from fontTools.pens.cu2quPen import Cu2QuPen
+from fontTools.subset import Subsetter, Options
+
+# Characters we want available in the fallback font.  Defaults to BMP CJK
+# unified ideographs + halfwidth / fullwidth forms.  ASCII is excluded
+# since the base font already covers it.
+CJK_RE = re.compile(r'[　-鿿＀-￯]')
+
+
+def scan_cjk(root):
+    seen = set()
+    for dirpath, _, files in os.walk(root):
+        for f in files:
+            if not (f.endswith('.adoc') or f.endswith('.po')):
+                continue
+            try:
+                t = open(os.path.join(dirpath, f), encoding='utf-8', errors='ignore').read()
+            except OSError:
+                continue
+            seen.update(CJK_RE.findall(t))
+    return seen
+
+
+def cff_to_ttf(font):
+    glyph_set = font.getGlyphSet()
+    glyf = newTable('glyf')
+    glyf.glyphs = {}
+    glyf.glyphOrder = font.getGlyphOrder()
+    for name in font.getGlyphOrder():
+        pen = TTGlyphPen(None)
+        try:
+            glyph_set[name].draw(Cu2QuPen(pen, max_err=1.0, reverse_direction=True))
+        except Exception:
+            pass
+        glyf.glyphs[name] = pen.glyph()
+    font['glyf'] = glyf
+    for t in ('CFF ', 'CFF2', 'VORG'):
+        if t in font:
+            del font[t]
+    font['head'].indexToLocFormat = 1
+    font['loca'] = newTable('loca')
+    font.sfntVersion = '\x00\x01\x00\x00'
+
+
+def convert(src, dst, ttc_index=None, text=None):
+    t0 = time.time()
+    if ttc_index is not None:
+        font = TTCollection(src).fonts[ttc_index]
+    else:
+        font = TTFont(src)
+
+    # `is not None`, not `if text:`: an empty scan result must still subset
+    # (to notdef) rather than convert the full ~65k-glyph face (~200s).
+    if text is not None:
+        opts = Options()
+        opts.layout_features = ['*']
+        opts.notdef_outline = True
+        opts.recommended_glyphs = True
+        opts.name_IDs = ['*']
+        opts.name_legacy = True
+        opts.name_languages = ['*']
+        sub = Subsetter(options=opts)
+        sub.populate(text=text)
+        sub.subset(font)
+
+    if 'CFF ' in font or 'CFF2' in font:
+        cff_to_ttf(font)
+
+    font.save(dst)
+    print(f'{dst}: {time.time()-t0:.1f}s ({font["maxp"].numGlyphs} glyphs)')
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument('input')
+    p.add_argument('output')
+    p.add_argument('--ttc-index', type=int, default=None)
+    p.add_argument('--text-from', action='append', default=[], metavar='DIR',
+                   help='directory scanned for adoc/po sources; subset output '
+                        'to characters found there.  Repeatable.')
+    a = p.parse_args()
+    if a.text_from:
+        seen = set()
+        for d in a.text_from:
+            seen.update(scan_cjk(d))
+        text = ''.join(sorted(seen))
+    else:
+        text = None
+    convert(a.input, a.output, a.ttc_index, text)
+
+
+if __name__ == '__main__':
+    main()

From 91d3f4ea773bb262e1796ef4b19d0c0a6c2234f8 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:23:48 +0800
Subject: [PATCH 05/10] build: probe optional docs deps; graceful disable,
 hard-fail explicit

- src/configure.ac: probe ruby-rouge, python3-fonttools, and
  NotoSerifCJK fontconfig path portably.  When BUILD_DOCS_HTML or
  BUILD_DOCS_PDF was requested without --enable-X explicit and a dep
  is missing: warn and disable that target.  When the user explicitly
  passed --enable-build-documentation=pdf with deps missing: fail
  hard (don't silently produce no PDFs).  Same hard-fail for any
  explicit PDF request, not only =pdf.

- debian/configure: regenerate Build-Depends-Indep with asciidoctor
  toolchain (ruby-asciidoctor, ruby-asciidoctor-pdf, ruby-rouge,
  python3-fonttools, fonts-dejavu, fonts-noto-cjk) replacing the
  asciidoc-py / dblatex / xsltproc stack.

- debian/control.top.in: expand @DOC_DEPENDS@ accordingly.
---
 debian/configure      |  14 +--
 debian/control.top.in |   6 +-
 src/configure.ac      | 242 +++++++++++++++++++++++-------------------
 3 files changed, 137 insertions(+), 125 deletions(-)

diff --git a/debian/configure b/debian/configure
index b157af7f09e..7ee052f9674 100755
--- a/debian/configure
+++ b/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
diff --git a/debian/control.top.in b/debian/control.top.in
index 1246fcdabfa..79f8d8fc4c9 100644
--- a/debian/control.top.in
+++ b/debian/control.top.in
@@ -12,12 +12,10 @@ Build-Depends:
     @KERNEL_HEADERS@,
     @MODUTILS_DEPENDS@,
     @EXTRA_BUILD@,
-    docbook-xsl ,
-    asciidoc,
-    ghostscript ,
     groff-base ,
     imagemagick ,
-    asciidoc-dblatex ,
+    asciidoctor ,
+    libunicode-linebreak-perl ,
     autoconf,
     automake,
     bwidget (>= 1.7),
diff --git a/src/configure.ac b/src/configure.ac
index f294f68b895..3d00a98eb54 100644
--- a/src/configure.ac
+++ b/src/configure.ac
@@ -1061,130 +1061,167 @@ AC_ARG_ENABLE(build-documentation,
         AC_MSG_RESULT([no])
     ])
 
-# Programs required for building all documentation
+# Programs required for building documentation.  Missing PDF-only
+# tools or an invalid CJK font are a hard error whenever PDF was
+# requested (BUILD_DOCS_PDF=yes -- i.e. anything except
+# --enable-build-documentation=html).  =html itself warn-and-disables
+# only the missing PDF tools; users who want PDF best-effort can pass
+# =html and rebuild after installing the missing tools.
 if ( test "$BUILD_DOCS" = "yes" ) ; then
-    AC_PATH_PROG(ASCIIDOC,asciidoc,"none")
-    if ( test "none" = "$ASCIIDOC" ) ; then
-	AC_MSG_WARN([no AsciiDoc, documentation cannot be built])
-        BUILD_DOCS=no
-    fi
-
-    AC_PATH_PROG(A2X,a2x,"none")
-    if ( test "none" = "$A2X" ) ; then
-	AC_MSG_WARN([no a2x, documentation cannot be built])
-        BUILD_DOCS=no
-    fi
-
-    AC_MSG_CHECKING([whether to specify latex.encoding])
-    temp_asciidoc=`mktemp --suffix=.txt`
-    cat > $temp_asciidoc < /dev/null 2>&1;
-    then
-        A2X_LATEX_ENCODING="-P latex.encoding=utf8"
-        AC_MSG_RESULT(yes)
-    else
-        A2X_LATEX_ENCODING=""
-        AC_MSG_RESULT(no)
-    fi
-    AC_SUBST(A2X_LATEX_ENCODING)
-    rm -f $temp_asciidoc ${temp_asciidoc%.txt}.pdf
-
-    AC_PATH_PROG(DBLATEX,dblatex,"none")
-    if ( test "none" = "$DBLATEX" ) ; then
-	AC_MSG_WARN([no dblatex, documentation cannot be built])
+    AC_PATH_PROG(ASCIIDOCTOR,asciidoctor,"none")
+    if ( test "none" = "$ASCIIDOCTOR" ) ; then
+        AC_MSG_WARN([no asciidoctor, documentation cannot be built
+install with "sudo apt-get install asciidoctor"])
         BUILD_DOCS=no
+        BUILD_DOCS_PDF=no
+        BUILD_DOCS_HTML=no
     fi
 
     if ( test "$BUILD_DOCS" = "yes" ) ; then
-        AC_MSG_CHECKING([dblatex version])
-        set -- `dblatex --version`; DBLATEX_VER=$3
-        set -- `echo $DBLATEX_VER | sed 's/[[.-]]/ /g'`
-        micro=`echo $3 | sed 's/\([[0-9]]*\).*/\1/g'`
-
-        if test $1 -eq 0 -a \( $2 -lt 2 -o \( $2 -eq 2 -a ${micro:-0} -lt 12 \) \); then
-            AC_MSG_WARN([dblatex version $DBLATEX_VER less than 0.2.12.
-Documentation cannot be built.])
-            BUILD_DOCS=no
-        else
-            AC_MSG_RESULT([$DBLATEX_VER])
-        fi
-    fi
-
-    if ( test "$BUILD_DOCS" = "yes" ) ; then
-        AC_PATH_PROG(SOURCE_HIGHLIGHT,source-highlight,"none")
-        if ( test "none" = "$SOURCE_HIGHLIGHT" ) ; then
-            AC_MSG_WARN([no source-highlight, documentation cannot be built])
+        AC_PATH_PROG(GS,gs,"none")
+        if ( test "none" = "$GS" ) ; then
+            AC_MSG_WARN([no gs, documentation cannot be built
+install with "sudo apt-get install ghostscript"])
             BUILD_DOCS=no
+            BUILD_DOCS_PDF=no
+            BUILD_DOCS_HTML=no
         fi
     fi
 
     if ( test "$BUILD_DOCS" = "yes" ) ; then
-        AC_PATH_PROG(CONVERT,convert,"none")
-        if ( test "none" = "$CONVERT" ) ; then
-            AC_MSG_WARN([no convert, documentation cannot be built])
+        AC_PATH_PROG(RSVG_CONVERT,rsvg-convert,"none")
+        if ( test "none" = "$RSVG_CONVERT" ) ; then
+            AC_MSG_WARN([no rsvg-convert, documentation cannot be built
+install with "sudo apt-get install librsvg2-bin"])
             BUILD_DOCS=no
+            BUILD_DOCS_PDF=no
+            BUILD_DOCS_HTML=no
         fi
     fi
 
+    # Rouge is required by the custom rouge_hal / rouge_ngc / rouge_ini
+    # extensions loaded by every asciidoctor invocation; without it the
+    # build dies with "cannot load such file -- rouge" deep in the make
+    # log (reported by bertho on Fedora 43 where ruby-rouge wasn't a
+    # transitive dep of asciidoctor).
     if ( test "$BUILD_DOCS" = "yes" ) ; then
-        AC_PATH_PROG(GS,gs,"none")
-        if ( test "none" = "$GS" ) ; then
-            AC_MSG_WARN([no gs, documentation cannot be built])
+        AC_MSG_CHECKING([for ruby rouge gem])
+        if ruby -e 'require "rouge"' 2>/dev/null ; then
+            AC_MSG_RESULT([yes])
+        else
+            AC_MSG_RESULT([no])
+            AC_MSG_WARN([no ruby rouge, documentation cannot be built
+install with "sudo apt-get install ruby-rouge" on Debian / Ubuntu,
+"sudo dnf install rubygem-rouge" on Fedora, or "gem install rouge"])
             BUILD_DOCS=no
+            BUILD_DOCS_PDF=no
+            BUILD_DOCS_HTML=no
         fi
     fi
 fi
 
 # Programs required only for building the PDF documentation
 if ( test "$BUILD_DOCS_PDF" = "yes" ) ; then
-    AC_PATH_PROG(PDFLATEX,pdflatex,"none")
-    if ( test "none" = "$PDFLATEX" ) ; then
-	AC_MSG_WARN([no pdflatex, PDF documentation cannot be built])
-        BUILD_DOCS=no
+    AC_PATH_PROG(ASCIIDOCTOR_PDF,asciidoctor-pdf,"none")
+    if ( test "none" = "$ASCIIDOCTOR_PDF" ) ; then
+        AC_MSG_ERROR([no asciidoctor-pdf, PDF documentation cannot be built
+install with "sudo apt-get install asciidoctor-pdf" (Debian sid/trixie)
+or "sudo apt-get install ruby-asciidoctor-pdf" (Debian bookworm)])
     fi
-fi
 
-# Programs required only for building the HTML documentation
-if ( test "$BUILD_DOCS_HTML" = "yes" ) ; then
-    AC_PATH_PROG(XSLTPROC,xsltproc,"none")
-    if ( test "none" = "$XSLTPROC" ) ; then
-	AC_MSG_WARN([no xsltproc, HTML documentation cannot be built])
-        BUILD_DOCS=no
+    # fontTools (python3-fonttools) is used by otf2ttf.py to convert the
+    # CFF/OTF NotoSerifCJK .ttc into a TrueType the prawn PDF engine can
+    # embed.
+    if ( test "$BUILD_DOCS_PDF" = "yes" ) ; then
+        AC_MSG_CHECKING([for python3 fontTools module])
+        if python3 -c 'import fontTools' 2>/dev/null ; then
+            AC_MSG_RESULT([yes])
+        else
+            AC_MSG_RESULT([no])
+            AC_MSG_WARN([no python3 fontTools, PDF documentation cannot be built
+install with "sudo apt-get install python3-fonttools"])
+            BUILD_DOCS_PDF=no
+        fi
     fi
 
-    AC_PATH_PROG(DVIPNG,dvipng,"none")
-    if ( test "none" = "$DVIPNG" ) ; then
-	AC_MSG_WARN([no dvipng, HTML documentation cannot be built])
-        BUILD_DOCS=no
+    if ( test "$BUILD_DOCS_PDF" = "yes" ) ; then
+    # NotoSerifCJK is the fallback font that asciidoctor-pdf reaches
+    # for when a glyph (zh_CN, Japanese, Korean) is missing from the
+    # base text font.  We need the .ttc TrueType Collection, because
+    # otf2ttf.py picks index 2 (SC) out of it.  Probe via fontconfig
+    # first, then load through python+fontTools to validate, because
+    # some distros ship a file named .ttc that is not actually a
+    # TrueType Collection (otf2ttf would die mid-build on it).  Probe
+    # failure warn-and-disables PDF on the default =Y path so other
+    # docs still build; explicit =pdf is treated as a hard error.
+    cjk_disable_pdf_reason=""
+    AC_MSG_CHECKING([for NotoSerifCJK Regular .ttc])
+    NOTOCJK_REGULAR_TTC="`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Regular' 2>/dev/null`"
+    case "$NOTOCJK_REGULAR_TTC" in
+        *.ttc) test -r "$NOTOCJK_REGULAR_TTC" || NOTOCJK_REGULAR_TTC="" ;;
+        *)     NOTOCJK_REGULAR_TTC="" ;;
+    esac
+    if test -z "$NOTOCJK_REGULAR_TTC" ; then
+        AC_MSG_RESULT([no])
+        cjk_disable_pdf_reason="no NotoSerifCJK Regular TrueType Collection found via fc-match"
+    else
+        AC_MSG_RESULT([$NOTOCJK_REGULAR_TTC])
     fi
 
-    AC_MSG_CHECKING([for HTML support in groff])
-    if ! groff -Thtml < /dev/null > /dev/null 2>&1 ; then
-        AC_MSG_WARN([no groff -Thtml, HTML documentation cannot be built])
-        BUILD_DOCS=no
-    else
-        AC_MSG_RESULT(yes)
+    if test -z "$cjk_disable_pdf_reason" ; then
+        AC_MSG_CHECKING([for NotoSerifCJK Bold .ttc])
+        NOTOCJK_BOLD_TTC="`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Bold' 2>/dev/null`"
+        case "$NOTOCJK_BOLD_TTC" in
+            *.ttc) test -r "$NOTOCJK_BOLD_TTC" || NOTOCJK_BOLD_TTC="" ;;
+            *)     NOTOCJK_BOLD_TTC="" ;;
+        esac
+        if test -z "$NOTOCJK_BOLD_TTC" ; then
+            AC_MSG_RESULT([no])
+            cjk_disable_pdf_reason="no NotoSerifCJK Bold TrueType Collection found via fc-match"
+        else
+            AC_MSG_RESULT([$NOTOCJK_BOLD_TTC])
+        fi
+    fi
+
+    if test -z "$cjk_disable_pdf_reason" ; then
+        AC_MSG_CHECKING([that NotoSerifCJK .ttc loads as a TrueType Collection])
+        if python3 -c 'import sys; from fontTools.ttLib import TTCollection; TTCollection(sys.argv[[1]]).fonts[[2]]; TTCollection(sys.argv[[2]]).fonts[[2]]' "$NOTOCJK_REGULAR_TTC" "$NOTOCJK_BOLD_TTC" 2>/dev/null ; then
+            AC_MSG_RESULT([yes])
+        else
+            AC_MSG_RESULT([no])
+            cjk_disable_pdf_reason="NotoSerifCJK file at $NOTOCJK_REGULAR_TTC is not a valid TrueType Collection (index 2 unavailable)"
+        fi
+    fi
+
+    if test -n "$cjk_disable_pdf_reason" ; then
+        AC_MSG_ERROR([$cjk_disable_pdf_reason, PDF documentation cannot be built
+install with "sudo apt-get install fonts-noto-cjk" on Debian / Ubuntu,
+"sudo pacman -S noto-fonts-cjk" on Arch, or
+"sudo dnf install google-noto-sans-cjk-fonts google-noto-serif-cjk-fonts" on Fedora.
+fontconfig also picks up user installs under ~/.fonts; run "fc-cache -f" after copying the .ttc there.
+For a fully custom path, set the var directly:
+   ./configure NOTOCJK_REGULAR_TTC=/path/to/NotoSerifCJK-Regular.ttc \
+              NOTOCJK_BOLD_TTC=/path/to/NotoSerifCJK-Bold.ttc])
     fi
+    AC_SUBST(NOTOCJK_REGULAR_TTC)
+    AC_SUBST(NOTOCJK_BOLD_TTC)
+    fi
+fi
 
+# Programs required only for building the HTML documentation
+if ( test "$BUILD_DOCS_HTML" = "yes" ) ; then
     AC_PATH_PROG(CHECKLINK,checklink,"none")
     if ( test "none" = "$CHECKLINK" ) ; then
-	AC_MSG_WARN([no checklink, HTML documentation cannot be built
+        AC_MSG_WARN([no checklink, HTML documentation cannot be built
 install with "sudo apt-get install w3c-linkchecker"])
-        BUILD_DOCS=no
+        BUILD_DOCS_HTML=no
     fi
 fi
 
 AC_ARG_ENABLE(build-documentation-translation,
     AS_HELP_STRING(
-        [--disable-build-documentation-translation],
-        [Disable building documentation in languages other than English.]
+        [--enable-build-documentation-translation],
+        [Also build translated documentation (po4a, ~5 min extra wall time).  Default off.]
     ),
     [
     case "$enableval" in
@@ -1200,37 +1237,26 @@ AC_ARG_ENABLE(build-documentation-translation,
         BUILD_DOCS_TRANSLATED_EXPLICIT=not_set
     ])
 
-if ( test "$BUILD_DOCS" = "yes" && test "$BUILD_DOCS_TRANSLATED_EXPLICIT" != "no") ; then
+BUILD_DOCS_TRANSLATED=no
+if ( test "$BUILD_DOCS" = "yes" && test "$BUILD_DOCS_TRANSLATED_EXPLICIT" = "yes") ; then
     AC_PATH_PROG(PO4A, po4a, "none")
-    BUILD_DOCS_TRANSLATED=yes
     if test $PO4A = "none"
     then
-        if test "$BUILD_DOCS_TRANSLATED_EXPLICIT" = "not_set"
-        then
-            AC_MSG_WARN([po4a not found, not building translated docs])
-        else
-            AC_MSG_ERROR([po4a not found, not building translated docs])
-        fi
-        BUILD_DOCS_TRANSLATED=no
+        AC_MSG_ERROR([po4a not found, cannot build translated docs])
     else
-        # Version 0.35 support asciidoc without tables
-        # Version 0.56 support the tablecells asciidoc option
-        # Version 0.62 correctly write UTF-8 into translated adocs
-        # Version 0.65 support grouping several doc files into different POTs
-        # Version 0.66 handle empty table cells in asciidoc
-        # Version 0.67 handle enforced linbreaks
+        # Version 0.67 handles enforced linebreaks correctly
         V=$(po4a --version| awk '/po4a version/ {print $3}')
         if dpkg --compare-versions 0.67 gt "$V"; then
-            if test "$BUILD_DOCS_TRANSLATED_EXPLICIT" = "not_set"
-            then
-                AC_MSG_WARN([po4a version too old, need version 0.67 or newer, not building translated docs])
-            else
-                AC_MSG_ERROR([po4a version too old, need version 0.67 or newer, not building translated docs])
-            fi
-	    BUILD_DOCS_TRANSLATED=no
+            AC_MSG_ERROR([po4a version too old, need version 0.67 or newer to build translated docs])
         fi
+        BUILD_DOCS_TRANSLATED=yes
     fi
 fi
+if test "$BUILD_DOCS" = "yes" && test "$BUILD_DOCS_TRANSLATED" = "no" ; then
+    DOC_LANGS=$(sed -e's/#.*//' "$srcdir/../docs/po4a.cfg" 2>/dev/null | grep '^\[po4a_langs\]' | cut -d" " -f2-)
+    DOC_LANGS=$(echo $DOC_LANGS | tr ' ' '/')
+    AC_MSG_NOTICE([documentation will be built for English only; pass --enable-build-documentation-translation to also build ${DOC_LANGS:-translations}])
+fi
 AC_SUBST(BUILD_DOCS)
 AC_SUBST(BUILD_DOCS_PDF)
 AC_SUBST(BUILD_DOCS_HTML)

From 4573422f2c5501c0a98a1ecfe43ca59e23fee50f Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:24:16 +0800
Subject: [PATCH 06/10] docs: migrate doc build rules to asciidoctor toolchain

Replace the legacy asciidoc-py + dblatex + xsltproc pipeline with
asciidoctor + asciidoctor-pdf + Rouge.  HTML built via asciidoctor,
PDFs via asciidoctor-pdf, manpages via asciidoctor manpage doctype
(troff) plus html5 backend.  Manual_Pages.pdf assembled from a
generated master document including every PDF_MAN_ORDER entry as a
chapter (leveloffset=+1, hard page break per entry).

- docs/src/Submakefile: rewrite around asciidoctor + Rouge.  Per-
  language target lists derived from po4a.cfg.  Idempotent build:
  stamp-gated copy_asciidoc_files / gen_complist / checkref, content-
  stable mtimes via touch on .pot regen, .SECONDARY for translated
  Master_*.pdf so leaf rules don't churn.  CJK font discovery via
  fontconfig (NotoSerifCJK .ttc) + DejaVu Sans Mono symlinks under
  objects/.fonts/.  Rouge theme rendered from the Rouge API at build
  time, single-mode fallback for older Rouge without light!/dark!.
  Manpage HTML resolves troff .so aliases via symlink, falls back to
  objects/man for halcompile-generated component adocs.

- debian/rules.in: per-lang translated PDF cleanup loop derived from
  po4a.cfg; comment about gcode.html lang tree.

- src/Makefile.inc.in: drop legacy asciidoc-py / dblatex variables.

Drop legacy infrastructure:
  asciidoc-dont-replace-arrows.conf, attribute-colon.conf,
  docbook.conf, docbook-image.conf, emc2.sty, html-images.xslt,
  html-latex-images, image-wildcard, links.xslt, links_db_gen.py,
  xhtml11.conf + xhtml11-{head-foot,latexmath,links}.conf,
  source-highlight/ (replaced by Rouge), scripts/inkscape rsvg shim
  (asciidoctor handles SVG natively).
---
 debian/rules.in                               |  14 +-
 docs/src/Submakefile                          | 831 +++++++++---------
 docs/src/asciidoc-dont-replace-arrows.conf    |  16 -
 docs/src/attribute-colon.conf                 |   2 -
 docs/src/docbook-image.conf                   |  24 -
 docs/src/docbook.conf                         |   2 -
 docs/src/emc2.sty                             |  25 -
 docs/src/html-images.xslt                     |  23 -
 docs/src/html-latex-images                    |  91 --
 docs/src/image-wildcard                       |  55 --
 docs/src/links.xslt                           |  44 -
 docs/src/links_db_gen.py                      |  18 -
 docs/src/source-highlight/README              |  76 --
 docs/src/source-highlight/Submakefile         |  63 --
 .../emc-langs-source-highlight.conf           | 118 ---
 docs/src/source-highlight/hal-demo.adoc       |  47 -
 docs/src/source-highlight/hal-test.hal        |  23 -
 docs/src/source-highlight/hal.lang            |  28 -
 docs/src/source-highlight/ini-demo.adoc       | 234 -----
 docs/src/source-highlight/ini-test.ini        | 195 ----
 docs/src/source-highlight/ini.lang            |  15 -
 docs/src/source-highlight/ngc-demo.adoc       | 118 ---
 docs/src/source-highlight/ngc-test.ngc        |  94 --
 docs/src/source-highlight/ngc.lang            |  99 ---
 docs/src/xhtml11-head-foot.conf               | 156 ----
 docs/src/xhtml11-latexmath.conf               |  14 -
 docs/src/xhtml11-links.conf                   |   6 -
 docs/src/xhtml11.conf                         |  27 -
 scripts/inkscape                              |  96 --
 src/Makefile.inc.in                           |   3 +-
 30 files changed, 428 insertions(+), 2129 deletions(-)
 delete mode 100644 docs/src/asciidoc-dont-replace-arrows.conf
 delete mode 100644 docs/src/attribute-colon.conf
 delete mode 100644 docs/src/docbook-image.conf
 delete mode 100644 docs/src/docbook.conf
 delete mode 100644 docs/src/emc2.sty
 delete mode 100644 docs/src/html-images.xslt
 delete mode 100755 docs/src/html-latex-images
 delete mode 100755 docs/src/image-wildcard
 delete mode 100644 docs/src/links.xslt
 delete mode 100755 docs/src/links_db_gen.py
 delete mode 100644 docs/src/source-highlight/README
 delete mode 100644 docs/src/source-highlight/Submakefile
 delete mode 100644 docs/src/source-highlight/emc-langs-source-highlight.conf
 delete mode 100644 docs/src/source-highlight/hal-demo.adoc
 delete mode 100644 docs/src/source-highlight/hal-test.hal
 delete mode 100644 docs/src/source-highlight/hal.lang
 delete mode 100644 docs/src/source-highlight/ini-demo.adoc
 delete mode 100644 docs/src/source-highlight/ini-test.ini
 delete mode 100644 docs/src/source-highlight/ini.lang
 delete mode 100644 docs/src/source-highlight/ngc-demo.adoc
 delete mode 100644 docs/src/source-highlight/ngc-test.ngc
 delete mode 100644 docs/src/source-highlight/ngc.lang
 delete mode 100644 docs/src/xhtml11-head-foot.conf
 delete mode 100644 docs/src/xhtml11-latexmath.conf
 delete mode 100644 docs/src/xhtml11-links.conf
 delete mode 100644 docs/src/xhtml11.conf
 delete mode 100755 scripts/inkscape

diff --git a/debian/rules.in b/debian/rules.in
index 9c0d295a12c..50b52e8ff63 100644
--- a/debian/rules.in
+++ b/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
diff --git a/docs/src/Submakefile b/docs/src/Submakefile
index b62c9d5546f..59f6f65e379 100644
--- a/docs/src/Submakefile
+++ b/docs/src/Submakefile
@@ -1,4 +1,4 @@
-.PHONY: docs docclean checkref checkref_en checkref_ar checkref_de checkref_es checkref_fr checkref_nb checkref_ru checkref_sv checkref_ta checkref_tr checkref_uk checkref_zh_CN
+.PHONY: docs docclean checkref
 .PHONY: pdfdocs htmldocs install-doc install-doc-pdf install-doc-html
 
 SHELL=/bin/bash
@@ -6,6 +6,13 @@ SHELL=/bin/bash
 # To make linuxcnc-checklink widely available
 export PATH:=$(BASEPWD)/../scripts:$(PATH)
 
+# Ruby (asciidoctor / asciidoctor-pdf) reads source files in the locale's
+# default external encoding.  Containerised builds often inherit POSIX/C,
+# which makes Ruby treat every UTF-8 byte > 0x7f as an invalid sequence
+# and abort on the first non-ASCII character.  Force UTF-8.
+export LANG := C.UTF-8
+export LC_ALL := C.UTF-8
+
 # Optional helper to convert to uppercase for variable names like $(DOC_TARGETS_HTML_SV)
 # GNU make doesn’t have built-in uppercase, so define one:
 uc = $(shell echo $(1) | tr '[:lower:]' '[:upper:]')
@@ -25,8 +32,7 @@ SRCDIR=../src
 DOC_DIR=../docs
 DOC_SRCDIR=../docs/src
 
-LOC_HL_DIR=../docs/src/source-highlight
-LOC_LANG_MAP=$(LOC_HL_DIR)/local/lang.map
+ASCIIDOCTOR_DEFAULT_CSS := $(shell ruby -e 'require "asciidoctor"; print Asciidoctor::DATA_DIR' 2>/dev/null)/stylesheets/asciidoctor-default.css
 
 # The following line determines for the Makefile what languages should be addressed.
 # Edit the file po4a.cfg in this source tree to adjust.
@@ -235,13 +241,38 @@ else
   PO4A_VERBOSE =
 endif
 
-$(DOC_DIR)/po/documentation.pot: $(addprefix $(DOC_SRCDIR)/, $(DOC_SRCS_EN))
+# components_gen.adoc is referenced as a translation master in po4a.cfg
+# (so each language has its own translated copy in /hal/) and is
+# auto-generated from the English manpages by gen_complist.py.  It must
+# exist before po4a is invoked, otherwise po4a aborts with "master file
+# does not exist".  gen_complist.py reads the manpage source list from
+# $(DOC_DIR)/man/, so changes to that set must invalidate the file --
+# hence $(MAN_SRCS) as a real prereq (the script is content-stable via
+# write_if_changed, so re-running over the same set is a no-op for
+# mtime, which keeps downstream po4a from re-firing every build).
+$(DOC_SRCDIR)/hal/components_gen.adoc: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc $(MAN_SRCS) | manpages
+	python3 $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc
+
+$(DOC_DIR)/po/documentation.pot: $(addprefix $(DOC_SRCDIR)/, $(DOC_SRCS_EN)) $(DOC_SRCDIR)/hal/components_gen.adoc
 	cd $(DOC_DIR) && ${TIME_CMD} po4a $(PO4A_VERBOSE) --msgmerge-opt='-v' --no-translations po4a.cfg
+	@touch $@
 pofiles: $(DOC_DIR)/po/documentation.pot
 
 ifeq ($(BUILD_DOCS_TRANSLATED),yes)
-translateddocs: manpages $(DOC_DIR)/po/documentation.pot
+# Stamp-file gate: without it `translateddocs` is a phony-style target with
+# no file output, so make re-runs po4a every build.  po4a rewrites the
+# per-language .adoc files, bumping their mtime past the downstream PDFs
+# and triggering a full translated-PDF rebuild on every invocation.
+#
+# Depend on the committed .po files and components_gen.adoc (a po4a master),
+# NOT documentation.pot: regenerating the pot runs po4a in msgmerge mode,
+# rewriting every docs/po/*.po with a fresh POT-Creation-Date on each build
+# (dirty tree + mtime cascade).  Building needs only `po4a --no-update`;
+# pot/po extraction stays on the explicit `pofiles` target.
+$(DOC_DIR)/.translateddocs-stamp: $(DOC_SRCDIR)/hal/components_gen.adoc $(wildcard $(DOC_DIR)/po/*.po) | manpages
 	cd $(DOC_DIR) && ${TIME_CMD} po4a $(PO4A_VERBOSE) --msgmerge-opt='-v' --no-update po4a.cfg
+	@touch $@
+translateddocs: $(DOC_DIR)/.translateddocs-stamp
 else
 translateddocs:
 endif
@@ -253,16 +284,28 @@ postatus::
 	    echo -n "$$p ";  msgfmt --statistics -o /dev/null $$p; \
 	done
 
-# Automatically define DOC_SRCS_ for each language
+# Automatically define DOC_SRCS_ for each language by reading the
+# translated-file list straight out of po4a.cfg.  Deriving from po4a.cfg
+# (rather than scanning $(L)/ with $(wildcard) or assuming every English
+# source has a translation) gives two properties at once: the list does
+# not depend on po4a having already produced the files (no "build twice"
+# fragility), and it does not include English-only sources like
+# drivers/mesa_modbus.adoc that are absent from the translation pipeline.
+TRANSLATED_DOC_SRCS := $(shell sed -nE 's|^\[type: AsciiDoc_def\] src/([^ ]+).*|\1|p' \
+    $(DOC_DIR)/po4a.cfg)
 $(foreach L,$(LANGUAGES),\
   $(eval DOC_SRCS_$(call toUC,$(L)) := \
-    $$(subst $$(DOC_SRCDIR)/,, \
-      $$(wildcard $$(DOC_SRCDIR)/$(L)/*.adoc) \
-      $$(wildcard $$(DOC_SRCDIR)/$(L)/*/*.adoc))))
+    $$(addprefix $(L)/,$$(TRANSLATED_DOC_SRCS))))
 
-# Define combined DOC_SRCS from all languages
+# Define combined DOC_SRCS from all languages.  Translated sources are
+# only pulled in when BUILD_DOCS_TRANSLATED=yes; otherwise the HTML / PDF
+# target lists derived from DOC_SRCS stay English-only and po4a is never
+# invoked.
 # DOC_SRCS_EN is manually defined at the very beginning of the file
-DOC_SRCS := $(DOC_SRCS_EN) $(foreach L,$(LANGUAGES),$(DOC_SRCS_$(call toUC,$L)))
+DOC_SRCS := $(DOC_SRCS_EN)
+ifeq ($(BUILD_DOCS_TRANSLATED),yes)
+DOC_SRCS += $(foreach L,$(LANGUAGES),$(DOC_SRCS_$(call toUC,$L)))
+endif
 
 $(foreach L,en $(LANGUAGES),\
   $(eval DOC_SRCS_$(call toUC,$(L))_SMALL := \
@@ -272,32 +315,22 @@ DOC_SRCS_HTML = $(patsubst %.adoc, %.html, $(foreach p, $(DOC_SRCS), $(if $(find
 DOC_TARGETS_HTML = $(addprefix $(DOC_DIR)/html/,$(DOC_SRCS_HTML)) #$(subst /,_,$(DOC_SRCS_HTML))
 DOC_TARGETS_XML = $(patsubst $(DOC_DIR)/html/%.html, objects/%.xml, $(DOC_TARGETS_HTML))
 
-DOC_TARGETS_XML_AR = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /ar/, $(p)), $p))
-DOC_TARGETS_XML_DE = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /de/, $(p)), $p))
-DOC_TARGETS_XML_ES = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /es/, $(p)), $p))
-DOC_TARGETS_XML_FR = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /fr/, $(p)), $p))
-DOC_TARGETS_XML_NB = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /nb/, $(p)), $p))
-DOC_TARGETS_XML_RU = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /ru/, $(p)), $p))
-DOC_TARGETS_XML_SV = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /sv/, $(p)), $p))
-DOC_TARGETS_XML_TA = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /ta/, $(p)), $p))
-DOC_TARGETS_XML_TR = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /tr/, $(p)), $p))
-DOC_TARGETS_XML_UK = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /uk/, $(p)), $p))
-DOC_TARGETS_XML_ZH_CN = $(foreach p, $(DOC_TARGETS_XML), $(if $(findstring /zh_CN/, $(p)), $p))
-
-DOC_TARGETS_XML_EN = $(filter-out $(DOC_TARGETS_XML_AR), $(filter-out $(DOC_TARGETS_XML_DE), $(filter-out $(DOC_TARGETS_XML_ES), $(filter-out $(DOC_TARGETS_XML_FR), $(filter-out $(DOC_TARGETS_XML_NB), $(filter-out $(DOC_TARGETS_XML_RU), $(filter-out $(DOC_TARGETS_XML_SV), $(filter-out $(DOC_TARGETS_XML_TR), $(filter-out $(DOC_TARGETS_XML_UK), $(filter-out $(DOC_TARGETS_XML_ZH_CN), $(DOC_TARGETS_XML)))))))))))
-
-DOC_TARGETS_HTML_AR = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /ar/, $(p)), $p))
-DOC_TARGETS_HTML_DE = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /de/, $(p)), $p))
-DOC_TARGETS_HTML_ES = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /es/, $(p)), $p))
-DOC_TARGETS_HTML_FR = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /fr/, $(p)), $p))
-DOC_TARGETS_HTML_NB = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /nb/, $(p)), $p))
-DOC_TARGETS_HTML_RU = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /ru/, $(p)), $p))
-DOC_TARGETS_HTML_SV = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /sv/, $(p)), $p))
-DOC_TARGETS_HTML_TA = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /ta/, $(p)), $p))
-DOC_TARGETS_HTML_TR = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /tr/, $(p)), $p))
-DOC_TARGETS_HTML_UK = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /uk/, $(p)), $p))
-DOC_TARGETS_HTML_ZH_CN = $(foreach p, $(DOC_TARGETS_HTML), $(if $(findstring /zh_CN/, $(p)), $p))
-DOC_TARGETS_HTML_EN = $(filter-out $(DOC_TARGETS_HTML_AR), $(filter-out $(DOC_TARGETS_HTML_DE), $(filter-out $(DOC_TARGETS_HTML_ES), $(filter-out $(DOC_TARGETS_HTML_FR), $(filter-out $(DOC_TARGETS_HTML_NB), $(filter-out $(DOC_TARGETS_HTML_RU), $(filter-out $(DOC_TARGETS_HTML_SV), $(filter-out $(DOC_TARGETS_HTML_TA), $(filter-out $(DOC_TARGETS_HTML_TR), $(filter-out $(DOC_TARGETS_HTML_UK), $(filter-out $(DOC_TARGETS_HTML_ZH_CN), $(DOC_TARGETS_HTML))))))))))))
+# Per-language slices of DOC_TARGETS_XML / DOC_TARGETS_HTML, derived
+# from $(LANGUAGES) (which comes from po4a.cfg).  English is whatever
+# is left after every translated subtree is filtered out.
+$(foreach L,$(LANGUAGES),\
+  $(eval DOC_TARGETS_XML_$(call toUC,$(L)) = \
+    $$(foreach p,$$(DOC_TARGETS_XML),$$(if $$(findstring /$(L)/,$$(p)),$$(p)))))
+DOC_TARGETS_XML_EN = $(filter-out \
+    $(foreach L,$(LANGUAGES),$(DOC_TARGETS_XML_$(call toUC,$(L)))), \
+    $(DOC_TARGETS_XML))
+
+$(foreach L,$(LANGUAGES),\
+  $(eval DOC_TARGETS_HTML_$(call toUC,$(L)) = \
+    $$(foreach p,$$(DOC_TARGETS_HTML),$$(if $$(findstring /$(L)/,$$(p)),$$(p)))))
+DOC_TARGETS_HTML_EN = $(filter-out \
+    $(foreach L,$(LANGUAGES),$(DOC_TARGETS_HTML_$(call toUC,$(L)))), \
+    $(DOC_TARGETS_HTML))
 
 MAN_HTML_TARGETS = $(patsubst $(DOC_DIR)/man/%, $(DOC_DIR)/html/man/%.html, $(MAN_SRCS))
 
@@ -306,61 +339,19 @@ PDF_TARGETS_EN := $(addprefix $(DOC_DIR)/, $(patsubst %.adoc,%.pdf, \
         LinuxCNC_Manual_Pages.pdf \
         ) \
 
-PDF_TARGETS_AR = $(addprefix $(DOC_DIR)/, $(subst ar/,, \
-	$(patsubst %.adoc,%_ar.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter ar/Master_%,$(DOC_SRCS_AR))))))
-
-PDF_TARGETS_DE = $(addprefix $(DOC_DIR)/, $(subst de/,, \
-	$(patsubst %.adoc,%_de.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter de/Master_%,$(DOC_SRCS_DE))))))
-
-PDF_TARGETS_ES = $(addprefix $(DOC_DIR)/, $(subst es/,, \
-	$(patsubst %.adoc,%_es.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter es/Master_%,$(DOC_SRCS_ES))))))
-
-PDF_TARGETS_FR = $(addprefix $(DOC_DIR)/, $(subst fr/,, \
-	$(patsubst %.adoc,%_fr.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter fr/Master_%,$(DOC_SRCS_FR))))))
-
-PDF_TARGETS_NB = $(addprefix $(DOC_DIR)/, $(subst nb/,, \
-	$(patsubst %.adoc,%_nb.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter nb/Master_%,$(DOC_SRCS_NB))))))
-
-PDF_TARGETS_RU = $(addprefix $(DOC_DIR)/, $(subst ru/,, \
-	$(patsubst %.adoc,%_ru.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter ru/Master_%,$(DOC_SRCS_RU))))))
-
-PDF_TARGETS_SV = $(addprefix $(DOC_DIR)/, $(subst sv/,, \
-	$(patsubst %.adoc,%_sv.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter sv/Master_%,$(DOC_SRCS_SV))))))
-
-PDF_TARGETS_TA = $(addprefix $(DOC_DIR)/, $(subst ta/,, \
-	$(patsubst %.adoc,%_ta.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter ta/Master_%,$(DOC_SRCS_TA))))))
-
-PDF_TARGETS_TR = $(addprefix $(DOC_DIR)/, $(subst tr/,, \
-	$(patsubst %.adoc,%_tr.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter tr/Master_%,$(DOC_SRCS_TR))))))
-
-PDF_TARGETS_UK = $(addprefix $(DOC_DIR)/, $(subst uk/,, \
-	$(patsubst %.adoc,%_uk.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter uk/Master_%,$(DOC_SRCS_UK))))))
-
-PDF_TARGETS_ZH_CN = $(addprefix $(DOC_DIR)/, $(subst zh_CN/,, \
-	$(patsubst %.adoc,%_zh_CN.pdf, \
-	$(subst Master_,LinuxCNC_, $(filter zh_CN/Master_%,$(DOC_SRCS_ZH_CN))))))
-
-PDF_TARGETS = $(PDF_TARGETS_EN) $(PDF_TARGETS_AR) $(PDF_TARGETS_DE) $(PDF_TARGETS_ES) $(PDF_TARGETS_FR) $(PDF_TARGETS_NB) $(PDF_TARGETS_RU) $(PDF_TARGETS_SV) $(PDF_TARGETS_TA) $(PDF_TARGETS_TR) $(PDF_TARGETS_UK)
-# Do not add $(PDF_TARGETS_ZH_CN) to the line above, it is added below - only if xetex is available
+# Per-language PDF target lists, derived from $(LANGUAGES).
+$(foreach L,$(LANGUAGES),\
+  $(eval PDF_TARGETS_$(call toUC,$(L)) = \
+    $$(addprefix $$(DOC_DIR)/, $$(subst $(L)/,, \
+      $$(patsubst %.adoc,%_$(L).pdf, \
+      $$(subst Master_,LinuxCNC_, $$(filter $(L)/Master_%,$$(DOC_SRCS_$(call toUC,$(L))))))))))
 
-# Chinese PDFs only build with xetex - optional build-dependency on texlive-xetex
-ifneq (, $(shell command -v xetex))
-PDF_TARGETS += $(PDF_TARGETS_ZH_CN)
-DBLATEX_OPTS=--backend xetex
+PDF_TARGETS = $(PDF_TARGETS_EN)
+ifeq ($(BUILD_DOCS_TRANSLATED),yes)
+PDF_TARGETS += $(foreach L,$(LANGUAGES),$(PDF_TARGETS_$(call toUC,$(L))))
 endif
 
 info::
-	@$(ECHO) PDF_TARGETS_UK: $(PDF_TARGETS_UK)
 	@$(ECHO) PDF_TARGETS: $(PDF_TARGETS)
 
 
@@ -374,19 +365,6 @@ HTML_TARGETS = \
 		$(DOC_DIR)/html/%/index.html, \
 		$(wildcard $(DOC_DIR)/src/index_*.tmpl)))
 
-A2X = a2x --xsltproc-opts "--nonet \
-			   --stringparam toc.section.depth 3 \
-			   --stringparam toc.max.depth 2 \
-			   --stringparam generate.section.toc.level 2 \
-			   --stringparam generate.toc 'book toc,title chapter toc'" \
-	  --keep-artifacts \
-	  -a "scriptdir=$(DOC_SRCDIR)/" \
-	  --asciidoc-opts="-f $(DOC_SRCDIR)/docbook.conf" \
-	  --asciidoc-opts="-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf" \
-	  --dblatex-opts "-P doc.publisher.show=0 -P latex.output.revhistory=0 -s $(DOC_SRCDIR)/emc2.sty \
-			  -P latex.hyperparam=colorlinks,linkcolor=blue,filecolor=blue,urlcolor=blue,citecolor=blue \
-                          $(A2X_LATEX_ENCODING) $(DBLATEX_OPTS)"
-
 ifeq ($(TRIVIAL_BUILD),no)
 -include $(patsubst %.adoc, depends/%.d, $(DOC_SRCS))
 Makefile: $(patsubst %.adoc, depends/%.d, $(DOC_SRCS))
@@ -422,29 +400,97 @@ pdfdocs: svgs_made_from_dots $(PDF_TARGETS)
 
 htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en
 
-.htmldoc-stamp: copy_asciidoc_files gen_complist $(HTML_TARGETS) .images-stamp .include-stamp
+# When translations are enabled, the .adoc files in $(L)/ are produced by
+# the translateddocs target (po4a).  Teach make how to ask for them: the
+# rule below has the translated .adoc files depend on translateddocs as
+# an order-only prereq, with an empty recipe.  That gives make a "rule"
+# to satisfy them (so it does not stop with "No rule to make target ..."
+# when depends/%.d is evaluated on a fresh tree) without rebuilding them
+# every time translateddocs ticks.
+ifeq ($(BUILD_DOCS_TRANSLATED),yes)
+TRANSLATED_ADOC_TARGETS := $(addprefix $(DOC_SRCDIR)/, \
+    $(filter-out $(DOC_SRCS_EN), $(DOC_SRCS)))
+$(TRANSLATED_ADOC_TARGETS): | translateddocs ;
+endif
+
+# Depend on the stamp files, not the phony copy_asciidoc_files /
+# gen_complist aliases: a phony prereq is always "newer", so naming them
+# re-touched .htmldoc-stamp every run, dragging checkref and the css copy
+# with it.  The stamps fire only when their real inputs change.
+.htmldoc-stamp: .copy-asciidoc-stamp $(DOC_DIR)/.gen_complist-stamp $(HTML_TARGETS) .images-stamp .include-stamp $(DOC_DIR)/html/asciidoctor.css $(DOC_DIR)/html/rouge-github.css
 	touch $@
 
-copy_asciidoc_files: $(wildcard /etc/asciidoc/stylesheets/*.css) $(wildcard /etc/asciidoc/javascripts/*.js)
+# Stamp-gated css/js copy; copy_asciidoc_files stays as a phony alias.
+copy_asciidoc_files: .copy-asciidoc-stamp
+.copy-asciidoc-stamp: $(wildcard /etc/asciidoc/stylesheets/*.css) $(wildcard /etc/asciidoc/javascripts/*.js) $(DOC_SRCDIR)/lcnc-overrides.css
 	if test -n "$^"; then cp -f $^ $(DOC_DIR)/html ; fi
+	@touch $@
 
-gen_complist: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc $(MAN_HTML_TARGETS)
+$(DOC_DIR)/html/asciidoctor.css: $(ASCIIDOCTOR_DEFAULT_CSS)
+	@mkdir -p $(dir $@)
+	cp -f $< $@
+
+# Rouge ships theme CSS in the gem; with -a linkcss asciidoctor emits
+#  per page but does not copy
+# the file when -a copycss! is set.  Render the theme via the Rouge API
+# so the spans asciidoctor emits get coloured.  Combine light + dark
+# variants (dark gated on prefers-color-scheme) into one file.
+$(DOC_DIR)/html/rouge-github.css:
+	@mkdir -p $(dir $@)
+	ruby -e ' \
+	  require "rouge"; \
+	  t = Rouge::Themes::Github; \
+	  if t.respond_to?(:light!) && t.respond_to?(:dark!); \
+	    t.light!; \
+	    puts t.new(scope: ".rouge").render; \
+	    puts "@media (prefers-color-scheme: dark) {"; \
+	    t.dark!; \
+	    puts t.new(scope: ".rouge").render; \
+	    puts "}"; \
+	  else \
+	    warn "rouge does not support theme modes (Rouge::Themes::Github.light!); dark mode code highlighting will use Monokai"; \
+	    puts t.new(scope: ".rouge").render; \
+	    puts "@media (prefers-color-scheme: dark) {"; \
+	    puts Rouge::Themes::Monokai.new(scope: ".rouge").render; \
+	    puts "}"; \
+	  end' > $@
+
+# Stamp-file gate.  The phony alias was running the python script on
+# every build, rewriting components_gen.adoc with a fresh mtime, which
+# in turn invalidated documentation.pot and re-triggered po4a/HTML.
+#
+# components_gen.adoc itself is produced by the lighter rule above
+# (line ~252) which fires before po4a; that rule's $(MAN_SRCS) prereq
+# keeps the file in sync with the manpage source set.  Re-running
+# gen_complist.py here after MAN_HTML_TARGETS would rewrite the file
+# with HTML-existence-dependent content (different miss_in_man set),
+# bumping mtime past .pot and re-triggering po4a on the next build.
+# Broken-link validation against generated HTML is checkref's job.
+$(DOC_DIR)/.gen_complist-stamp: $(DOC_SRCDIR)/hal/components_gen.adoc $(MAN_HTML_TARGETS)
 	mkdir -p $(DOC_DIR)/html/hal
-	python3 $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc
+	@touch $@
 
+gen_complist: $(DOC_DIR)/.gen_complist-stamp
 
-CHECKREF_TARGETS := checkref_en $(foreach L,$(LANGUAGES),checkref_$(L))
 
-#checkref: checkref_en checkref_ar checkref_de checkref_es checkref_fr checkref_nb checkref_ru checkref_sv checkref_ta checkref_tr checkref_uk checkref_zh_CN
+CHECKREF_TARGETS := checkref_en $(foreach L,$(LANGUAGES),checkref_$(L))
+.PHONY: $(CHECKREF_TARGETS)
 checkref: $(CHECKREF_TARGETS)
 
-checkref_en: $(DOC_TARGETS_HTML_EN) $(DOC_DIR)/html/index.html $(DOC_DIR)/html/gcode.html .htmldoc-stamp
-	$(DOC_SRCDIR)/checkref English $^
+# checkref_* stay phony aliases; the link check lives in stamp-gated rules
+# so it only re-runs when the HTML changes.  .htmldoc-stamp is filtered out
+# of the args so the stamp file is not handed to the link checker.
+checkref_en: $(DOC_DIR)/.checkref-english-stamp
+$(DOC_DIR)/.checkref-english-stamp: $(DOC_TARGETS_HTML_EN) $(DOC_DIR)/html/index.html $(DOC_DIR)/html/gcode.html .htmldoc-stamp
+	$(DOC_SRCDIR)/checkref English $(filter %.html,$^)
+	@touch $@
 
 # Pattern rule for all languages
-checkref_%: $$(DOC_TARGETS_HTML_$$(call uc,$$*)) \
+checkref_%: $(DOC_DIR)/.checkref-%-stamp ;
+$(DOC_DIR)/.checkref-%-stamp: $$(DOC_TARGETS_HTML_$$(call uc,$$*)) \
              $$(DOC_DIR)/html/%/gcode.html .htmldoc-stamp
-	$(DOC_SRCDIR)/checkref $(call lang_name,$*) $$^
+	$(DOC_SRCDIR)/checkref $(call lang_name,$*) $(filter %.html,$$^)
+	@touch $@
 
 
 MAN_SRCS_NOSO = $(patsubst $(DOC_DIR)/man/%,%, \
@@ -456,11 +502,22 @@ PDF_MAN_ORDER := man1/linuxcnc.1 $(filter-out %/linuxcnc.1, $(filter man1/%, $(M
 	$(filter man3/hm2%.3, $(MAN_SRCS_NOSO)) \
 	$(filter man9/%, $(MAN_SRCS_NOSO))
 
-$(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: $(MAN_SRCS) objects/var-PDF_MAN_ORDER
-	@$(ECHO) Formatting manual pages as PDF
-	(cd $(DOC_DIR)/man; groff -t -rC1 -rD1 -Tps -man $(PDF_MAN_ORDER)) \
-		| ps2pdf - $@
+# The manual-pages PDF rule lives next to the other PDF rules
+# (further down, after the CJK font setup) so it can pick up
+# CJK_TTFS / DOC_FONT_DIR without forward references.
+
 
+# Files produced by pattern rules but not named as explicit goals are
+# treated as intermediate and deleted at the end of every build, which
+# triggers a full rebuild on the next invocation.  Two groups bite us:
+#  - per-language Master_*.pdf  (chain: .adoc -> %/Master_*.pdf
+#    -> LinuxCNC_*_.pdf)
+#  - the per-manpage HTML files  (chain: man/% -> html/man/%.html, used
+#    via $(HTML_TARGETS) but never as an explicit goal name)
+# Declaring them .SECONDARY keeps them on disk without affecting precious
+# -on-error semantics.
+.SECONDARY: $(foreach L,$(LANGUAGES),$(foreach D,Getting_Started Documentation Integrator Developer,$(DOC_SRCDIR)/$(L)/Master_$(D).pdf)) \
+            $(MAN_HTML_TARGETS)
 
 PDF_TARGETS_LinuxCNC_Getting_Started := $(DOC_DIR)/LinuxCNC_Getting_Started.pdf $(foreach L,$(LANGUAGES),$(DOC_DIR)/LinuxCNC_Getting_Started_$(L).pdf)
 
@@ -498,11 +555,11 @@ $(DOC_DIR)/LinuxCNC_Developer_%.pdf: $(DOC_SRCDIR)/%/Master_Developer.pdf
 	@ln -f $< $@
 
 
-$(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/%
+$(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% $(DOC_SRCDIR)/docinfo.html
 	@$(ECHO) Formatting $(notdir $<) as HTML
 	@mkdir -p $(dir $@)
 	$(Q)if grep -q '^\.so' $<; then \
-		ln -srf ../docs/html/man/$$(awk '{print $$2}' $<).html $@; \
+		ln -srf ../docs/html/man/$$(basename $$(dirname $<))/$$(basename $$(awk '{print $$2}' $<)).html $@; \
 	else \
 		N="$$(basename "$<").adoc"; \
 		D="$$(dirname "$<")"; \
@@ -515,38 +572,28 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/%
 			echo "Error: Cannot find manpage '$<' in adoc format"; \
 			exit 1; \
 		fi; \
-		asciidoc \
+		asciidoctor \
+			-r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \
+			-r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \
+			-r $(realpath $(DOC_SRCDIR))/extensions/rouge_ini.rb \
 			--doctype=manpage \
-			--backend=html \
+			--backend=html5 \
+			-a compat-mode \
 			-a mansource=LinuxCNC \
 			-a manmanual='LinuxCNC Documentation' \
-			-f $(DOC_SRCDIR)/xhtml11.conf \
-			-f $(DOC_SRCDIR)/xhtml11-head-foot.conf \
-			-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-			-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-			-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-			-a disable-javascript \
-			-a autowidth-option \
-			-a "footer-style=none" \
-			-a linkcss \
-			-a "scriptsdir=../.." \
-			-a "stylesdir=../.." \
-			-a stylesheet=linuxcnc.css \
+			-a "lcnc-cssrel=../../" \
+			-a docinfo=shared \
+			-a docinfodir=$(realpath $(DOC_SRCDIR)) \
+			-a source-highlighter=rouge \
+			-a rouge-style=github \
+			-a webfonts! \
+			-a linkcss -a copycss! \
+			-a "stylesdir=../../" \
 			-o $@ \
 			"$$F" \
 			; \
 	fi;
 
-SA := 
 $@
 
-$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp
+# PDF rule. Uses asciidoctor-pdf with our xref + image preprocessor
+# extensions and the LinuxCNC theme. The xref-root attribute is set
+# to the directory of the source file so each language tree gets
+# its own anchor index (Master_*.adoc under DOC_SRCDIR for English,
+# DOC_SRCDIR//Master_*.adoc for translations).
+DOC_FONT_DIR  = objects/.fonts
+# Locations of the NotoSerifCJK Regular / Bold TrueType Collections are
+# discovered by configure (via fontconfig with package-path fallbacks)
+# and exported through Makefile.inc, so the build works on any distro
+# that ships the .ttc, not only the Debian path.
+CJK_TTFS      = $(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf \
+                $(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf
+# DejaVu Sans Mono is the code-block font.  asciidoctor-pdf only looks for
+# fonts in pdf-fontsdir by filename, not via fontconfig, so discover the
+# files at build time and symlink them into DOC_FONT_DIR.  Keeps the
+# pdf-theme.yml portable (no absolute paths baked in).
+DEJAVU_TTFS   = $(DOC_FONT_DIR)/DejaVuSansMono.ttf \
+                $(DOC_FONT_DIR)/DejaVuSansMono-Bold.ttf \
+                $(DOC_FONT_DIR)/DejaVuSansMono-Oblique.ttf \
+                $(DOC_FONT_DIR)/DejaVuSansMono-BoldOblique.ttf
+DOC_FONTS     = $(CJK_TTFS) $(DEJAVU_TTFS)
+
+# Build a TrueType (glyf-based) copy of the Simplified Chinese cut of the
+# Noto Serif CJK font.  The system font is shipped only as a CFF/OTF
+# TrueType Collection and prawn 2.4 corrupts the PDF when asked to embed
+# CFF outlines, so we convert the curves with cu2qu first.  This is the
+# fallback font that lets the translated docs render their few non-Latin
+# characters; the base text is still served by Noto Serif.
+# Scan both docs/src and the po catalogues: the .po files hold the full
+# translated text, so the glyph subset no longer depends on whether po4a
+# has produced the per-language .adoc yet.  Without this the subset can
+# come up empty on a fresh build and the converter falls back to the full
+# ~65k-glyph face (~200s vs ~1.5s).
+$(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf: $(NOTOCJK_REGULAR_TTC) $(DOC_SRCDIR)/otf2ttf.py $(wildcard $(DOC_DIR)/po/*.po)
+	@mkdir -p $(DOC_FONT_DIR)
+	$(ECHO) "Converting CJK font to TTF: $(notdir $@)"
+	$(Q)python3 $(DOC_SRCDIR)/otf2ttf.py --ttc-index 2 --text-from $(DOC_SRCDIR) --text-from $(DOC_DIR)/po $< $@.tmp && mv $@.tmp $@
+
+$(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: $(NOTOCJK_BOLD_TTC) $(DOC_SRCDIR)/otf2ttf.py $(wildcard $(DOC_DIR)/po/*.po)
+	@mkdir -p $(DOC_FONT_DIR)
+	$(ECHO) "Converting CJK font to TTF: $(notdir $@)"
+	$(Q)python3 $(DOC_SRCDIR)/otf2ttf.py --ttc-index 2 --text-from $(DOC_SRCDIR) --text-from $(DOC_DIR)/po $< $@.tmp && mv $@.tmp $@
+
+# DejaVu Sans Mono discovery: fc-match resolves the canonical .ttf for
+# each style, we symlink it into DOC_FONT_DIR under its expected filename
+# so pdf-theme.yml can stay path-free.
+define DEJAVU_RULE
+$(DOC_FONT_DIR)/$(1): | $(DOC_FONT_DIR)
+	@F=$$$$(fc-match --format='%{file}' '$(2)' 2>/dev/null); \
+	if [ -z "$$$$F" ] || [ ! -r "$$$$F" ]; then \
+	    echo "fc-match could not locate '$(2)'; install fonts-dejavu" >&2; \
+	    exit 1; \
+	fi; \
+	ln -sf "$$$$F" $$@
+endef
+$(eval $(call DEJAVU_RULE,DejaVuSansMono.ttf,DejaVu Sans Mono:style=Book))
+$(eval $(call DEJAVU_RULE,DejaVuSansMono-Bold.ttf,DejaVu Sans Mono:style=Bold))
+$(eval $(call DEJAVU_RULE,DejaVuSansMono-Oblique.ttf,DejaVu Sans Mono:style=Oblique))
+$(eval $(call DEJAVU_RULE,DejaVuSansMono-BoldOblique.ttf,DejaVu Sans Mono:style=Bold Oblique))
+
+$(DOC_FONT_DIR):
+	@mkdir -p $@
+
+# svgs_made_from_dots is .PHONY; as a normal prereq it forces every PDF to
+# rebuild on every run.  Order-only (after the |) instead; the SVGs the PDF
+# embeds are tracked via .adoc-images-stamp.
+$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc .adoc-images-stamp $(DOC_FONTS) | svgs_made_from_dots
 	$(ECHO) Building $@
-	@rm -f $@
-	$(Q)$(A2X) -L -d book -vf pdf $< || (X=$$?; rm -f $@; exit $$X)
+	@rm -f $@ $@.raw
+	$(Q)timeout 900 asciidoctor-pdf \
+		 -r $(realpath $(DOC_SRCDIR))/extensions/xref_resolver.rb \
+		 -r $(realpath $(DOC_SRCDIR))/extensions/image_resolver.rb \
+		 -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \
+		 -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \
+		 -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ini.rb \
+		 --sourcemap \
+		 -a compat-mode \
+		 -a "doc-languages=$(LANGUAGES)" \
+		 -a xref-root=$(dir $<) \
+		 -a "xref-exclude=^($(LANGUAGES_MATCH))/" \
+		 -a "scriptdir=$(DOC_SRCDIR)/" \
+		 -a "pdf-fontsdir=$(realpath $(DOC_FONT_DIR));GEM_FONTS_DIR" \
+		 -a "lversion=$(shell cat ../VERSION)" \
+		 -a toc -a numbered \
+		 -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \
+		 -a source-highlighter=rouge \
+		 -a rouge-style=github \
+		 -d book \
+		 -o $@.raw $< || (X=$$?; rm -f $@.raw; \
+		    if [ $$X -eq 124 ]; then echo "asciidoctor-pdf timed out after 15 min on $<"; fi; \
+		    exit $$X)
+	$(Q)gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 \
+		 -dPassThroughJPEGImages=true \
+		 -dDownsampleColorImages=false \
+		 -dDownsampleGrayImages=false \
+		 -dDownsampleMonoImages=false \
+		 -dAutoFilterColorImages=false -dColorImageFilter=/FlateEncode \
+		 -dAutoFilterGrayImages=false  -dGrayImageFilter=/FlateEncode \
+		 -dNOPAUSE -dQUIET -dBATCH \
+		 -sOutputFile=$@ $@.raw \
+		 && rm -f $@.raw \
+		 || (X=$$?; rm -f $@ $@.raw; exit $$X)
+	@test -f $@
+
+# Manual pages PDF: previously produced from the generated troff files
+# with groff + ps2pdf, which lost syntax highlighting on code samples.
+# Now built from the .adoc sources via asciidoctor-pdf so highlighting
+# survives.  A small master document is generated each build that
+# includes every manpage in PDF_MAN_ORDER as a chapter (leveloffset=+1),
+# with a hard page break between entries.  Component pages whose .adoc
+# lives in objects/man/ (built by halcompile) are picked up alongside
+# the native ones in docs/src/man/.
+objects/LinuxCNC_Manual_Pages.adoc: objects/var-PDF_MAN_ORDER $(MAN_SRCS) $(DOC_SRCDIR)/Submakefile
+	@mkdir -p $(dir $@)
+	$(Q){ \
+	    echo "= LinuxCNC Manual Pages"; \
+	    echo ":doctype: book"; \
+	    echo ":source-highlighter: rouge"; \
+	    echo ":toc:"; \
+	    echo ":numbered:"; \
+	    echo; \
+	    for M in $(PDF_MAN_ORDER); do \
+	        if   [ -r "$(DOC_SRCDIR)/man/$$M.adoc" ]; then \
+	            echo "include::$(realpath $(DOC_SRCDIR))/man/$$M.adoc[leveloffset=+1]"; \
+	        elif [ -r "objects/man/$$M.adoc" ]; then \
+	            echo "include::$(realpath objects)/man/$$M.adoc[leveloffset=+1]"; \
+	        else \
+	            echo "Error: no .adoc source for manpage $$M" >&2; exit 1; \
+	        fi; \
+	        echo; \
+	        echo "<<<"; \
+	        echo; \
+	    done; \
+	} > $@.tmp
+	$(Q)mv -f $@.tmp $@
+
+$(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(DOC_FONTS)
+	@$(ECHO) Formatting manual pages as PDF
+	@rm -f $@ $@.raw
+	$(Q)timeout 900 asciidoctor-pdf \
+	    -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \
+	    -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \
+	    -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ini.rb \
+	    -a compat-mode \
+	    -a mansource=LinuxCNC \
+	    -a manmanual='LinuxCNC Documentation' \
+	    -a source-highlighter=rouge \
+		-a rouge-style=github \
+	    -a "pdf-fontsdir=$(realpath $(DOC_FONT_DIR));GEM_FONTS_DIR" \
+	    -a "lversion=$(shell cat ../VERSION)" \
+	    -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \
+	    -d book \
+	    -o $@.raw $< || (X=$$?; rm -f $@.raw; \
+	        if [ $$X -eq 124 ]; then echo "asciidoctor-pdf timed out after 15 min on $<"; fi; \
+	        exit $$X)
+	$(Q)gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 \
+	    -dPassThroughJPEGImages=true \
+	    -dDownsampleColorImages=false \
+	    -dDownsampleGrayImages=false \
+	    -dDownsampleMonoImages=false \
+	    -dAutoFilterColorImages=false -dColorImageFilter=/FlateEncode \
+	    -dAutoFilterGrayImages=false  -dGrayImageFilter=/FlateEncode \
+	    -dNOPAUSE -dQUIET -dBATCH \
+	    -sOutputFile=$@ $@.raw \
+	    && rm -f $@.raw \
+	    || (X=$$?; rm -f $@ $@.raw; exit $$X)
 	@test -f $@
 
 depends/%.d: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/asciideps .include-stamp
@@ -612,55 +821,6 @@ depends/%.d: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/asciideps .include-stamp
 	$(Q)$(DOC_SRCDIR)/asciideps $< > $@.tmp
 	@mv $@.tmp $@
 
-objects/%.links-stamp: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/links.xslt
-	@mkdir -p `dirname $@`
-	$(Q)asciidoc -f $(DOC_SRCDIR)/attribute-colon.conf -a "scriptdir=$(DOC_SRCDIR)/" -d book -o- -b docbook $< | xsltproc $(DOC_SRCDIR)/links.xslt - > $@.tmp || (X=$$?; rm -f $@; exit $$X)
-	$(Q)sh move-if-change $@.tmp $(patsubst %-stamp,%,$@)
-	$(Q)touch $@
-
-objects/%.links: objects/%.links-stamp
-	@:
-
-# Secondary is not working here.
-# See http://www.gnu.org/software/make/manual/make.html#Chained-Rules
-.PRECIOUS: objects/%.links-stamp
-
-objects/xref_en.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_EN_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_ar.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_AR_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_de.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_DE_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_es.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_ES_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_fr.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_FR_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_nb.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_NB_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_ru.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_RU_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_sv.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_SV_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_ta.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_TA_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_tr.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_TR_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_uk.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_UK_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
-objects/xref_zh_CN.links: $(patsubst %.adoc,objects/%.links,$(DOC_SRCS_ZH_CN_SMALL))
-	$(PYTHON) $(DOC_SRCDIR)/links_db_gen.py objects/ $^ > $@
-
 $(DOC_TARGETS_HTML): $(DOC_DIR)/html/%.html: $(DOC_SRCDIR)/%.html
 	@d=`dirname $*`; \
 	mkdir -p $(shell dirname $@)
@@ -672,14 +832,12 @@ $(DOC_TARGETS_HTML): $(DOC_DIR)/html/%.html: $(DOC_SRCDIR)/%.html
 .html-images-stamp: $(DOC_TARGETS_HTML)
 	set -e; for HTML_FILE in $^; do \
 		HTML_DIR=$$(basename $$(dirname $$HTML_FILE)); \
-		for IMAGE_FILE in $$(xsltproc --novalid --nonet $(DOC_SRCDIR)/html-images.xslt $$HTML_FILE); do \
+		for IMAGE_FILE in $$(grep -oE 'src="[^"]+"' $$HTML_FILE | sed 's/src="//;s/"$$//' | grep -vE '^https?:|^data:|^/'); do \
 			IMAGE_DIR=$$(dirname $$IMAGE_FILE); \
 			IMAGE_PATH=$$(echo $(DOC_SRCDIR)/$$HTML_DIR/$$IMAGE_FILE | sed -E 's%/src/($(LANGUAGES_MATCH))/%/src/%'); \
 			mkdir -p $(DOC_DIR)/html/$$HTML_DIR/$$IMAGE_DIR; \
 			cp -f $$IMAGE_PATH $(DOC_DIR)/html/$$HTML_DIR/$$IMAGE_FILE; \
 		done; \
-		mkdir -p objects/image-cache; \
-		HTML_LATEX_CACHE=objects/image-cache $(DOC_SRCDIR)/html-latex-images $$HTML_FILE || (X=$$?; rm $$HTML_FILE; exit $$X); \
 	done > $@.new && mv $@.new $@
 
 # Hack to avoid ../../../src/ style include which do not work with
@@ -705,8 +863,13 @@ $(DOC_TARGETS_HTML): $(DOC_DIR)/html/%.html: $(DOC_SRCDIR)/%.html
 	done) > $@.new && mv $@.new $@
 
 # Copy all images used by translated adoc files into the directories
-# with translated adoc files.
-.adoc-images-stamp: translateddocs $(addprefix $(DOC_SRCDIR)/, $(filter-out $(DOC_SRCS_EN), $(DOC_SRCS)))
+# with translated adoc files.  The .translateddocs-stamp prerequisite
+# only exists when BUILD_DOCS_TRANSLATED=yes; without it the rule has
+# no work to do (filter-out yields empty) so we skip the dep too.
+ifeq ($(BUILD_DOCS_TRANSLATED),yes)
+ADOC_IMAGES_STAMP_DEPS := $(DOC_DIR)/.translateddocs-stamp
+endif
+.adoc-images-stamp: $(ADOC_IMAGES_STAMP_DEPS) $(addprefix $(DOC_SRCDIR)/, $(filter-out $(DOC_SRCS_EN), $(DOC_SRCS)))
 	set -e; for ADOC_FILE in $(addprefix $(DOC_SRCDIR)/, $(filter-out $(DOC_SRCS_EN), $(DOC_SRCS))); do \
 		ADOC_DIR=$$(echo $$(dirname $$ADOC_FILE) | sed s%$(DOC_SRCDIR)/%% ); \
 		echo Processing $$ADOC_FILE, dir $$ADOC_DIR; \
@@ -725,198 +888,43 @@ $(DOC_TARGETS_HTML): $(DOC_DIR)/html/%.html: $(DOC_SRCDIR)/%.html
 		done; \
 	done > $@.new && mv $@.new $@
 
-# Define a target-specific variable called STYLES_SCRIPTS_DIR, which has
-# the relative path from this html target to the root of the generated
-# document tree (docs/html in the git repo).  This is where the CSS files
-# and javascript files will be installed.
-$(DOC_SRCDIR)/%.html: STYLES_SCRIPTS=$(shell \
-    D=$$(python3 -c "print('../' * '$*'.count('/'))"); \
-    if [ ! -z $$D ]; then \
-        echo "-a 'scriptsdir=$$D' -a 'stylesdir=$$D'"; \
-    fi \
-)
+# Relative path from this html target back to DOC_SRCDIR, used to point
+# the lcnc-overrides.css  in docinfo.html at the right place.
+$(DOC_SRCDIR)/%.html: LCNC_CSSREL=$(shell python3 -c "print('../' * '$*'.count('/'))")
+
+# asciidoctor HTML rule used for every language. $1 is the language tag
+# in lowercase (en, ar, de, ...); $2 is the directory the xref index is
+# rooted at (the source tree root for the language).
+define ASCIIDOCTOR_HTML_RULE
+$$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$(DOC_SRCDIR)/%.html: $$(DOC_SRCDIR)/%.adoc $$(DOC_SRCDIR)/docinfo.html
+	$$(ECHO) "Building '$1' adoc to html: " $$<
+	$$(Q)asciidoctor -r $$(realpath $$(DOC_SRCDIR))/extensions/xref_resolver.rb \
+		 -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_hal.rb \
+		 -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_ngc.rb \
+		 -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_ini.rb \
+		 -a compat-mode \
+		 -a xref-root=$2 \
+		 -a "xref-exclude=$3" \
+		 -a "relindir=$$(shell dirname $$*)" \
+		 -a "lcnc-cssrel=$$(LCNC_CSSREL)" \
+		 -a docinfo=shared \
+		 -a docinfodir=$$(realpath $$(DOC_SRCDIR)) \
+		 -a source-highlighter=rouge \
+		 -a rouge-style=github \
+		 -a webfonts! \
+		 -a linkcss -a copycss! \
+		 -a "stylesdir=$$(LCNC_CSSREL)" \
+		 -d book -a toc -a numbered \
+		 -o $$@ $$< || (X=$$$$?; rm -f $$@; exit $$$$X)
+endef
+
+# English is rooted at the doc tree root so it must exclude all language
+# subdirs from its xref index. Translated languages are rooted at their
+# own subtree so the exclude is empty.
+$(eval $(call ASCIIDOCTOR_HTML_RULE,en,$(DOC_SRCDIR),^($(LANGUAGES_MATCH))/))
+$(foreach lang,$(LANGUAGES),\
+    $(eval $(call ASCIIDOCTOR_HTML_RULE,$(lang),$(DOC_SRCDIR)/$(lang))))
 
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_EN_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_en.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'en' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_en.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_AR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_ar.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'ar' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_ar.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_DE_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_de.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'de' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_de.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_ES_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_es.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'es' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_es.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_FR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_fr.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'fr' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_fr.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_NB_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_nb.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'nb' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_nb.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_RU_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_ru.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'ru' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_ru.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_SV_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_sv.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'sv' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_sv.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_TA_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_ta.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'ta' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_ta.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_TR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_tr.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'tr' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_tr.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_UK_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_uk.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'uk' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 -a linkcss \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_uk.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_ZH_CN_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_zh_CN.links $(LOC_LANG_MAP)
-	$(ECHO) "Building 'zh_CN' adoc to html: " $<
-	$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
-		 -f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
-		 -a linkcss \
-		 -f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
-		 -a "source_highlight_dir=$(LOC_HL_DIR)/local" \
-		 $(STYLES_SCRIPTS) \
-	         -a "scriptdir=$(DOC_SRCDIR)/" \
-	         -a "relindir=$(shell dirname $*)" \
-	         -a "linksfile=objects/xref_zh_CN.links" \
-		 -a stylesheet=linuxcnc.css \
-		 -d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
-
-
-# Conversion to HTML
-# Define common prerequisites
-COMMON_DEPS_CONVERSION := $(DOC_SRCDIR)/xref.xsl $(DOC_SRCDIR)/docs.xml $(DOC_SRCDIR)/terms.xml
-
-# Declare all final HTML targets
-HTML_TARGETS := $(foreach L,$(LANGUAGES),$(DOC_DIR)/html/$(L)/xref.html)
-
-$(DOC_DIR)/html/%/xref.html: objects/xref_%.xml $(COMMMON_DEPS_CONVERSION)
-	@$(ECHO) Converting $< to HTML
-	xsltproc --stringparam docname "xref_$*" \
-		--stringparam language $(call lang_name,$*) \
-		--path objects -o $@ $(DOC_SRCDIR)/xref.xsl $<
 
 default: docs
 
@@ -948,6 +956,7 @@ docclean:
 	-rm -f $(DOC_SRCDIR)/*/gui/gmoccapy_release_notes.txt
 	-rm -f $(DOC_DIR)/html/*/drivers/mb2hal_HOWTO.ini
 	-rm -f $(DOC_DIR)/html/drivers/mb2hal_HOWTO.ini
+	-rm -rf $(DOC_FONT_DIR)
 	-rm -f $(DOC_DIR)/html/gui/gmoccapy_release_notes.txt
 	-rm -f $(DOC_DIR)/html/*/gui/gmoccapy_release_notes.txt
 	-rm -f $(DOC_DIR)/html/code/*.*
@@ -970,10 +979,14 @@ docclean:
 	-rm -f $(DOC_DIR)/html/man/man9/*.*
 	-rm -f $(DOC_TARGETS_HTML) $(DOC_DIR)/html/xref*.html $(DOC_DIR)/html/index*.html $(DOC_DIR)/*.png $(DOC_DIR)/man/*.png
 	-rm -f .htmldoc-stamp
+	-rm -f .copy-asciidoc-stamp
 	-rm -f .adoc-images-stamp
 	-rm -f .html-images-stamp
 	-rm -f .images-stamp
 	-rm -f .include-stamp
+	-rm -f $(DOC_DIR)/.translateddocs-stamp
+	-rm -f $(DOC_DIR)/.gen_complist-stamp
+	-rm -f $(DOC_DIR)/.checkref-*-stamp
 	-rm -f $(DOTFILES:.dot=.svg)
 	$(RM) $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc
 
@@ -983,7 +996,7 @@ $(MAN_DEPS): depends/%.d: $(DOC_DIR)/man/%
 	@echo Depending $(notdir $<)
 	@mkdir -p $(dir $@)
 	$(Q)echo -n "$(DOC_DIR)/html/man/$*.html: $<" > $@.tmp
-	$(Q)grep '^\.so ' $< | awk '{printf " \\\n\t$(DOC_DIR)/man/%s", $$2}' >> $@.tmp
+	$(Q)grep '^\.so ' $< | awk '{ if ($$2 ~ /\//) printf " \\\n\t$(DOC_DIR)/man/%s", $$2; else printf " \\\n\t$(DOC_DIR)/man/$(*D)/%s", $$2 }' >> $@.tmp
 	$(Q)echo >> $@.tmp
 	$(Q)mv -f $@.tmp $@
 
@@ -996,7 +1009,7 @@ endif
 	dot -Tpng -o$@ $<
 
 %.svg: %.dot
-	dot -Tsvg -o$@ $<
+	dot -Tsvg -Gbgcolor=transparent -o$@ $<
 
 %.png:; $(error Required image file $@ does not exist)
 %.jpg:; $(error Required image file $@ does not exist)
@@ -1020,26 +1033,14 @@ manpages: $(GENERATED_MANPAGES)
 TARGETS += manpages
 
 # make manpages from all the asciidoc manpage-sources
-# Note that in some versions of asciidoc, including the one in Debian Jessie,
-# a2x spuriously warns that this --destination-dir is ignored.  It is *NOT*
-# ignored, don't remove it trying to fix the diagnostic.
-# For more information, see https://github.com/asciidoc/asciidoc/issues/44
 GENERATED_MANPAGES += $(patsubst $(DOC_DIR)/src/man/%.adoc, $(DOC_DIR)/man/%, $(wildcard $(DOC_DIR)/src/man/man?/*.adoc))
 $(DOC_DIR)/man/%: $(DOC_DIR)/src/man/%.adoc
 	$(ECHO) Making manpage $(notdir $@)
 	@mkdir -p $(dir $@)
-	$(Q)a2x --doctype manpage \
-		--format manpage \
-		--destination-dir $(dir $@) \
-		--xsltproc-opts="--nonet" \
+	$(Q)asciidoctor --doctype=manpage \
+		--backend=manpage \
+		--destination-dir="$(dir $@)" \
+		-a compat-mode \
 		-a mansource=LinuxCNC \
 		-a manmanual='LinuxCNC Documentation' \
 		$<
-#	$(Q)asciidoctor \
-#		--doctype=manpage \
-#		--backend=manpage \
-#		--destination-dir="$(dir $@)" \
-#		-a mansource=LinuxCNC \
-#		-a manmanual='LinuxCNC Documentation' \
-#		$<
-#	$(Q)../scripts/fixup_man_alias "$<" "$(dir $@)"
diff --git a/docs/src/asciidoc-dont-replace-arrows.conf b/docs/src/asciidoc-dont-replace-arrows.conf
deleted file mode 100644
index c2119458107..00000000000
--- a/docs/src/asciidoc-dont-replace-arrows.conf
+++ /dev/null
@@ -1,16 +0,0 @@
-
-[replacements]
-
-# Arrows from the Arrows block of Unicode.
-# -> right arrow
-(? right double arrow
-(?[\w\-_:]+)(,(?P.*?))?\]\]$)|(^\[(?P.*)\]$)
diff --git a/docs/src/docbook-image.conf b/docs/src/docbook-image.conf
deleted file mode 100644
index 555284940b1..00000000000
--- a/docs/src/docbook-image.conf
+++ /dev/null
@@ -1,24 +0,0 @@
-# Allow wildcards in image names
-[image-inlinemacro]
-
-  
-  
-  
-  {alt={target}}
-
-
-[image-blockmacro]
-{title}
-{title%}{pgwide-option?}
-# DocBook XSL Stylesheets custom processing instructions.
-
-
-
-  
-  
-  
-  {alt={target}}
-
-{title#}
-{title%}
-
diff --git a/docs/src/docbook.conf b/docs/src/docbook.conf
deleted file mode 100644
index dfab8247bb5..00000000000
--- a/docs/src/docbook.conf
+++ /dev/null
@@ -1,2 +0,0 @@
-include::attribute-colon.conf[]
-include::docbook-image.conf[]
diff --git a/docs/src/emc2.sty b/docs/src/emc2.sty
deleted file mode 100644
index dc000d1152c..00000000000
--- a/docs/src/emc2.sty
+++ /dev/null
@@ -1,25 +0,0 @@
-%%
-%% Fixed LinuxCNC (formerly known as EMC2) Documentation style
-%%
-\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{emc2doc}[2011/02/10 EMC2 Style]
-%% XXX: Here starts verbatim copy of asciidoc-docbook.sty
-
-%% Just use the original package and pass the options.
-\RequirePackageWithOptions{docbook}
-
-% Sidebar is a boxed minipage that can contain verbatim.
-% Changed shadow box to double box.
-\renewenvironment{sidebar}[1][0.95\textwidth]{
-  \hspace{0mm}\newline%
-  \noindent\begin{Sbox}\begin{minipage}{#1}%
-  \setlength\parskip{\medskipamount}%
-}{
-  \end{minipage}\end{Sbox}\doublebox{\TheSbox}%
-}
-
-% For DocBook literallayout elements, see `./dblatex/dblatex-readme.txt`.
-\usepackage{alltt}
-%% XXX: Here ends verbatim copy of asciidoc-docbook.sty
-
-\usepackage{grffile}
diff --git a/docs/src/html-images.xslt b/docs/src/html-images.xslt
deleted file mode 100644
index af170676361..00000000000
--- a/docs/src/html-images.xslt
+++ /dev/null
@@ -1,23 +0,0 @@
-
-
-
-
-
-
-  
-    
-
-  
-  
-    
-       
-
-    
-  
-
-
-
diff --git a/docs/src/html-latex-images b/docs/src/html-latex-images
deleted file mode 100755
index cb7ecc95f21..00000000000
--- a/docs/src/html-latex-images
+++ /dev/null
@@ -1,91 +0,0 @@
-#!/usr/bin/env python3
-# vim: sts=4 sw=4 et
-
-import os, shutil, sys, subprocess
-import tempfile, hashlib
-import lxml.etree as ET
-
-tmpdir = None
-
-cachedir = os.environ.get('HTML_LATEX_CACHE', './cache')
-
-nsmap = {'xhtml':"http://www.w3.org/1999/xhtml"}
-
-latex_header = r"""
-\documentclass{article}
-\usepackage[mathletters]{ucs}
-\usepackage[utf8x]{inputenc}
-%\usepackage[T2A]{fontenc}
-%\usepackage[english,russian]{babel}
-\usepackage{euscript}
-\usepackage{type1cm}
-\usepackage{amssymb}
-\usepackage{amsmath}
-\usepackage{ulem}
-\usepackage{mathrsfs}
-\begin{document}
-\thispagestyle{empty}
-"""
-
-latex_footer = r"""
-\end{document}
-"""
-
-latex_cmd = "latex -interaction nonstopmode ./file.tex".split()
-dvipng_cmd = "dvipng -q -D 148 -T tight -pp 1 --noghostscript file.dvi -o file.png".split() 
-
-def build_img(fn, e, block=False):
-    txt = e.text.strip()
-    txt = txt.replace('>', '>').replace('<', '<').replace('&', '&') # XML escapes
-    txt = txt.replace('\\[', '[').replace('\\]', ']') # Asciidoc escapes
-    md5 = hashlib.md5(txt.encode('utf-8')).hexdigest()
-    img = md5 + ".png"
-    fullimg = os.path.join(cachedir, img)
-    if not os.path.exists(fullimg):
-        latex(txt, block)
-        os.rename(os.path.join(tmpdir, 'file.png'), fullimg)
-    shutil.copy2(fullimg, os.path.join(os.path.dirname(fn), img))
-    node = ET.Element('img', attrib={'class':'latexmath'}, id=md5, src=img, title=txt)
-    e.getparent().replace(e, node)
-    return 1
-    
-def latex(txt, block=False):
-    if block:
-        if not txt.startswith('$$'): txt = '$$' + txt
-        if not txt.endswith('$$'): txt = txt + '$$'
-    else:
-        if txt[0] != '$': txt = '$' + txt
-        if txt[-1] != '$': txt = txt + '$'
-
-    fp = open(os.path.join(tmpdir, 'file.tex'), 'w')
-    fp.write(latex_header)
-    fp.write(txt.encode('utf-8') + '\n')
-    fp.write(latex_footer)
-    fp.close()
-    r = subprocess.call(latex_cmd, cwd=tmpdir)
-    if r: raise RuntimeError("Compilation failed")
-    r = subprocess.call(dvipng_cmd, cwd=tmpdir)
-    if r: raise RuntimeError("Compilation failed")
-
-def substitute(f):
-    xml = ET.parse(open(f), ET.HTMLParser())
-    images = 0
-    for e in xml.xpath('//span[@class="latexmath"]', namespaces=nsmap):
-        images += build_img(f, e, block=False)
-    for e in xml.xpath('//div[@class="latexmath"]', namespaces=nsmap):
-        images += build_img(f, e, block=True)
-    if not images: return
-    print("Added %d images" % images)
-    fp = open(f + ".math", 'w')
-    fp.write(ET.tostring(xml, pretty_print=True, xml_declaration=False, encoding="utf-8"))
-    fp.close()
-    os.unlink(f)
-    #os.rename(f, f + ".pre-math")
-    os.rename(f + ".math", f)
-
-tmpdir = tempfile.mkdtemp(dir=cachedir)
-try:
-    for f in sys.argv[1:]:
-        substitute(f)
-finally:
-    shutil.rmtree(tmpdir)
diff --git a/docs/src/image-wildcard b/docs/src/image-wildcard
deleted file mode 100755
index dadbca6b256..00000000000
--- a/docs/src/image-wildcard
+++ /dev/null
@@ -1,55 +0,0 @@
-#!/usr/bin/env python3
-
-import os, sys, glob
-
-def relpath(path, start):
-    """Return a relative version of a path"""
-
-    if not path:
-        raise ValueError("no path specified")
-
-    start_list = os.path.abspath(start).split(os.path.sep)
-    path_list = os.path.abspath(path).split(os.path.sep)
-
-    # Work out how much of the filepath is shared by start and path.
-    i = len(os.path.commonprefix([start_list, path_list]))
-
-    rel_list = [os.path.pardir] * (len(start_list)-i) + path_list[i:]
-    if not rel_list:
-        return os.path.curdir
-    return os.path.join(*rel_list)
-
-if len(sys.argv) > 1:
-	image = sys.argv[1]
-
-if len(sys.argv) > 2:
-	docpath = sys.argv[2] #os.path.dirname(sys.argv[2])
-else:
-	docpath = '.'
-
-if len(sys.argv) > 3 and str.strip(sys.argv[3]):
-	exts = [s.strip() for s in sys.argv[3].split(',')]
-else:
-	# Standard images for web
-	exts = ['png', 'svg', 'jpg', 'jpeg']
-
-exts = ['.' + e for e in exts]
-
-def lookup(image):
-	images = glob.glob(os.path.join(docpath, image))
-	if not images:
-		return
-	elif len(images) == 1:
-		return images[0]
-
-	found = [os.path.splitext(s)[1] for s in images]
-	for e in exts:
-		if e not in found:
-			continue
-		return images[found.index(e)]
-	else:
-		return images[0]
-i = lookup(image)
-if not i:
-	i = image
-print((relpath(i, docpath)))
diff --git a/docs/src/links.xslt b/docs/src/links.xslt
deleted file mode 100644
index 8fe78e5c539..00000000000
--- a/docs/src/links.xslt
+++ /dev/null
@@ -1,44 +0,0 @@
-
-
-
-
-
-
-
-  
-    
-
-  
-
-  
-    
-
-  
-
-  
-    
-
-  
-
-  
-    
-
-  
-
-  
-    
-
-  
-
-  
-    
-      
-
-    
-  
-
-
-
-
diff --git a/docs/src/links_db_gen.py b/docs/src/links_db_gen.py
deleted file mode 100755
index b32fddab62f..00000000000
--- a/docs/src/links_db_gen.py
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/usr/bin/env python3
-import os, sys
-
-d = {}
-
-strip = sys.argv[1]
-
-for f in sys.argv[2:]:
-    base = os.path.splitext(f)[0]
-    if base.startswith(strip):
-        base = base[len(strip):]
-    for l in open(f):
-        l = l.strip().replace(' ', '_')
-        if not l:
-            continue
-        d[l] = base
-for k, v in list(d.items()):
-    print('%s\t%s' % (k, v))
diff --git a/docs/src/source-highlight/README b/docs/src/source-highlight/README
deleted file mode 100644
index d349c21aa23..00000000000
--- a/docs/src/source-highlight/README
+++ /dev/null
@@ -1,76 +0,0 @@
-source-highlighting EMC languages in HTML documents
-===================================================
-
-I've created GNU source-highlight language definitions for G-code and
-halcmd to highlight .hal and .ngc files in asciidoc. INI file
-highlighting works out of the box. All three need a bit of trickery to
-work cleanly for both HTML and PDF.
-
-Highlighting is for HTML output only at this point in time.  To have
-PDFs highlighted, the file
-/usr/share/texmf-texlive/tex/latex/listings/lstlang1.sty needs to be
-extended to deal with NGC, HAL and INI formats, and put into the build
-directory so dblatex can find it.
-
-Highlighting halcmd, INI and NGC source in HTML is now integrated into
-the documentation build process. Tcl, Python, sh etc keep working out
-of the box.
-
-NB: source-highlight's mechanisms to find .lang and .map files is
-very inflexible which is why the complete source language definition
-directory (/usr/share/source-highlight) needs to be replicated under 'local',
-and a new lang.map generated in there (all language definitions are
-relative to this directory, and include each other).
-
-Using NGC, HAL and INI file snippets in your .txt files:
-========================================================
-Copy this to the top of your txt file:
------------------ snip ----------------
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
-// Begin a listing of INI/HAL/NGC files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
------------------ snip ----------------
-
-Adding or changing a language definition (.lang) file
-======================================================
-
-New language: just drop .lang into this directory. The
-source-highlight configuration will be rebuilt to include this
-language.  then can be used in [source,{named}] listings. You
-might need a conditional like
-
-:name: {basebackend@docbook:'':name}
-
-to prevent pdflatex formatting errors.
-
-Changing a language definition: just edit the .lang file in this directory.
-
-Overruling definitions in the source-highlight standard language definitions:
-
-Copy the .lang file from /usr/share/source-highlight into
-this directory and edit as needed. The right things should happen on
-build (including a massive initial rebuild ;-)
-
-
-Building HTML examples in the this directory
-============================================
-
-To produce PDF and HTML samples, type 'make examples' .
-
-This should produce {ini-demo,hal-demo,ngc-demo}.{pdf,html} files in
-the current directory, with proper highlighting of HTML only. PDF files
-come out properly but have no highlighting.
-
---------------------------------------------
-
-I found this tool very helpful for writing GNU source-highlight .lang
-definitions:
-
-https://srchighliteide.sourceforge.net/
-
-Michael Haberler 3/2011
diff --git a/docs/src/source-highlight/Submakefile b/docs/src/source-highlight/Submakefile
deleted file mode 100644
index af2940aa047..00000000000
--- a/docs/src/source-highlight/Submakefile
+++ /dev/null
@@ -1,63 +0,0 @@
-# The source-highlight language defs and lang.map dir
-HL_DIR=/usr/share/source-highlight
-
-LOC_HL_DIR=../docs/src/source-highlight
-LOC_LANG_MAP=$(LOC_HL_DIR)/local/lang.map
-
-# Languages for which we provide our own .lang files.
-# This includes overriding languages listed in HL_DIR.
-EMCLANGS=$(wildcard $(LOC_HL_DIR)/*.lang)
-
-# Grep arg to suppress user defined langs already in lang.map
-GREPARG= $(patsubst %, -e %,$(EMCLANGS))
-
-# Examples
-SOURCE_HIGHLIGHT_PDF_TARGETS := $(patsubst %.adoc, %.pdf, $(wildcard $(LOC_HL_DIR)/*.txt))
-SOURCE_HIGHLIGHT_HTML_TARGETS := $(patsubst %.adoc, %.html ,$(wildcard $(LOC_HL_DIR)/*.txt))
-
-# Tests with HTML output without going through asciidoc
-TEST_SRCS := hal-test.hal ini-test.ini ngc-test.ngc
-TEST_TARGETS := hal-test.html ini-test.html ngc-test.html
-
-
-TARGET=$(LOC_HL_DIR)/local/lang.map
-ASCIIDOC_ARGS=-a source_highlight_dir=local -f emc-langs-source-highlight.conf
-
-$(TARGET): $(EMCLANGS) $(HL_DIR)/lang.map
-ifeq (,$(findstring lang.map,$(wildcard $(HL_DIR)/*)))#
-	$(error $(HL_DIR)/lang.map does not exist - are you sure \
-	the 'source-highlight'  package is installed?)
-endif
-	rm -rf $(LOC_HL_DIR)/local
-	cp -r $(HL_DIR) $(LOC_HL_DIR)/local
-	mv $(LOC_HL_DIR)/local/lang.map $(LOC_HL_DIR)/local/lang.map.dist
-	cp $(LOC_HL_DIR)/*.lang $(LOC_HL_DIR)/local
-	grep -v $(GREPARG) $(LOC_HL_DIR)/local/lang.map.dist >$(TARGET)
-	for i in $(EMCLANGS); do \
-             echo `basename $$i .lang` '=' `basename $$i` >>$(TARGET) ; \
-        done
-
-examples: $(TARGET) $(SOURCE_HIGHLIGHT_HTML_TARGETS) $(SOURCE_HIGHLIGHT_PDF_TARGETS) tests
-
-
-tests: 	$(TARGET) $(TEST_TARGETS)
-
-
-%.html:	%.ini
-	source-highlight --data-dir=local --input $< --output $@
-
-%.html:	%.ngc
-	source-highlight --data-dir=local --input $< --output $@
-
-%.html:	%.hal
-	source-highlight --data-dir=local --input $< --output $@
-
-docclean: clean-source-highlight
-clean-source-highlight:
-	-rm -rf local $(SOURCE_HIGHLIGHT_HTML_TARGETS) $(SOURCE_HIGHLIGHT_PDF_TARGETS) $(TEST_TARGETS)
-
-$(SOURCE_HIGHLIGHT_PDF_TARGETS):  %.pdf: %.adoc
-	a2x -v -f pdf $<
-
-$(SOURCE_HIGHLIGHT_HTML_TARGETS): %.html: %.adoc
-	asciidoc $(ASCIIDOC_ARGS) -v  $<
diff --git a/docs/src/source-highlight/emc-langs-source-highlight.conf b/docs/src/source-highlight/emc-langs-source-highlight.conf
deleted file mode 100644
index d26473ca426..00000000000
--- a/docs/src/source-highlight/emc-langs-source-highlight.conf
+++ /dev/null
@@ -1,118 +0,0 @@
-#
-# This file is modified from  /etc/asciidoc/filters/source/source-highlight-filter.conf
-# and modified to support additional languages (ngc,halcmd)
-# it is passed to asciidoc as -f  option
-#
-# Michael Haberler 3/2011
-#
-#-------------
-#
-# AsciiDoc source code highlight filter configuration file.
-#
-# Documented in source-highlight-filter.txt in AsciiDoc distribution
-# ./examples/website/ directory.
-#
-# HTML outputs require GNU source-highlight
-# http://www.gnu.org/software/src-highlite/source-highlight.html
-#
-
-########################
-# Source block templates
-########################
-[source-highlight-block]
-template::[listingblock]
-
-ifdef::basebackend-html[]
-[source-highlight-block]
-
-
{title}

-

-|
-

-endif::basebackend-html[]
-
-# Customized listingblock block for xhtml11 to ensure valid XHTML1.1.
-ifdef::backend-xhtml11[]
-[source-highlight-block]
-

-
-
{caption=}{title}

-

-|
-

-endif::backend-xhtml11[]
-
-# Use DocBook programlisting element.
-ifdef::backend-docbook[]
-[source-highlight-block]
-{title}
-
-|
-
-{title#}
-endif::backend-docbook[]
-
-#########################
-# Source paragraph styles
-#########################
-[paradef-default]
-ifdef::basebackend-html[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("callouts",),posattrs=("style","language","src_numbered","src_tab"),filter="source-highlight -f html  --data-dir={source_highlight_dir} -s {language} {src_numbered?--line-number} {src_tab?--tab={src_tab}}"
-endif::basebackend-html[]
-
-ifdef::backend-xhtml11[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("callouts",),posattrs=("style","language","src_numbered","src_tab"),filter="source-highlight -f xhtml  --data-dir={source_highlight_dir} -s {language} {src_numbered?--line-number} {src_tab?--tab={src_tab}}"
-endif::backend-xhtml11[]
-
-ifdef::backend-docbook[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("specialcharacters","callouts"),posattrs=("style","language","src_numbered","src_tab"),filter=""
-endif::backend-docbook[]
-
-#########################
-# Source block styles
-#########################
-[blockdef-listing]
-ifdef::basebackend-html[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("callouts",),posattrs=("style","language","src_numbered","src_tab"),filter="source-highlight -f html  --data-dir={source_highlight_dir} -s {language} {src_numbered?--line-number} {src_tab?--tab={src_tab}}"
-endif::basebackend-html[]
-
-ifdef::backend-xhtml11[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("callouts",),posattrs=("style","language","src_numbered","src_tab"),filter="source-highlight -f xhtml   --data-dir={source_highlight_dir}  -s {language} {src_numbered?--line-number} {src_tab?--tab={src_tab}}"
-endif::backend-xhtml11[]
-
-ifdef::backend-docbook[]
-source-style=template="source-highlight-block",presubs=(),postsubs=("specialcharacters","callouts"),posattrs=("style","language","src_numbered","src_tab")
-endif::backend-docbook[]
-
-
-#
-# DEPRECATED: Pre 8.2.7 filter definition.
-#
-
-#########################
-# Source block definition
-#########################
-[blockdef-source-highlight]
-# The old ^ delimiter is for backward compatibility, may be removed from
-# in future versions.
-delimiter=(^source~{4,}$)|(^\^{4,}$)
-template=source-highlight-block
-presubs=none
-posattrs=language,src_numbered,src_tab
-
-ifndef::backend-docbook[]
-postsubs=callouts
-# GNU Source Highlight filter.
-filter=source-highlight -f {backend-xhtml11?xhtml}{backend-html4?html}{backend-docbook?docbook} -s {language} {src_numbered?--line-number} {src_tab?--tab={src_tab}}
-endif::backend-docbook[]
-
-ifdef::backend-docbook[]
-postsubs=specialcharacters,callouts
-# In the case of DocBook just pass the listing through and let the DocBook
-# toolchain handle it.
-filter=
-endif::backend-docbook[]
-
-#
-# DEPRECATED: End
-#
diff --git a/docs/src/source-highlight/hal-demo.adoc b/docs/src/source-highlight/hal-demo.adoc
deleted file mode 100644
index f7975c103c0..00000000000
--- a/docs/src/source-highlight/hal-demo.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-:lang: en
-
-= Source Highlight Filter Test
-
-// for now, PDF's can't have highlighted ini,hal or ngc files
-// for brave souls: extend /usr/share/texmf-texlive/tex/latex/listings/lstlang1.sty
-// and make it a local copy in the current directory
-// HTML works fine
-
-// these attributes must come after the document title, to work around a bug in asciidoc 8.6.6
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
-// begin a listing of ini/hal/ngc files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
-
-Details of the filter can be found in `./doc/source-highlight-filter.txt`.
-
-[source,{hal}]
----------------------------------------------------------------------
-# note this is for highlighting demo only - there aint any use to it
-
-loadusr -W [MYSECTION]MYMODULE
-
-loadrt conv_float_s32 names=f2s32
-addf f2s32 servo-thread
-
-# in case they were linked already
-
-unlinkp motion.digital-out-01 471.11 $(envvar)
-unlinkp motion.digital-in-01  815  $VAR
-
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32.in [FOO]bAR
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32x.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 motion.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 motion.in
-net tool-change hal_manualtoolchange.56.change <= motion.digital-out-01
-net tool-changed hal_manualtoolchange.changed motion.digital-in-01
-net tool-prep-number hal_manualtoolchange.number f2s32.out
-
-# prepare loopback
-net tool-prepare motion.digital-out-00 motion.digital-in-00
----------------------------------------------------------------------
diff --git a/docs/src/source-highlight/hal-test.hal b/docs/src/source-highlight/hal-test.hal
deleted file mode 100644
index eb71a7b3569..00000000000
--- a/docs/src/source-highlight/hal-test.hal
+++ /dev/null
@@ -1,23 +0,0 @@
-# Note: This is for highlighting demo only - there aint any use to it
-
-loadusr -W [MYSECTION]MYMODULE
-
-loadrt conv_float_s32 names=f2s32
-addf f2s32 servo-thread
-
-# in case they were linked already
-
-unlinkp motion.digital-out-01 471.11 $(envvar)
-unlinkp motion.digital-in-01  815  $VAR
-
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32.in [FOO]bAR
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 f2s32x.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 motion.0.in
-net tool-prep-number-f  motion.0.analog-out-00 => motion.0.analog-out-00 motion.in
-net tool-change hal_manualtoolchange.56.change <= motion.digital-out-01
-net tool-changed hal_manualtoolchange.changed motion.digital-in-01
-net tool-prep-number hal_manualtoolchange.number f2s32.out
-
-# prepare loopback
-net tool-prepare motion.digital-out-00 motion.digital-in-00
diff --git a/docs/src/source-highlight/hal.lang b/docs/src/source-highlight/hal.lang
deleted file mode 100644
index 66972c1d86f..00000000000
--- a/docs/src/source-highlight/hal.lang
+++ /dev/null
@@ -1,28 +0,0 @@
-# language HAL (EMC Hardware Abstraction Layer)
-# as documented by halcmd(1)
-# Michael Haberler 3/2011
-# a bit unsure whether 'function' and 'label' are the appropriate styles
-
-keyword = "loadrt|unloadrt|loadusr|waitusr|unloadusr|unlinkp",
-  "unload|newsig|delsig|sets|stype|gets|linkps|linksp",
-  "linkpp|net|unlinkp|setp|ptype|getp|addf|delf",
-  "start|stop|show|item|save|source|alias|unalias|list|lock|unlock|status|help"
-
-symbol = "=>","<=","="
-
-# a pin name has a token, followed by at least one dot, and a word
-variable = '([[:alpha:]]|[_])[[:word:]]+\.([[:word:]]|[\-\.])+'
-
-# standalone token - a signal name, component name (no dots)
-function = '([[:alpha:]]|_)([[:word:]]|\-)*'
-
-# INIFILE variable
-label = '\[[[:alpha:]][[:word:]]+\][[:alpha:]][[:word:]]+'
-
-# environment variable
-label = '\$[[:alpha:]][[:word:]]+'
-label = '\$\([[:alpha:]][[:word:]]+\)'
-
-include "number.lang"
-
-comment start "#"
\ No newline at end of file
diff --git a/docs/src/source-highlight/ini-demo.adoc b/docs/src/source-highlight/ini-demo.adoc
deleted file mode 100644
index ee5657716dc..00000000000
--- a/docs/src/source-highlight/ini-demo.adoc
+++ /dev/null
@@ -1,234 +0,0 @@
-:lang: en
-
-= Source Highlight Filter Test
-
-Details of the filter can be found in `./doc/source-highlight-filter.txt`.
-
-// For now, PDF's can't have highlighted INI, HAL or ngc files.
-// For brave souls: extend /usr/share/texmf-texlive/tex/latex/listings/lstlang1.sty
-// and make it a local copy in the current directory.
-// HTML works fine.
-
-// these attributes must come after the document title, to work around a bug in asciidoc 8.6.6
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
-// Begin a listing of INI/HAL/ngc files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
-
-[source,{ini}]
----------------------------------------------------------------------
-
-# EMC controller parameters for a simulated machine.
-
-# General note: Comments can either be preceded with a # or ; - either is
-# acceptable, although # is in keeping with most Linux config files.
-
-# General section -------------------------------------------------------------
-[EMC]
-
-# Version of this INI file
-VERSION =               $Revision$
-
-# Name of machine, for use with display, etc.
-MACHINE =               EMC-HAL-SIM-AXIS
-
-# Debug level, 0 means no messages. See src/emc/nml_int/emcglb.h for others
-# DEBUG =               0x7FFFFFFF
-DEBUG = 0
-
-# Sections for display options ------------------------------------------------
-[DISPLAY]
-
-# Name of display program, e.g., axis
-DISPLAY =             axis
-
-# Cycle time, in seconds, that display will sleep between polls
-CYCLE_TIME =            0.100
-
-# Path to help file
-HELP_FILE =             doc/help.txt
-
-# Initial display setting for position, RELATIVE or MACHINE
-POSITION_OFFSET =       RELATIVE
-
-# Initial display setting for position, COMMANDED or ACTUAL
-POSITION_FEEDBACK =     ACTUAL
-
-# Highest value that will be allowed for feed override, 1.0 = 100%
-MAX_FEED_OVERRIDE =     1.2
-MAX_SPINDLE_OVERRIDE =  1.0
-# Prefix to be used
-PROGRAM_PREFIX = ../../nc_files/
-
-# Introductory graphic
-INTRO_GRAPHIC = emc2.gif
-INTRO_TIME = 5
-
-EDITOR = gedit
-
-INCREMENTS = 1 mm, .01 in, .1mm, 1 mil, .1 mil, 1/8000 in
-[FILTER]
-PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image
-PROGRAM_EXTENSION = .py Python Script
-
-png = image-to-gcode
-gif = image-to-gcode
-jpg = image-to-gcode
-py = python
-
-# Task controller section -----------------------------------------------------
-[TASK]
-
-# Name of task controller program, e.g., milltask
-TASK =                  milltask
-
-# Cycle time, in seconds, that task controller will sleep between polls
-CYCLE_TIME =            0.001
-
-# Part program interpreter section --------------------------------------------
-[RS274NGC]
-
-# File containing interpreter variables
-PARAMETER_FILE =        sim_mm.var
-
-# Motion control section ------------------------------------------------------
-[EMCMOT]
-
-EMCMOT =              motmod
-
-# Timeout for comm to emcmot, in seconds
-COMM_TIMEOUT =          1.0
-
-# BASE_PERIOD is unused in this configuration but specified in core_sim.hal
-BASE_PERIOD  =               0
-# Servo task period, in nano-seconds
-SERVO_PERIOD =               1000000
-
-# Hardware Abstraction Layer section --------------------------------------------------
-[HAL]
-
-# The run script first uses halcmd to execute any HALFILE
-# files, and then to execute any individual HALCMD commands.
-#
-
-# list of HAL config files to run through halcmd
-# files are executed in the order in which they appear
-HALFILE =                    core_sim.hal
-HALFILE =		     axis_manualtoolchange.hal
-HALFILE = simulated_home.hal
-#HALFILE = gamepad.hal
-
-# list of halcmd commands to execute
-# commands are executed in the order in which they appear
-#HALCMD =                    save neta
-
-# Single file that is executed after the GUI has started.  Only supported by
-# AXIS at this time (only AXIS creates a HAL component of its own)
-#POSTGUI_HALFILE = test_postgui.hal
-
-HALUI = halui
-
-# Trajectory planner section --------------------------------------------------
-[TRAJ]
-COORDINATES =           X Y Z
-LINEAR_UNITS =          mm
-ANGULAR_UNITS =         degree
-DEFAULT_VELOCITY =      30.48
-MAX_VELOCITY =          53.34
-DEFAULT_ACCELERATION =  508
-MAX_ACCELERATION =      508
-POSITION_FILE = position_mm.txt
-
-# Axes sections ---------------------------------------------------------------
-[AXIS_X]
-MAX_VELOCITY =                  4
-MAX_ACCELERATION =              100.0
-MIN_LIMIT =                     -10.0
-MAX_LIMIT =                     10.0
-
-[AXIS_Y]
-MAX_VELOCITY =                  4
-MAX_ACCELERATION =              100.0
-MIN_LIMIT =                     -10.0
-MAX_LIMIT =                     10.0
-
-[AXIS_Z]
-MAX_VELOCITY =                  4
-MAX_ACCELERATION =              100.0
-MIN_LIMIT =                     -8.0
-MAX_LIMIT =                     0.12
-
-# Joint sections ---------------------------------------------------------------
-
-# First joint
-[JOINT_0]
-TYPE =                          LINEAR
-HOME =                          0.000
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -254
-MAX_LIMIT =                     254
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    0.0
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 1
-HOME_IS_SHARED = 1
-
-# Second joint
-[JOINT_1]
-TYPE =                          LINEAR
-HOME =                          0.000
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -254
-MAX_LIMIT =                     254
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    0.0
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 1
-
-# Third joint
-[JOINT_2]
-TYPE =                          LINEAR
-HOME =                          0.0
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -50.8
-MAX_LIMIT =                     101.6
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    25.4
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 0
-HOME_IS_SHARED = 1
-
-# section for main IO controller parameters -----------------------------------
-[EMCIO]
-# tool table file
-TOOL_TABLE =    sim_mm.tbl
-TOOL_CHANGE_POSITION = 0 0 50.8
----------------------------------------------------------------------
diff --git a/docs/src/source-highlight/ini-test.ini b/docs/src/source-highlight/ini-test.ini
deleted file mode 100644
index e0fef0c4e83..00000000000
--- a/docs/src/source-highlight/ini-test.ini
+++ /dev/null
@@ -1,195 +0,0 @@
-
-# EMC controller parameters for a simulated machine.
-
-# General note: Comments can either be preceded with a # or ; - either is
-# acceptable, although # is in keeping with most Linux config files.
-
-# General section -------------------------------------------------------------
-[EMC]
-
-# Version of this INI file
-VERSION =               $Revision$
-
-# Name of machine, for use with display, etc.
-MACHINE =               EMC-HAL-SIM-AXIS
-
-# Debug level, 0 means no messages. See src/emc/nml_int/emcglb.h for others
-# DEBUG =               0x7FFFFFFF
-DEBUG = 0
-
-# Sections for display options ------------------------------------------------
-[DISPLAY]
-
-# Name of display program, e.g., axis
-DISPLAY =             axis
-
-# Cycle time, in seconds, that display will sleep between polls
-CYCLE_TIME =            0.100
-
-# Path to help file
-HELP_FILE =             doc/help.txt
-
-# Initial display setting for position, RELATIVE or MACHINE
-POSITION_OFFSET =       RELATIVE
-
-# Initial display setting for position, COMMANDED or ACTUAL
-POSITION_FEEDBACK =     ACTUAL
-
-# Highest value that will be allowed for feed override, 1.0 = 100%
-MAX_FEED_OVERRIDE =     1.2
-MAX_SPINDLE_OVERRIDE =  1.0
-# Prefix to be used
-PROGRAM_PREFIX = ../../nc_files/
-
-# Introductory graphic
-INTRO_GRAPHIC = emc2.gif
-INTRO_TIME = 5
-
-EDITOR = gedit
-
-INCREMENTS = 1 mm, .01 in, .1mm, 1 mil, .1 mil, 1/8000 in
-[FILTER]
-PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image
-PROGRAM_EXTENSION = .py Python Script
-
-png = image-to-gcode
-gif = image-to-gcode
-jpg = image-to-gcode
-py = python
-
-# Task controller section -----------------------------------------------------
-[TASK]
-
-# Name of task controller program, e.g., milltask
-TASK =                  milltask
-
-# Cycle time, in seconds, that task controller will sleep between polls
-CYCLE_TIME =            0.001
-
-# Part program interpreter section --------------------------------------------
-[RS274NGC]
-
-# File containing interpreter variables
-PARAMETER_FILE =        sim_mm.var
-
-# Motion control section ------------------------------------------------------
-[EMCMOT]
-
-EMCMOT =              motmod
-
-# Timeout for comm to emcmot, in seconds
-COMM_TIMEOUT =          1.0
-
-# BASE_PERIOD is unused in this configuration but specified in core_sim.hal
-BASE_PERIOD  =               0
-# Servo task period, in nano-seconds
-SERVO_PERIOD =               1000000
-
-# Hardware Abstraction Layer section --------------------------------------------------
-[HAL]
-
-# The run script first uses halcmd to execute any HALFILE
-# files, and then to execute any individual HALCMD commands.
-#
-
-# list of HAL config files to run through halcmd
-# files are executed in the order in which they appear
-HALFILE =                    core_sim.hal
-HALFILE =		     axis_manualtoolchange.hal
-HALFILE = simulated_home.hal
-#HALFILE = gamepad.hal
-
-# list of halcmd commands to execute
-# commands are executed in the order in which they appear
-#HALCMD =                    save neta
-
-# Single file that is executed after the GUI has started.  Only supported by
-# AXIS at this time (only AXIS creates a HAL component of its own)
-#POSTGUI_HALFILE = test_postgui.hal
-
-HALUI = halui
-
-# Trajectory planner section --------------------------------------------------
-[TRAJ]
-
-AXES =                  3
-COORDINATES =           X Y Z
-HOME =                  0 0 0
-LINEAR_UNITS =          mm
-ANGULAR_UNITS =         degree
-DEFAULT_LINEAR_VELOCITY = 30.48
-MAX_LINEAR_VELOCITY = 53.34
-DEFAULT_LINEAR_ACCELERATION = 508
-MAX_LINEAR_ACCELERATION = 508
-POSITION_FILE = position_mm.txt
-
-# Axes sections ---------------------------------------------------------------
-
-# First axis
-[AXIS_0]
-
-TYPE =                          LINEAR
-HOME =                          0.000
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -254
-MAX_LIMIT =                     254
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    0.0
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 1
-
-# Second axis
-[AXIS_1]
-
-TYPE =                          LINEAR
-HOME =                          0.000
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -254
-MAX_LIMIT =                     254
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    0.0
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 1
-
-# Third axis
-[AXIS_2]
-
-TYPE =                          LINEAR
-HOME =                          0.0
-MAX_VELOCITY =                  30.48
-MAX_ACCELERATION =              508
-BACKLASH = 0.000
-INPUT_SCALE =                   157.48
-OUTPUT_SCALE = 1.000
-MIN_LIMIT =                     -50.8
-MAX_LIMIT =                     101.6
-FERROR = 1.27
-MIN_FERROR = .254
-HOME_OFFSET =                    25.4
-HOME_SEARCH_VEL =                127
-HOME_LATCH_VEL =                 25.4
-HOME_USE_INDEX =                 NO
-HOME_IGNORE_LIMITS =             NO
-HOME_SEQUENCE = 0
-
-# section for main IO controller parameters -----------------------------------
-[EMCIO]
-# tool table file
-TOOL_TABLE =    sim_mm.tbl
-TOOL_CHANGE_POSITION = 0 0 50.8
diff --git a/docs/src/source-highlight/ini.lang b/docs/src/source-highlight/ini.lang
deleted file mode 100644
index ce231a51004..00000000000
--- a/docs/src/source-highlight/ini.lang
+++ /dev/null
@@ -1,15 +0,0 @@
-# simpleminded INI filter for source-highlight 2.4
-#
-comment start "#"
-section start '\[.*\]'
-
-
-state keyword start '[^="\[]+' begin
-    function = "="
-    variable = '.+'
-end
-
-
-include "number.lang"
-include "symbols.lang"
-include "c_string.lang"
diff --git a/docs/src/source-highlight/ngc-demo.adoc b/docs/src/source-highlight/ngc-demo.adoc
deleted file mode 100644
index 21466d38e32..00000000000
--- a/docs/src/source-highlight/ngc-demo.adoc
+++ /dev/null
@@ -1,118 +0,0 @@
-:lang: en
-
-= Source Highlight Filter Test
-
-// For now, PDF's can't have highlighted INI, HAL or NGC files.
-// For brave souls: extend /usr/share/texmf-texlive/tex/latex/listings/lstlang1.sty
-// and make it a local copy in the current directory.
-// HTML works fine.
-
-// These attributes must come after the document title, to work around a bug in asciidoc 8.6.6.
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
-// Begin a listing of INI/HAL/NGC files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
-
-Details of the filter can be found in `./doc/source-highlight-filter.txt`.
-
-[source,{ngc}]
----------------------------------------------------------------------
-; G-code highlighting stresstest - useless otherwise
-;
-# = 0
-G0 (Rapid to start) X1 Y1
-G0 X1 Y1 (Rapid to start; but don't forget the coolant)
-M2 ; End of program.
-M66 P1 L3 Q[#]
-M66 P1 L3 Q[# + [#4711]]
-M66 P1 L3 Q#
-M66 P1 L3 Q#3
-M66 P1 L3 Q#5999
-G5  X23.5 a 19.2
-(debug, foo!)
-(Debug, some text and a substitution: #23 and some more thereafter)
-(DEBUG, #<_a_param>)
-(DEBUG, #)
-
-G0 G53 Z0 X[#19]
-G 3 0
-G00
-G01
-G 0 1
-G3 0
-G30
-G53
-G5 3
-G 5 3
-G0
-G1
-;
-; To activate, incantate as follows in the INI file:
-;
-; [RS274NGC]
-; # Remap M6 to a named O-word subroutine.
-; # The tool number currently loaded (in spindle) is passed as parameter #1
-; M6_COMMAND=ocall
-;
-;
-N4711 O sub
-;
-;
-N 0815 # = 0
-# = 0
-# = 0
-
-#4711 = 8.15
-
-; number of seconds to wait for 'tool-changed' equivalent
-# = 9999
-;
-(DEBUG, executing M6 O-word sub, tool=#1)
-;
-O if [#] EQ 0
-    M5
-O endif
-
-O if [#] NE 0
-    G0 G53 Z0
-O endif
-
-O if [#] NE 0
-    G30
-O endif
-
-; Set analog output pin #2 to signal the pocket number.
-; iocontrol.tool-number becomes motion.analog-out-02.
-M68 E2 Q[#1]
-(DEBUG, set current tool number on motion.analog-out-02: #1)
-;
-; Assert the equivalent of the iocontrol.tool-change pin,
-; which is now motion.digital-out-01.
-M64 P1
-(DEBUG, motion.digital-out-01 set high, waiting for motion.digital-in-01)
-;
-; Wait for the equivalent of the iocontrol.tool-changed pin to go high.
-; We use motion.digital-in-01.
-;
-M66 P1 L3 Q#
-;
-O if [#5399] EQ -1
-    (DEBUG, timeout waiting for motion.digital-in-01 to become true: #5399 )
-O else
-    (DEBUG, motion.digital-in-01 became true: #5399)
-O endif
-
-; Retract iocontrol.tool-change equivalent.
-(DEBUG, deasserting motion.digital-out-01)
-;
-M65 P1
-;
-(DEBUG, done with M6 sub)
-;
-O endsub
-m2
----------------------------------------------------------------------
diff --git a/docs/src/source-highlight/ngc-test.ngc b/docs/src/source-highlight/ngc-test.ngc
deleted file mode 100644
index 360e27243d2..00000000000
--- a/docs/src/source-highlight/ngc-test.ngc
+++ /dev/null
@@ -1,94 +0,0 @@
-; G-code highlighting stresstest - useless otherwise
-;
-# = 0
-G0 (Rapid to start) X1 Y1
-G0 X1 Y1 (Rapid to start; but don't forget the coolant)
-M2 ; End of program.
-M66 P1 L3 Q[#]
-M66 P1 L3 Q[# + [#4711]]
-M66 P1 L3 Q#
-M66 P1 L3 Q#3
-M66 P1 L3 Q#5999
-G5  X23.5 a 19.2
-(debug, foo!)
-(Debug, some text and a substitution: #23 and some more thereafter)
-(DEBUG, #<_a_param>)
-(DEBUG, #)
-
-G0 G53 Z0 X[#19]
-G 3 0
-G00
-G01
-G 0 1
-G3 0
-G30
-G53
-G5 3
-G 5 3
-G0
-G1
-;
-; To activate, incantate as follows in the INI file:
-;
-; [RS274NGC]
-; # remap M6 to a named oword subroutine.
-; # the tool number currently loaded (in spindle) is passed as parameter #1
-; M6_COMMAND=ocall
-;
-;
-N4711 O sub
-;
-;
-N 0815 # = 0
-# = 0
-# = 0
-
-#4711 = 8.15
-
-; number of seconds to wait for 'tool-changed' equivalent
-# = 9999
-;
-(DEBUG, executing M6 O-word sub, tool=#1)
-;
-O if [#] EQ 0
-    M5
-O endif
-
-O if [#] NE 0
-    G0 G53 Z0
-O endif
-
-O if [#] NE 0
-    G30
-O endif
-
-; Set analog output pin #2 to signal the pocket number.
-; iocontrol.tool-number becomes motion.analog-out-02.
-M68 E2 Q[#1]
-(DEBUG, set current tool number on motion.analog-out-02: #1)
-;
-; Assert the equivalent of the iocontrol.tool-change pin,
-; which is now motion.digital-out-01.
-M64 P1
-(DEBUG, motion.digital-out-01 set high, waiting for motion.digital-in-01)
-;
-; Wait for the equivalent of the iocontrol.tool-changed pin to go high.
-; We use motion.digital-in-01.
-;
-M66 P1 L3 Q#
-;
-O if [#5399] EQ -1
-    (DEBUG, timeout waiting for motion.digital-in-01 to become true: #5399 )
-O else
-    (DEBUG, motion.digital-in-01 became true: #5399)
-O endif
-
-; Retract iocontrol.tool-change equivalent.
-(DEBUG, deasserting motion.digital-out-01)
-;
-M65 P1
-;
-(DEBUG, done with M6 sub)
-;
-O endsub
-m2
diff --git a/docs/src/source-highlight/ngc.lang b/docs/src/source-highlight/ngc.lang
deleted file mode 100644
index 6fbd5b6cfec..00000000000
--- a/docs/src/source-highlight/ngc.lang
+++ /dev/null
@@ -1,99 +0,0 @@
-# ngc.lang - RS274 G-Code formatting (EMC flavour)
-#
-#  Michael Haberler 3/2011
-#
-#  Originally based on the Highlight-mode file for gedit,
-#  written by Jan Van Gilsen .
-#  Installation instructions can be found at:
-#  http://wiki.linuxcnc.org/cgi-bin/emcinfo.pl?Highlighting_In_Gedit
-#  Version		: 0.3
-#  Last Edit	: 10Th Nov 2007, by Jan Van Gilsen
-#  Comment 	: Added probing and rigid tapping G-codes (new in 2.2)
-#  This file is used for the syntax highlighting in the HTML output of the documentation.
-
-
-environment comment delim '\([dD][eE][bB][uU][gG],' ")" begin
-	variable =  '#([0-9]{4})'
-	variable =  '#[0-9][0-9]?'
-	variable =  '#<([^\>]+)>'
-end
-comment delim "(" ")"
-comment start ";"
-
-ignore = 'axes'
-
-# Numbered parameters (#5xxx)
-variable =  '#([0-9]{4})'
-
-# Function parameter -  #1 .. #30
-variable =  '#[0-9][0-9]?'
-
-# Named parameters
-variable =  '#<([^\>]+)>'
-
-# Math functions and boolean logic
-function = "cos|tan|asin|acos|atan|exp|ln|sqrt|fup|fix|abs|or",
-	"xor|and|mod|gt|lt|ge|le|eq|ne|exists"
-	nonsensitive
-
-# Operators
-function = '(([\/|\=\+\*])|(\])|(\[))'
-
-# Line numbers
-comment = '^[n|N]([ |\t]*[0-9]){1,5}'
-
-# O-word lines and their keywords
-preproc = '[ \t]*[o|O](([ \t]*[0-9])+|<([[:alpha:]]|_)([[:word:]]|\-)+>)[ \t]*',
-	'(sub|endsub|while|endwhile|if|else|endif|do|call|break|continue|return|repeat|endrepeat|elseif)'
-
-# G-codes
-vardef GCODE = '[g|G]([ \t]*[0])*[ \t]*'
-keyword = $GCODE + '1[ \t]*[07-9]'
-keyword = $GCODE + '2[ \t]*[018]'
-keyword = $GCODE + '3[ \t]*[03]'
-keyword = $GCODE + '3[ \t]*3[ \t]*.[ \t]*1'
-keyword = $GCODE + '3[ \t]*8[ \t]*.[ \t]*[2-5]*'
-keyword = $GCODE + '4[ \t]*[1-3][ \t]*.[ \t]*1'
-keyword = $GCODE + '4[ \t]*[0-39]'
-keyword = $GCODE + '5[ \t]*[2-9]'
-keyword = $GCODE + '6[ \t]*[14]'
-keyword = $GCODE + '6[ \t]*.[ \t]*1'
-keyword = $GCODE + '7[ \t]*[013467]'
-keyword = $GCODE + '7[ \t]*.[ \t]*[12]*'
-keyword = $GCODE + '8[ \t]*[0-9]'
-keyword = $GCODE + '9[ \t]*[0-46-9]'
-keyword = $GCODE + '9[ \t]*2[ \t]*.[ \t]*[1-3]'
-keyword = $GCODE + '[0-5|7-8]'
-
-
-# M-Codes
-vardef MCODE = '[m|M]([ \t]*[0])*[ \t]*'
-keyword = $MCODE + '1[ \t]*[0-9][ \t]*[1-9]'
-keyword = $MCODE + '1[ \t]*[1-9][ \t]*0'
-keyword = $MCODE + '3[ \t]*0'
-keyword = $MCODE + '5[ \t]*[0-3]'
-keyword = $MCODE + '6[ \t]*0'
-keyword = $MCODE + '6[ \t]*[0-9]'
-keyword = $MCODE + '7[ \t]*[0-3]'
-keyword = $MCODE + '9[ \t]*[8-9]'
-keyword = $MCODE + '[0-9]'
-
-# Feeds & speeds
-keyword = '[f|F|s|S]([ \t]*[0-9])*[ \t]*[.]?([ \t]*[0-9])*'
-
-# T, H
-keyword = '[t|T|h|H]([ \t]*[0-9])*'
-
-# Coordinates & arguments; trailing number/expression/params formatted separately
-atom = '[x|X|y|Y|z|Z|a|A|b|B|c|C|e|E|u|U|v|V|w|W|h|H|i|I|j|J|k|K|p|P|q|Q|r|R|l|L](\s*)?'
-
-
-#    * A number consists of (1) an optional plus or minus sign,
-#	followed by (2) zero to many digits, followed, possibly,
-#	by (3) one decimal point,
-#	followed by (4) zero to many digits - provided that there is at least one digit somewhere in the number.
-#
-#    * There are two kinds of numbers: integers and decimals. An integer does not have a decimal point in it; a decimal does.
-#    * Numbers may have any number of digits, subject to the limitation on line length. Only about seventeen significant figures will be retained, however (enough for all known applications).
-#    * A non-zero number with no sign as the first character is assumed to be positive.
-number = '[+-]?([[:digit:]]*\.)?[[:digit:]]+'
diff --git a/docs/src/xhtml11-head-foot.conf b/docs/src/xhtml11-head-foot.conf
deleted file mode 100644
index 4d102198e77..00000000000
--- a/docs/src/xhtml11-head-foot.conf
+++ /dev/null
@@ -1,156 +0,0 @@
-#
-# xhtml11-head-foot.conf
-#
-# Redefinition of man-page header and footer html
-#
-# From: xhtml11.conf
-# Asciidoc configuration file.
-# xhtml11 backend, generates XHTML 1.1 conformant markup.
-#
-
-[header]
-
-
-
-
-
-
-{title}
-{title%}{doctitle=}
-ifdef::linkcss[]
-
-ifdef::quirks[]
-
-endif::quirks[]
-ifeval::["{source-highlighter}"=="pygments"]
-
-endif::[]
-
-# DEPRECATED: 'pygments' attribute.
-ifdef::pygments[]
-
-ifdef::toc2[]
-
-endif::linkcss[]
-ifndef::linkcss[]
-
-endif::linkcss[]
-ifndef::disable-javascript[]
-ifdef::linkcss[]
-
-
-
-endif::linkcss[]
-ifndef::linkcss[]
-
-endif::linkcss[]
-endif::disable-javascript[]
-ifdef::asciimath[]
-ifdef::linkcss[]
-
-endif::linkcss[]
-ifndef::linkcss[]
-
-endif::linkcss[]
-endif::asciimath[]
-ifdef::latexmath[]
-ifdef::linkcss[]
-
-endif::linkcss[]
-ifndef::linkcss[]
-
-endif::linkcss[]
-endif::latexmath[]
-ifdef::mathjax[]
-
-
-endif::mathjax[]
-{docinfo1,docinfo2#}{include:{docdir}/docinfo.html}
-{docinfo,docinfo2#}{include:{docdir}/{docname}-docinfo.html}
-template::[docinfo]
-
-
-# Article, book header.
-ifndef::doctype-manpage[]
-
-endif::doctype-manpage[]
-# Man page header.
-ifdef::doctype-manpage[]
-
-endif::doctype-manpage[]
-

-
-[footer]
-

-{disable-javascript%
}
-
-
-
diff --git a/docs/src/xhtml11-latexmath.conf b/docs/src/xhtml11-latexmath.conf
deleted file mode 100644
index 48d2a191084..00000000000
--- a/docs/src/xhtml11-latexmath.conf
+++ /dev/null
@@ -1,14 +0,0 @@
-# Cover latexmath in elements with specific class names
-[latexmath-inlinemacro]
-
-{passtext}
-
-
-[latexmath-blockmacro]
-

-

-
{title}

-

-{passtext}
-

-

diff --git a/docs/src/xhtml11-links.conf b/docs/src/xhtml11-links.conf
deleted file mode 100644
index 516e6b66958..00000000000
--- a/docs/src/xhtml11-links.conf
+++ /dev/null
@@ -1,6 +0,0 @@
-# xref:id[text]
-[xref-inlinemacro]
-{0=[{target}]}
-# <>
-[xref2-inlinemacro]
-{2=[{1}]}
diff --git a/docs/src/xhtml11.conf b/docs/src/xhtml11.conf
deleted file mode 100644
index 6e8a5315352..00000000000
--- a/docs/src/xhtml11.conf
+++ /dev/null
@@ -1,27 +0,0 @@
-include::attribute-colon.conf[]
-include::xhtml11-links.conf[]
-include::xhtml11-latexmath.conf[]
-
-[table]
-

-
-
-{colspecs}
-{headrows#}
-{headrows}
-{headrows#}
-{footrows#}
-{footrows}
-{footrows#}
-
-{bodyrows}
-
-
{caption={table-caption} {counter:table-number}. }{title}

-

diff --git a/scripts/inkscape b/scripts/inkscape
deleted file mode 100755
index 44cdc1c119c..00000000000
--- a/scripts/inkscape
+++ /dev/null
@@ -1,96 +0,0 @@
-#!/bin/bash
-# Shim that intercepts the inkscape calls made by dblatex during the
-# LinuxCNC docs build and forwards them to rsvg-convert. Avoids the noisy
-# Pango/GtkRecentManager warnings that headless Inkscape prints on every
-# SVG conversion (see issue #4040). Handles both dblatex syntaxes:
-#   new (Inkscape 1.x): inkscape -D --export-filename=OUT IN
-#   old (Inkscape 0.x): inkscape -z -D --export-png=OUT IN
-#                       (also --export-pdf=, --export-eps=)
-# Falls back to the real inkscape whenever the args do not match the
-# expected pattern, when rsvg-convert is missing, or when
-# LINUXCNC_DOCS_NO_RSVG is set.
-
-set -u
-
-real_inkscape() {
-    # Find the next `inkscape` on PATH after stripping the directory holding
-    # this shim, so we do not recurse into ourselves.
-    local self_dir
-    self_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
-    local stripped_path
-    stripped_path=$(printf '%s' "$PATH" | tr ':' '\n' \
-        | grep -vxF "$self_dir" | paste -sd:)
-    PATH="$stripped_path" exec inkscape "$@"
-}
-
-# Escape hatch.
-if [ -n "${LINUXCNC_DOCS_NO_RSVG:-}" ]; then
-    real_inkscape "$@"
-fi
-
-# rsvg-convert must be available.
-if ! command -v rsvg-convert >/dev/null 2>&1; then
-    real_inkscape "$@"
-fi
-
-# Parse the dblatex call pattern. Accepted flags:
-#   -D, -d, -z, --without-gui   (ignored: pose/area/legacy GUI suppression)
-#   --export-filename=OUT       (Inkscape 1.x)
-#   --export-png=OUT            (Inkscape 0.x)
-#   --export-pdf=OUT            (Inkscape 0.x)
-#   --export-eps=OUT            (Inkscape 0.x)
-# One positional input. Anything else falls through to real inkscape.
-out=""
-in=""
-fmt=""
-saw_unknown=0
-for arg in "$@"; do
-    case "$arg" in
-        -D|-d|-z|--without-gui)
-            ;;
-        --export-filename=*)
-            out="${arg#--export-filename=}"
-            ;;
-        --export-png=*)
-            out="${arg#--export-png=}"
-            fmt=png
-            ;;
-        --export-pdf=*)
-            out="${arg#--export-pdf=}"
-            fmt=pdf
-            ;;
-        --export-eps=*)
-            out="${arg#--export-eps=}"
-            fmt=eps
-            ;;
-        -*)
-            saw_unknown=1
-            ;;
-        *)
-            if [ -n "$in" ]; then
-                saw_unknown=1
-            else
-                in="$arg"
-            fi
-            ;;
-    esac
-done
-
-if [ "$saw_unknown" = 1 ] || [ -z "$in" ] || [ -z "$out" ]; then
-    real_inkscape "$@"
-fi
-
-# If format not yet set (new-syntax --export-filename), infer from extension.
-if [ -z "$fmt" ]; then
-    case "$out" in
-        *.pdf) fmt=pdf ;;
-        *.png) fmt=png ;;
-        *.eps) fmt=eps ;;
-        *.svg) fmt=svg ;;
-        *)     real_inkscape "$@" ;;
-    esac
-fi
-
-if ! rsvg-convert -f "$fmt" -o "$out" "$in"; then
-    real_inkscape "$@"
-fi
diff --git a/src/Makefile.inc.in b/src/Makefile.inc.in
index 223062d996a..848adcbd285 100644
--- a/src/Makefile.inc.in
+++ b/src/Makefile.inc.in
@@ -127,10 +127,11 @@ BUILD_DOCS = @BUILD_DOCS@
 BUILD_DOCS_PDF = @BUILD_DOCS_PDF@
 BUILD_DOCS_HTML = @BUILD_DOCS_HTML@
 BUILD_DOCS_TRANSLATED = @BUILD_DOCS_TRANSLATED@
+NOTOCJK_REGULAR_TTC = @NOTOCJK_REGULAR_TTC@
+NOTOCJK_BOLD_TTC = @NOTOCJK_BOLD_TTC@
 PYTHON = @PYTHON@
 TCLSH = @TCLSH@
 EMC2_TCL_LIB_DIR = @EMC2_TCL_LIB_DIR@
-A2X_LATEX_ENCODING = @A2X_LATEX_ENCODING@
 
 HAVE_LIBMODBUS3   = @HAVE_LIBMODBUS3@
 LIBMODBUS_LIBS    = @LIBMODBUS_LIBS@

From a15ea32857c64076654ff00f11fed63a7114c641 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:24:37 +0800
Subject: [PATCH 07/10] docs: source content fixes for asciidoctor parser

Adjust .adoc sources where asciidoctor's parser is stricter than the
legacy asciidoc-py, where INI/HAL/NGC examples were malformed enough
that the new Rouge highlighters exposed the breakage, or where blank
lines were missing before * bullet lists (asciidoctor requires them).

Touches docs/src/{code,config,drivers,examples,gcode,gui,hal,ladder,
lathe,motion,plasma,remap,tooldatabase,user}/*.adoc, docs/src/man/man9
manpage sources, docs/help/tklinuxcnc.adoc, and a table cell merge
fix in src/hal/components/lut5.comp.  Also a small per-language
asset swap (control-point_es.svg).
---
 docs/help/tklinuxcnc.adoc                     |   9 +-
 docs/src/code/building-linuxcnc.adoc          |  40 ++--
 docs/src/code/code-notes.adoc                 |   5 -
 docs/src/code/contributing-to-linuxcnc.adoc   |   5 -
 docs/src/code/rs274.adoc                      |   8 +-
 docs/src/config/core-components.adoc          |  10 +-
 docs/src/config/ini-config.adoc               |  53 +++--
 docs/src/config/ini-homing.adoc               |  17 +-
 docs/src/config/lathe-config.adoc             |  35 ++-
 docs/src/config/moveoff.adoc                  |  22 +-
 docs/src/config/python-hal-interface.adoc     |   4 -
 docs/src/config/python-interface.adoc         |   4 -
 docs/src/config/stepper-diagnostics.adoc      |   8 +-
 docs/src/config/stepper.adoc                  |  17 +-
 docs/src/drivers/ax5214h.adoc                 |   8 +-
 docs/src/drivers/gm.adoc                      |  16 +-
 docs/src/drivers/gs2.adoc                     |   8 +-
 docs/src/drivers/hostmot2.adoc                |  15 +-
 docs/src/drivers/mb2hal.adoc                  |   7 +-
 docs/src/drivers/mitsub-vfd.adoc              |  12 +-
 docs/src/drivers/motenc.adoc                  |   8 +-
 docs/src/drivers/opto22.adoc                  |  10 +-
 docs/src/drivers/pico-ppmc.adoc               |   8 +-
 docs/src/drivers/pmx485.adoc                  |   8 +-
 docs/src/drivers/servo-to-go.adoc             |  12 +-
 docs/src/drivers/vfs11.adoc                   |  18 +-
 docs/src/examples/gs2-example.adoc            |   7 +-
 docs/src/examples/mpg.adoc                    |  10 +-
 docs/src/examples/pci-parallel-port.adoc      |  12 +-
 docs/src/examples/spindle.adoc                |  22 +-
 docs/src/gcode/coordinates.adoc               |  17 +-
 docs/src/gcode/g-code.adoc                    | 195 +++++++++--------
 docs/src/gcode/m-code.adoc                    |  29 ++-
 docs/src/gcode/machining-center.adoc          |  12 +-
 docs/src/gcode/o-code.adoc                    |  45 ++--
 docs/src/gcode/overview.adoc                  |  42 ++--
 docs/src/gcode/rs274ngc.adoc                  |   7 +-
 docs/src/gcode/tool-compensation.adoc         |   8 +-
 .../src/getting-started/getting-linuxcnc.adoc |  20 +-
 .../getting-started/hardware-interface.adoc   |   4 +-
 .../getting-started/updating-linuxcnc.adoc    |   6 -
 docs/src/gui/axis.adoc                        |  18 +-
 docs/src/gui/filter-programs.adoc             |  12 +-
 docs/src/gui/gladevcp-libraries.adoc          |   8 +-
 docs/src/gui/gladevcp-panels.adoc             |  14 +-
 docs/src/gui/gladevcp.adoc                    |  18 +-
 docs/src/gui/gmoccapy.adoc                    |  86 ++++----
 docs/src/gui/gscreen.adoc                     |   9 +-
 docs/src/gui/gui-dev-reference.adoc           |  37 ++--
 docs/src/gui/halui.adoc                       |  15 +-
 docs/src/gui/image-to-gcode.adoc              |   8 +-
 docs/src/gui/mdro.adoc                        |   5 -
 docs/src/gui/ngcgui.adoc                      |  34 ++-
 docs/src/gui/panelui.adoc                     |  21 +-
 docs/src/gui/pyvcp-examples.adoc              |  17 +-
 docs/src/gui/pyvcp.adoc                       |  25 +--
 docs/src/gui/qtdragon.adoc                    | 125 ++++++-----
 docs/src/gui/qtvcp-code-snippets.adoc         |   2 +-
 docs/src/gui/qtvcp-custom-widgets.adoc        |   4 +-
 docs/src/gui/qtvcp-libraries.adoc             |  14 +-
 docs/src/gui/qtvcp-vcp-panels.adoc            |  48 ++---
 docs/src/gui/qtvcp-vismach.adoc               |   2 +-
 docs/src/gui/qtvcp-widgets.adoc               | 118 +++++-----
 docs/src/gui/qtvcp.adoc                       |  23 +-
 docs/src/gui/tklinuxcnc.adoc                  |   7 +-
 docs/src/gui/tooledit.adoc                    |  13 +-
 docs/src/gui/touchy.adoc                      |   8 +-
 docs/src/hal/basic-hal.adoc                   |  36 ++--
 docs/src/hal/comp.adoc                        |  10 +-
 docs/src/hal/hal-examples.adoc                |  20 +-
 docs/src/hal/halmodule.adoc                   |   2 +-
 docs/src/hal/halshow.adoc                     |  16 +-
 docs/src/hal/haltcl.adoc                      |  26 +--
 docs/src/hal/halui-examples.adoc              |  14 +-
 docs/src/hal/intro.adoc                       |   8 +-
 docs/src/hal/parallel-port.adoc               |  22 +-
 docs/src/hal/tools.adoc                       |  12 +-
 docs/src/hal/twopass.adoc                     |  25 +--
 docs/src/ladder/classic-ladder.adoc           |  24 +--
 docs/src/ladder/ladder-examples.adoc          |  13 +-
 docs/src/lathe/images/control-point_es.svg    |  19 +-
 docs/src/lathe/lathe-user.adoc                |  10 +-
 docs/src/man/man9/hm2_7i43.9.adoc             |   2 +-
 docs/src/man/man9/hm2_rpspi.9.adoc            |   2 +-
 docs/src/motion/5-axis-kinematics.adoc        |  16 +-
 docs/src/motion/external-offsets.adoc         |  13 +-
 docs/src/motion/switchkins.adoc               |  21 +-
 docs/src/plasma/plasma-cnc-primer.adoc        |  22 +-
 docs/src/plasma/qtplasmac.adoc                | 201 +++++++++---------
 docs/src/remap/remap.adoc                     |  49 ++---
 docs/src/tooldatabase/tooldatabase.adoc       |   8 +-
 docs/src/user/user-concepts.adoc              |   8 +-
 src/hal/components/lut5.comp                  |   2 +-
 93 files changed, 821 insertions(+), 1274 deletions(-)

diff --git a/docs/help/tklinuxcnc.adoc b/docs/help/tklinuxcnc.adoc
index 13dba0d220e..86170289922 100644
--- a/docs/help/tklinuxcnc.adoc
+++ b/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
diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc
index e14139853d6..c5dbd87c433 100644
--- a/docs/src/code/building-linuxcnc.adoc
+++ b/docs/src/code/building-linuxcnc.adoc
@@ -95,10 +95,10 @@ $ sudo make setuid
 
 After you have successfully built LinuxCNC it is time to run the tests:
 
------
+----
 $ source ../scripts/rip-environment
 $ runtests
------
+----
 
 This might fail, too!
 Read this whole document, especially the section on <>.
@@ -138,9 +138,9 @@ Non-realtime::
   (such as the user interfaces, and some kinds of components and device drivers). +
   To make use of the realtime capabilities of LinuxCNC, certain parts of LinuxCNC need to run with root privileges.
   To enable root for these parts, run this extra command after the `make` that builds LinuxCNC:
------
+----
 $ sudo make setuid
------
+----
 
 == Build modes
 
@@ -344,10 +344,10 @@ You can use this meta-data to easily list the required packages missing from you
 First, go to the source tree of LinuxCNC and initiate its default self-configuration,
 if not already performed:
 
------
+----
 $ cd linuxcnc-dev
 $ ./debian/configure
------
+----
 
 This will prepare the file debian/control that contains lists of Debian packages
 to create with the runtime dependencies for those packages and for our cause also
@@ -474,26 +474,26 @@ When using the RTAI realtime platform it does not have enough privilege, and the
 
 If LinuxCNC displays the following message on startup, the problem is your system's configured limit on locked memory:
 
------
+----
 RTAPI: ERROR: failed to map shmem
 RTAPI: Locked memory limit is 32KiB, recommended at least 20480KiB.
------
+----
 
 To fix this problem, add a file named
 `/etc/security/limits.d/linuxcnc.conf` (as root) with your favorite
 text editor (e.g., `sudo gedit /etc/security/limits.d/linuxcnc.conf`).
 The file should contain the following line:
 
------
+----
 * - memlock 20480
------
+----
 
 Log out and log back in to make the changes take effect.
 Verify that the memory lock limit is raised using the following command:
 
------
+----
 $ ulimit -l
------
+----
 
 == Building on Gentoo
 
@@ -501,45 +501,45 @@ Building on Gentoo is possible, but not supported.  Be sure you are
 running a desktop profile.  This project uses the Tk Widget Set, asciidoc,
 and has some other dependencies.  They should be installed as root:
 
------
+----
 ~ # euse -E tk imagequant
 ~ # emerge -uDNa world
 ~ # emerge -a dev-libs/libmodbus dev-lang/tk dev-tcltk/bwidget dev-tcltk/tclx
 ~ # emerge -a dev-python/pygobject dev-python/pyopengl dev-python/numpy
 ~ # emerge -a app-text/asciidoc app-shells/bash-completion
------
+----
 
 You can switch back to being a normal user for most of the rest of the
 install.  As that user, create a virtual environment for pip, then install
 the pip packages:
 
------
+----
 ~/src $ python -m venv   --system-site-packages ~/src/venv
 ~/src $ . ~/src/venv/bin/activate
 (venv) ~/src $ pip install yapps2
 (venv) ~/src $
------
+----
 
 Then you can contrinue as normally:
 
------
+----
 (venv) ~/src $ git clone https://github.com/LinuxCNC/linuxcnc.git
 (venv) ~/src $ cd linuxcnc
 (venv) ~/src $ cd src
 (venv) ~/src $ ./autogen.sh
 (venv) ~/src $ ./configure --enable-non-distributable=yes
 (venv) ~/src $ make
------
+----
 
 There is no need to run "make suid", just make sure your user is in
 the "dialout" group.  To start linuxcnc, you must be in the Python
 Virtual Environment, and set up the linuxcnc environment:
 
------
+----
 ~ $ . ~/src/venv/bin/activate
 (venv) ~ $ . ~/src/linuxcnc/scripts/rip-environment
 (venv) ~ $ ~/src/linuxcnc $ scripts/linuxcnc
------
+----
 
 
 == Options for checking out the git repo
diff --git a/docs/src/code/code-notes.adoc b/docs/src/code/code-notes.adoc
index 89b8dea799a..8c62a8cd09b 100644
--- a/docs/src/code/code-notes.adoc
+++ b/docs/src/code/code-notes.adoc
@@ -4,11 +4,6 @@
 [[cha:code-notes]]
 = Code Notes
 
-// 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}
 
 == Intended audience
 
diff --git a/docs/src/code/contributing-to-linuxcnc.adoc b/docs/src/code/contributing-to-linuxcnc.adoc
index 9626599abab..85e32473be4 100644
--- a/docs/src/code/contributing-to-linuxcnc.adoc
+++ b/docs/src/code/contributing-to-linuxcnc.adoc
@@ -3,11 +3,6 @@
 
 = Contributing to LinuxCNC
 
-// 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}
 
 == Introduction
 
diff --git a/docs/src/code/rs274.adoc b/docs/src/code/rs274.adoc
index 44c88bc6d15..704d84a807d 100644
--- a/docs/src/code/rs274.adoc
+++ b/docs/src/code/rs274.adoc
@@ -4,12 +4,6 @@
 [[cha:rs274]]
 = Stand Alone Interpreter
 
-// 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}
-
 The rs274 stand alone interpreter is available for use via the command line.
 
 == Usage
@@ -40,7 +34,7 @@ and see that the loop never ends. To break out of the loop use Ctrl Z. The
 following two files are needed to run the example.
 
 .test.ngc
-[source,{ngc}]
+[source,ngc]
 ----
 # = 123.352
 
diff --git a/docs/src/config/core-components.adoc b/docs/src/config/core-components.adoc
index b139f284833..e2bc75717a7 100644
--- a/docs/src/config/core-components.adoc
+++ b/docs/src/config/core-components.adoc
@@ -4,12 +4,6 @@
 [[cha:core-components]]
 = Core Components
 
-// 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}
-
 (((Core components)))
 See also the man pages 'motion(9)'.
 
@@ -35,7 +29,7 @@ updated by the motion-controller function.
 Motion is loaded with the motmod command. A kins should be loaded before
 motion.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt motmod base_period_nsec=['period'] servo_period_nsec=['period']
               traj_period_nsec=['period'] num_joints=['0-9']
@@ -89,7 +83,7 @@ as a locking indexer (typically a rotary).  The mask bits select the
 joint(s).  The LSB of the mask selects joint 0.
 Example:
 
-[source,{hal}]
+[source,hal]
 ----
 unlock_joints_mask=0x38 selects joints 3,4,5
 ----
diff --git a/docs/src/config/ini-config.adoc b/docs/src/config/ini-config.adoc
index 8a2f548e8b8..3260e118d59 100644
--- a/docs/src/config/ini-config.adoc
+++ b/docs/src/config/ini-config.adoc
@@ -4,11 +4,6 @@
 [[cha:ini-configuration]]
 = INI Configuration(((INI Configuration)))
 
-// 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}
 
 == The INI File Components(((INI File,Components)))
 
@@ -27,7 +22,7 @@ A comment line is started with a ; or a # mark.
 When the INI reader sees either of these marks on a line, the rest of the line is ignored by the software.
 Comments can be used to describe what an INI element will do.
 
-[source,{ini}]
+[source,ini]
 ----
 ; This is my mill configuration file.
 # I set it up on January 12, 2012
@@ -36,7 +31,7 @@ Comments can be used to describe what an INI element will do.
 Comments can also be used to 'turn off' a variable.
 This makes it easier to pick between different variables.
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = axis
 # DISPLAY = touchy
@@ -46,7 +41,7 @@ In this list, the DISPLAY variable will be set to axis because the other one is
 If someone carelessly edits a list like this and leaves two of the lines uncommented, the first one encountered will be used.
 
 Note that inside a variable's value, the "#" and ";" characters are part of the value:
-[source,{ini}]
+[source,ini]
 ----
 # Below does not result in INCORRECT=value
 # because comments are not interpreted as comments in values
@@ -93,7 +88,7 @@ Additionally, variable identifiers cannot start with a digit.
 White space at the beginning of the line and after the variable identifier, up to the equals sign, is ignored.
 
 .Variable Example
-[source,{ini}]
+[source,ini]
 ----
 MACHINE = My Machine
 ----
@@ -104,7 +99,7 @@ There may be white space following the trailing backslash character, but this is
 Section identifiers may not be extended to multiple lines.
 
 .Variable with Line extends Example
-[source,{ini}]
+[source,ini]
 ----
 APP = sim_pin \
 ini.0.max_acceleration \
@@ -137,7 +132,7 @@ Spaces inside a value are automatically part of the value.
 Tabs and newlines can be added using `\t` and `\n`.
 
 .Value Escape Example
-[source,{ini}]
+[source,ini]
 ----
 STRING = Hello World!
 
@@ -202,18 +197,18 @@ Most sample configurations use custom sections and variables to put all of the s
 To add a custom variable to an existing LinuxCNC section, simply include the variable in that section.
 
 .Custom Variable Example, assigning the value 'LINEAR' to the variable 'TYPE', and the value '16000' to the variable 'SCALE'.
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]
 TYPE = LINEAR
-...
+# ...
 SCALE = 16000
 ----
 
 To introduce a custom section with its own variables, add the section and variables to the INI file.
 
 .Custom Section Example
-[source,{ini}]
+[source,ini]
 ----
 [PROBE]
 Z_FEEDRATE = 50
@@ -224,7 +219,7 @@ Z_SAFE_DISTANCE = -10
 To use the custom variables in your HAL file, put the section and variable name in place of the value.
 
 .HAL Example
-[source,{hal}]
+[source,hal]
 ----
 setp offset.1.offset [PROBE]Z_OFFSET
 setp stepgen.0.position-scale [JOINT_0]SCALE
@@ -240,7 +235,7 @@ Please note that G-code embedded ini variables are converted to upper case befor
 The `#<_ini[section]variable>` should be called [SECTION]VARIABLE in the INI file.
 
 .G-code Example
-[source,{ngc}]
+[source,ngc]
 ----
 G91
 G38.2 Z#<_ini[probe]z_safe_distance> F#<_ini[probe]z_feedrate>
@@ -256,7 +251,7 @@ An INI file may include the contents of another file by using a `#INCLUDE` direc
 The `#INCLUDE` directive must be in upper case, start in the first column of the line and have at least one space after it.
 
 .#INCLUDE Format
-[source,{ini}]
+[source,ini]
 ----
 #INCLUDE filename
 ----
@@ -271,7 +266,7 @@ The filename can be specified as:
 Multiple `#INCLUDE` directives are supported.
 
 .#INCLUDE Examples
-[source,{ini}]
+[source,ini]
 ----
 #INCLUDE joint_0.inc
 #INCLUDE ../parallel/joint_1.inc
@@ -498,14 +493,14 @@ This output is what will be displayed in the text area, previewed in the display
 
 If your post processor outputs files in all caps you might want to add the following line:
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .NGC XYZ Post Processor
 ----
 
 The following lines add support for the image-to-G-code converter included with LinuxCNC.
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .png,.gif,.jpg # Greyscale Depth Image
   png = image-to-gcode
@@ -515,7 +510,7 @@ PROGRAM_EXTENSION = .png,.gif,.jpg # Greyscale Depth Image
 
 An example of a custom G-code converter located in the linuxcnc directory.
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .gcode 3D Printer
   gcode = /home/mill/linuxcnc/convert.py
@@ -525,7 +520,7 @@ NOTE: The program file associated with an extension must have either the full pa
 
 It is also possible to specify an interpreter:
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .py Python Script
   py = python
@@ -747,7 +742,7 @@ Omission of required addf statements is almost always an error.
 Signals usually include one or more input connections and a single output (but both are not strictly required).
 A system library file is provided to make checks for these conditions and report to stdout and in a pop-up GUI:
 
-[source,{ini}]
+[source,ini]
 ----
 HALFILE = LIB:halcheck.tcl [nopopup]
 ----
@@ -806,26 +801,26 @@ The applications can be started after a specified delay to allow for GUI-depende
   Examples:
 ** Simulate inputs to HAL pins for testing (using sim_pin -- a simple GUI to set inputs to parameters, unconnected pins, or signals with no writers):
 
-[source,{ini}]
+[source,ini]
 ----
 APP = sim_pin motion.probe-input halui.abort motion.analog-in-00
 ----
 ** Invoke halshow with a previuosly saved watchlist.
    Since LinuxCNC sets the working directory to the directory for the INI file, you can refer to files in that directory (example: my.halshow):
 
-[source,{ini}]
+[source,ini]
 ----
 APP = halshow my.halshow
 ----
 ** Alternatively, a watchlist file identified with a full pathname could be specified:
 
-[source,{ini}]
+[source,ini]
 ----
 APP = halshow ~/saved_shows/spindle.halshow
 ----
 ** Open halscope using a previously saved configuration:
 
-[source,{ini}]
+[source,ini]
 ----
 APP = halscope -i my.halscope
 ----
@@ -1027,7 +1022,7 @@ The __ specifies one of: X Y Z A B C U V W
   Moving with other joints is not allowed when moving a locked rotary joint.
   To create the unlock pins, use the motmod parameter:
 +
-[source,{ini}]
+[source,ini]
 ----
 unlock_joints_mask=jointmask
 ----
@@ -1038,7 +1033,7 @@ Example: `loadrt motmod ... unlock_joints_mask=0x38` creates unlock-pins for joi
 
 * `OFFSET_AV_RATIO = 0.1` - (real) If nonzero, this item enables the use of HAL input pins for external axis offsets:
 +
-[source,{ini}]
+[source,hal]
 ----
 axis..eoffset-enable
 axis..eoffset-count
diff --git a/docs/src/config/ini-homing.adoc b/docs/src/config/ini-homing.adoc
index cfe03d3a361..7f99d8552de 100644
--- a/docs/src/config/ini-homing.adoc
+++ b/docs/src/config/ini-homing.adoc
@@ -4,11 +4,6 @@
 [[cha:homing-configuration]]
 = Homing Configuration
 
-// 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}
 
 == Overview
 
@@ -274,7 +269,7 @@ Examples for a 3 joint system
 
 Two sequences (0,1), no synchronization
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]HOME_SEQUENCE = 0
 [JOINT_1]HOME_SEQUENCE = 1
@@ -283,7 +278,7 @@ Two sequences (0,1), no synchronization
 
 Two sequences, joints 1 and 2 synchronized
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]HOME_SEQUENCE =  0
 [JOINT_1]HOME_SEQUENCE = -1
@@ -292,7 +287,7 @@ Two sequences, joints 1 and 2 synchronized
 
 With mixed positive and negative values, joints 1 and 2 synchronized
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]HOME_SEQUENCE =  0
 [JOINT_1]HOME_SEQUENCE = -1
@@ -301,7 +296,7 @@ With mixed positive and negative values, joints 1 and 2 synchronized
 
 One sequence, no synchronization
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]HOME_SEQUENCE =  0
 [JOINT_1]HOME_SEQUENCE =  0
@@ -310,7 +305,7 @@ One sequence, no synchronization
 
 One sequence, all joints synchronized
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]HOME_SEQUENCE = -1
 [JOINT_1]HOME_SEQUENCE = -1
@@ -360,7 +355,7 @@ This logic should also assert the *motion.homing-inhibit* pin to ensure that hom
 
 Example: Synced joints 0,1 using negative sequence (-1) for synchronized homing with a switch (allow_jjog) that selects a positive sequence (1) for individual *joint* jogging prior to homing (partial HAL code):
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt mux2           names=home_sequence_mux
 loadrt conv_float_s32 names=home_sequence_s32
diff --git a/docs/src/config/lathe-config.adoc b/docs/src/config/lathe-config.adoc
index 7e12544f033..f02b613a18c 100644
--- a/docs/src/config/lathe-config.adoc
+++ b/docs/src/config/lathe-config.adoc
@@ -4,11 +4,6 @@
 [[cha:lathe-configuration]]
 = Lathe Configuration
 
-// 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}
 
 == Default Plane
 
@@ -17,7 +12,7 @@ That is why the default plane is XY (G17). A normal lathe only uses the
 XZ plane (G18). To change the default plane place the following line in
 the INI file in the RS274NGC section.
 
-[source,{ini}]
+[source,ini]
 ----
 RS274NGC_STARTUP_CODE = G18
 ----
@@ -36,12 +31,12 @@ historical settings.
 GMOCCAPY also uses the mentioned settings, but does offer additional settings,
 check the <> section for details.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = axis
 LATHE = 1
-...
+# ...
 
 [KINS]
 KINEMATICS = trivkins
@@ -49,27 +44,27 @@ JOINTS = 3
 
 [TRAJ]
 COORDINATES = X Z
-...
+# ...
 
 [JOINT_0]
-...
+# ...
 [JOINT_2]
-...
+# ...
 [AXIS_X]
-...
+# ...
 [AXIS_Z]
-...
+# ...
 ----
 
 With joints_axes incorporation, a simpler configuration can be made with just
 the two required joints by specifying trivkins with the 'coordinates=' parameter:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = axis
 LATHE = 1
-...
+# ...
 
 [KINS]
 KINEMATICS = trivkins coordinates=xz
@@ -77,16 +72,16 @@ JOINTS = 2
 
 [TRAJ]
 COORDINATES = X Z
-...
+# ...
 
 [JOINT_0]
-...
+# ...
 [JOINT_1]
-...
+# ...
 [AXIS_X]
-...
+# ...
 [AXIS_Z]
-...
+# ...
 ----
 
 // vim: set syntax=asciidoc:
diff --git a/docs/src/config/moveoff.adoc b/docs/src/config/moveoff.adoc
index 45d75365af6..81e1bb7d605 100644
--- a/docs/src/config/moveoff.adoc
+++ b/docs/src/config/moveoff.adoc
@@ -4,12 +4,6 @@
 [[cha:moveoff]]
 = Moveoff Component
 
-// 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}
-
 The moveoff HAL component is a HAL-only method for implementing offsets.
 See the manpage ('$ man moveoff') for the IMPORTANT limitations and warnings.
 
@@ -127,12 +121,12 @@ for HAL files that connect the pins for `joint.N.motor-pos-cmd`,
 `joint.N.motor-pos-fb`, and any components connected to these pins
 (pid and encoder components in a servo system for instance).
 
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 HALUI   = halui
 HALFILE = existing_configuration_halfile_1
-...
+# ...
 HALFILE = existing_configuration_halfile_n
 HALFILE = LIB:hookup_moveoff.tcl
 ----
@@ -145,7 +139,7 @@ used, if no entry is found, then the moveoff component default will be used).
 Using component defaults or [AXIS_n] section values for per-axis offset
 settings is NOT recommended.
 
-[source,{ini}]
+[source,ini]
 ----
 [MOVEOFF_n]
 MAX_LIMIT =
@@ -156,7 +150,7 @@ MAX_ACCELERATION =
 
 Add INI file entries for moveoff component settings (omit to use moveoff defaults):
 
-[source,{ini}]
+[source,ini]
 ----
 [MOVEOFF]
 EPSILON =
@@ -197,7 +191,7 @@ is automatically created if necessary.
 To use the moveoff_gui, add an entry in the INI file [APPLICATIONS]
 section as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 [APPLICATIONS]
 # Note: a delay (specified in seconds) may be required if connections
@@ -219,11 +213,11 @@ configs (configs/sim/axis/moveoff/*.ini) use a simple system HAL file
 (named LIB:moveoff_external.hal) to connect the mv.move-enable, mv.offset-in-M,
 and mv.bactrack-enable pins to signals:
 
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 HALUI = halui
-...
+# ...
 HALFILE = LIB:hookup_moveoff.tcl
 HALFILE = LIB:moveoff_external.hal
 ----
@@ -231,7 +225,7 @@ HALFILE = LIB:moveoff_external.hal
 The connections made by LIB:moveoff_external.hal (for a three axis
 configuration) are:
 
-[source,{hal}]
+[source,hal]
 ----
 net external_enable mv.move-enable
 
diff --git a/docs/src/config/python-hal-interface.adoc b/docs/src/config/python-hal-interface.adoc
index 90f6d913bd0..40dc67436c8 100644
--- a/docs/src/config/python-hal-interface.adoc
+++ b/docs/src/config/python-hal-interface.adoc
@@ -4,10 +4,6 @@
 [[cha:python-hal-interface]]
 = The HAL Python module
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
 This documentation describes the `hal` python module, which provides
 a Python API for creating and accessing HAL pins and signals.
 
diff --git a/docs/src/config/python-interface.adoc b/docs/src/config/python-interface.adoc
index cdf5a3d97e3..219a873d244 100644
--- a/docs/src/config/python-interface.adoc
+++ b/docs/src/config/python-interface.adoc
@@ -4,10 +4,6 @@
 [[cha:python-interface]]
 = The LinuxCNC Python module
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
 This documentation describes the `linuxcnc` python module, which provides
 a Python API for talking to LinuxCNC.
 
diff --git a/docs/src/config/stepper-diagnostics.adoc b/docs/src/config/stepper-diagnostics.adoc
index d4b3d3d011a..dc5d8b33f25 100644
--- a/docs/src/config/stepper-diagnostics.adoc
+++ b/docs/src/config/stepper-diagnostics.adoc
@@ -4,12 +4,6 @@
 [[cha:stepper-diagnostics]]
 = Stepper Diagnostics
 
-// 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}
-
 (((Stepper Diagnostics)))
 If what you get is not what you expect many times you just got some
 experience. Learning from the experience increases your understanding
@@ -114,7 +108,7 @@ the final position will not end up 0.500" that the axis window is
 showing. To test another axis just replace the Z with your axis in the
 G0 lines.
 
-[source,{ngc}]
+[source,ngc]
 ----
 ( test program to see if Z axis loses position )
 ( msg, test 1 of Z axis configuration )
diff --git a/docs/src/config/stepper.adoc b/docs/src/config/stepper.adoc
index 562af551e2d..94b6df0a2d2 100644
--- a/docs/src/config/stepper.adoc
+++ b/docs/src/config/stepper.adoc
@@ -4,11 +4,6 @@
 [[cha:stepper-config]]
 = Stepper Configuration
 
-// 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}
 
 == Introduction
 
@@ -66,7 +61,7 @@ Further on we'll investigate the standard_pinout.hal.
 
 This file contains several HAL commands, and usually looks like this:
 
-[source,{hal}]
+[source,hal]
 ----
 # standard pinout config file for 3-axis steppers
 # using a parport for I/O
@@ -168,7 +163,7 @@ Open the file and locate the parts you want to change.
 
 If you want for example to change the pin for the X-axis Step & Directions signals, all you need to do is to change the number in the 'parport.0.pin-XX-out' name:
 
-[source,{hal}]
+[source,hal]
 ----
 net Xstep parport.0.pin-03-out
 net Xdir  parport.0.pin-02-out
@@ -176,7 +171,7 @@ net Xdir  parport.0.pin-02-out
 
 can be changed to:
 
-[source,{hal}]
+[source,hal]
 ----
 net Xstep parport.0.pin-02-out
 net Xdir  parport.0.pin-03-out
@@ -191,7 +186,7 @@ Hint: make sure you don't have more than one signal connected to the same pin.
 If external hardware expects an "active low" signal, set the corresponding '-invert' parameter.
 For instance, to invert the spindle control signal:
 
-[source,{hal}]
+[source,hal]
 ----
 setp parport.0.pin-09-out-invert TRUE
 ----
@@ -200,7 +195,7 @@ setp parport.0.pin-09-out-invert TRUE
 
 If your spindle can be controlled by a PWM signal, use the 'pwmgen' component to create the signal:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt pwmgen output_type=0
 addf pwmgen.update servo-thread
@@ -222,7 +217,7 @@ For this reason there are already defined signals called 'Xen', 'Yen', 'Zen'.
 
 To connect them use the following example:
 
-[source,{hal}]
+[source,hal]
 ----
 net Xen parport.0.pin-08-out
 ----
diff --git a/docs/src/drivers/ax5214h.adoc b/docs/src/drivers/ax5214h.adoc
index a21be849f0e..d1365899503 100644
--- a/docs/src/drivers/ax5214h.adoc
+++ b/docs/src/drivers/ax5214h.adoc
@@ -4,12 +4,6 @@
 [[cha:ax5214-driver]]
 = AX5214H Driver
 
-// 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}
-
 The Axiom Measurement & Control AX5214H is a 48 channel digital I/O
 board. It plugs into an ISA bus, and resembles a pair of 8255 chips. In
 fact it may be a pair of 8255 chips, but I'm not sure. If/when someone
@@ -18,7 +12,7 @@ of the work is already done.
 
 == Installing
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_ax5214h cfg=""
 ----
diff --git a/docs/src/drivers/gm.adoc b/docs/src/drivers/gm.adoc
index 93d96aabc0a..a2ffc520185 100644
--- a/docs/src/drivers/gm.adoc
+++ b/docs/src/drivers/gm.adoc
@@ -4,12 +4,6 @@
 [[cha:gm-driver]]
 = General Mechatronics Driver
 
-// 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}
-
 General Mechatronics GM6-PCI card based motion control system
 
 For detailed description, please refer to the https://www.generalmechatronics.com/data/products/robot_controller/PCI_UserManual_eng.pdf[System integration manual].
@@ -36,7 +30,7 @@ image::images/GMsystem.png["GM servo control system",align="center",scaledwidth=
 
 Installing:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_gm
 ----
@@ -229,7 +223,7 @@ For example, if position-scale is 2000, then 1000 counts of the encoder will pro
 .HAL example
 
 .Setting encoder module of axis 0 to receive 500 CPR quadrature encoder signal and use reset to round position.
-[source,{hal}]
+[source,hal]
 ----
 setp gm.0.encoder.0.counter-mode 0         # 0: quad, 1: stepDir
 setp gm.0.encoder.0.index-mode 1           # 0: reset pos at index, 1:round pos at index
@@ -240,7 +234,7 @@ setp gm.0.encoder.0.position-scale 20000   # 10 encoder rev cause the machine to
 ----
 
 .Connect encoder position to LinuxCNC joint position feedback
-[source,{hal}]
+[source,hal]
 ----
 net Xpos-fb gm.0.encoder.0.position => joint.0.motor-pos-fb
 ----
@@ -310,7 +304,7 @@ image::images/GM_RefSignals.png["Reference signal timing diagrams",align="center
 .HAL example
 
 .Setting StepGen module of axis 0 to generate 1000 step pulse per position unit
-[source,{hal}]
+[source,hal]
 ----
 setp gm.0.stepgen.0.step-type 0         # 0:stepDir, 1:UpDown, 2:Quad
 setp gm.0.stepgen.0.control-type 0      # 0:Pos. control, 1:Vel. Control
@@ -327,7 +321,7 @@ setp gm.0.stepgen.0.dirdelay 2000       # 2000 ns = 2 µs
 ----
 
 .Connect StepGen to axis 0 position reference and enable pins
-[source,{hal}]
+[source,hal]
 ----
 net Xpos-cmd joint.0.motor-pos-cmd => gm.0.stepgen.0.position-cmd
 net Xen joint.0.amp-enable-out => gm.0.stepgen.0.enable
diff --git a/docs/src/drivers/gs2.adoc b/docs/src/drivers/gs2.adoc
index 0aadefbab66..4136fe7e9f3 100644
--- a/docs/src/drivers/gs2.adoc
+++ b/docs/src/drivers/gs2.adoc
@@ -4,18 +4,12 @@
 [[cha:gs2-vfd-driver]]
 = GS2 VFD Driver
 
-// 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}
-
 (((GS2 VFD Driver)))
 This is a non-realtime HAL program for the GS2 series of VFDs at Automation Direct. footnote:[In Europe the equivalent can be found under the brand name Omron.]
 
 This component is loaded using the halcmd "loadusr" command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn spindle-vfd gs2_vfd -n spindle-vfd
 ----
diff --git a/docs/src/drivers/hostmot2.adoc b/docs/src/drivers/hostmot2.adoc
index cc6845f663f..e18613f62de 100644
--- a/docs/src/drivers/hostmot2.adoc
+++ b/docs/src/drivers/hostmot2.adoc
@@ -4,11 +4,6 @@
 [[cha:mesa-hostmot2-driver]]
 = Mesa HostMot2 Driver
 
-// 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}
 
 == Introduction
 
@@ -66,7 +61,7 @@ I/O boards. The low-level I/O drivers are 'hm2_7i43' and 'hm2_pci' (for
 all the PCI- and PC-104/Plus-based Anything I/O boards). The hostmot2 driver
 must be loaded first, using a HAL command like this:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hostmot2
 ----
@@ -78,7 +73,7 @@ boards running the HostMot2 firmware. The low-level I/O drivers provide
 this access. The low-level I/O drivers are loaded with commands like
 this:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT
        num_encoders=3 num_pwmgens=3 num_stepgens=1"
@@ -180,7 +175,7 @@ your configuration.
 
 An example of a 5I20 configuration:
 
-[source,{ini}]
+[source,ini]
 ----
 [HOSTMOT2]
 DRIVER=hm2_pci
@@ -718,7 +713,7 @@ If you like to roll your own configuration the following examples show how
 to load the drivers in the HAL file.
 
 .5I25 + 7I76 Card
-[source,{hal}]
+[source,hal]
 ----
 # load the generic driver
 loadrt hostmot2
@@ -728,7 +723,7 @@ loadrt hm2_pci config="num_encoders=1 num_stepgens=5 sserial_port_0=0XXX"
 ----
 
 .5I25 + 7I77 Card
-[source,{hal}]
+[source,hal]
 ----
 # load the generic driver
 loadrt hostmot2
diff --git a/docs/src/drivers/mb2hal.adoc b/docs/src/drivers/mb2hal.adoc
index b4fd7ffc5f3..d82568e76f0 100644
--- a/docs/src/drivers/mb2hal.adoc
+++ b/docs/src/drivers/mb2hal.adoc
@@ -4,11 +4,6 @@
 [[cha:mb2hal]]
 = MB2HAL
 
-// 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}
 
 == Introduction
 
@@ -150,7 +145,7 @@ Program or connection:
 
 Click link:mb2hal_HOWTO.ini[here] to download.
 
-[source,{ini}]
+[source,ini]
 ----
 include::mb2hal_HOWTO.ini[]
 ----
diff --git a/docs/src/drivers/mitsub-vfd.adoc b/docs/src/drivers/mitsub-vfd.adoc
index 06b9f982319..557eab54f42 100644
--- a/docs/src/drivers/mitsub-vfd.adoc
+++ b/docs/src/drivers/mitsub-vfd.adoc
@@ -4,14 +4,6 @@
 [[cha:mitsub]]
 = Mitsub VFD Driver
 
-// 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}
-
-:hal: {basebackend@docbook:'':hal}
-
 This is a non-realtime HAL program, written in Python, to control VFDs from
 Mitsubishi. +
 Specifically the A500 F500 E500 A500 D700 E700 F700 series - others may work. +
@@ -25,7 +17,7 @@ One should always have an Estop circuit that kills the power to the unit in case
 
 This component is loaded using the halcmd "loadusr" command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn coolant mitsub_vfd spindle=02 coolant=01
 ----
@@ -103,7 +95,7 @@ Where  is +mitsub_vfd+ or the name given during loading.
 
 == HAL example
 
-[source,{hal}]
+[source,hal]
 ----
 #
 # example usage of the Mitsubishi VFD driver
diff --git a/docs/src/drivers/motenc.adoc b/docs/src/drivers/motenc.adoc
index 65e7e96b5f9..fee21dac40c 100644
--- a/docs/src/drivers/motenc.adoc
+++ b/docs/src/drivers/motenc.adoc
@@ -4,12 +4,6 @@
 [[cha:motenc]]
 = Motenc Driver
 
-// 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}
-
 Vital Systems Motenc-100 and Motenc-LITE
 
 The Vital Systems Motenc-100 and Motenc-LITE are 8- and 4-channel
@@ -22,7 +16,7 @@ board and exports the appropriate HAL objects.
 
 Installing:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_motenc
 ----
diff --git a/docs/src/drivers/opto22.adoc b/docs/src/drivers/opto22.adoc
index 5bff01e9544..e6c18d4e1a8 100644
--- a/docs/src/drivers/opto22.adoc
+++ b/docs/src/drivers/opto22.adoc
@@ -4,12 +4,6 @@
 [[cha:opto22]]
 = Opto22 Driver
 
-// 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}
-
 *PCI AC5 ADAPTER CARD / HAL DRIVER*
 
 == The Adapter Card
@@ -37,7 +31,7 @@ card. The HAL driver is a realtime module. It will support 4 cards as
 is (more cards are possible with a change in the source code). Load the
 basic driver like so:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt opto_ac5
 ----
@@ -109,7 +103,7 @@ They would be numbered 12 to 23 port 1 would be the same.
 
 To change the default setting load the driver something like so:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt opto_ac5 portconfig0=0xffff portconfig1=0xff0000
 ----
diff --git a/docs/src/drivers/pico-ppmc.adoc b/docs/src/drivers/pico-ppmc.adoc
index 0c72079d121..cd10b7ee224 100644
--- a/docs/src/drivers/pico-ppmc.adoc
+++ b/docs/src/drivers/pico-ppmc.adoc
@@ -4,12 +4,6 @@
 [[cha:pico-drivers]]
 = Pico Drivers
 
-// 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}
-
 Pico Systems has a family of boards for doing analog servo, stepper,
 and PWM (digital) servo control. The boards connect to the PC through a
 parallel port working in EPP mode. Although most users connect one
@@ -24,7 +18,7 @@ USC. And the Universal PWM Controller, or UPC.
 
 Installing:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_ppmc port_addr=[,[,...]]
 ----
diff --git a/docs/src/drivers/pmx485.adoc b/docs/src/drivers/pmx485.adoc
index 6113bc3e9a9..fcd103d691d 100644
--- a/docs/src/drivers/pmx485.adoc
+++ b/docs/src/drivers/pmx485.adoc
@@ -4,19 +4,13 @@
 [[cha:pmx485]]
 = Powermax Modbus Driver
 
-// 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}
-
 This is a non-realtime HAL program, written in python, to control Hypetherm Powermax plasma cutters using the Modbus ASCII protocol over RS485.
 
 NOTE: Since this is a non-realtime program it can be affected by computer loading and latency. It is possible to lose communications which will be indicated by a change in the status output. One should always have an Estop circuit that kills the power to the unit in case of emergency.
 
 This component is loaded using the halcmd "loadusr" command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn pmx485 pmx485 /dev/ttyUSB0
 ----
diff --git a/docs/src/drivers/servo-to-go.adoc b/docs/src/drivers/servo-to-go.adoc
index 64703001874..205a8ced029 100644
--- a/docs/src/drivers/servo-to-go.adoc
+++ b/docs/src/drivers/servo-to-go.adoc
@@ -4,12 +4,6 @@
 [[cha:servo-to-go]]
 = Servo To Go Driver
 
-// 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}
-
 The Servo-To-Go (STG) is one of the first PC motion control cards supported
 by LinuxCNC. It is an ISA card and it exists in different flavors (all
 supported by this driver). The board includes up to 8 channels of
@@ -25,7 +19,7 @@ this problem, and work fine with the STG cards.
 
 == Installing
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_stg [base=
] [num_chan=] [dio=""] \
                  [model=]
@@ -48,7 +42,7 @@ HINT: after starting up the driver, 'dmesg' can be consulted for
 messages relevant to the driver (e.g. autodetected version number and
 base address). For example:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_stg base=0x300 num_chan=4 dio="IOIO"
 ----
@@ -60,7 +54,7 @@ configured as Input, the next 8 (Port B) configured as Output, the next
 8 (Port C) configured as Input, and the last 8 (Port D) configured as
 Output
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_stg
 ----
diff --git a/docs/src/drivers/vfs11.adoc b/docs/src/drivers/vfs11.adoc
index 752b71c0ea1..485b6758bb7 100644
--- a/docs/src/drivers/vfs11.adoc
+++ b/docs/src/drivers/vfs11.adoc
@@ -4,10 +4,6 @@
 [[cha:vfs11-vfd]]
 = VFS11 VFD Driver
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
 This is a non-realtime HAL program to control the S11 series of VFDs from Toshiba.
 
 vfs11_vfd supports serial and TCP connections.
@@ -18,7 +14,7 @@ Regardless of the connection type, vfs11_vfd operates as a Modbus master.
 
 This component is loaded using the halcmd "loadusr" command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn spindle-vfd vfs11_vfd -n spindle-vfd
 ----
@@ -142,8 +138,8 @@ Where  is +vfs11_vfd+ or the name given during loading with the -n option.
 This lists all options understood by vfs11_vfd.
 Typical setups for RS-232, RS-485 and TCP can be found in 'src/hal/user_comps/vfs11_vfd/*.ini'.
 
-[source,{ini}]
----------------------------------------------------------------------
+[source,ini]
+----
 [VFS11]
 # serial connection
 TYPE=rtu
@@ -204,12 +200,12 @@ RECONNECT_DELAY=1
 DEBUG=10
 MODBUS_DEBUG=0
 POLLCYCLES=10
----------------------------------------------------------------------
+----
 
 == HAL example
 
-[source,{hal}]
----------------------------------------------------------------------
+[source,hal]
+----
 #
 # example usage of the VF-S11 VFD driver
 #
@@ -240,7 +236,7 @@ net spindle-orient spindle.0.orient spindle-vfd.max-speed spindle-vfd.jog-mode
 
 # take precedence over control panel
 setp spindle-vfd.enable 1
----------------------------------------------------------------------
+----
 
 == Panel operation
 
diff --git a/docs/src/examples/gs2-example.adoc b/docs/src/examples/gs2-example.adoc
index eb848baf5c3..aedfd72b81f 100644
--- a/docs/src/examples/gs2-example.adoc
+++ b/docs/src/examples/gs2-example.adoc
@@ -4,11 +4,6 @@
 [[cha:gs2-spindle]]
 = GS2 Spindle
 
-// 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}
 
 == Example
 
@@ -21,7 +16,7 @@ We start with a StepConf Wizard generated config. Make sure the pins with "Spind
 In the custom.hal file we place the following to connect LinuxCNC to the GS2 and have LinuxCNC control the drive.
 
 .GS2 Example
-[source,{hal}]
+[source,hal]
 ----
 # load the non-realtime component for the Automation Direct GS2 VFDs
 loadusr -Wn spindle-vfd gs2_vfd -r 9600 -p none -s 2 -n spindle-vfd
diff --git a/docs/src/examples/mpg.adoc b/docs/src/examples/mpg.adoc
index bf827284a25..99ee3e5d861 100644
--- a/docs/src/examples/mpg.adoc
+++ b/docs/src/examples/mpg.adoc
@@ -4,12 +4,6 @@
 [[cha:mpg-pendant]]
 = MPG Pendant
 
-// 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}
-
 This example is to explain how to hook up the common MPG pendants
 found on the market today. This example uses an MPG3 pendant and a
 C22 pendant interface card from CNC4PC connected to a second parallel
@@ -29,7 +23,7 @@ mode.  Machines with non-identity kinematics may need use additional
 connections for jogging in joint mode.
 
 .jog.hal
-[source,{hal}]
+[source,hal]
 ----
 # Jog Pendant
 loadrt encoder num_chan=1
@@ -88,7 +82,7 @@ for each click of the MPG use the link:../man/man9/ilowpass.9.html[ilowpass] com
 limit the acceleration.
 
 .jog.hal with ilowpass
-[source,{hal}]
+[source,hal]
 ----
 loadrt encoder num_chan=1
 loadrt mux4 count=1
diff --git a/docs/src/examples/pci-parallel-port.adoc b/docs/src/examples/pci-parallel-port.adoc
index 084659633a2..d1e4a2c17a2 100644
--- a/docs/src/examples/pci-parallel-port.adoc
+++ b/docs/src/examples/pci-parallel-port.adoc
@@ -4,12 +4,6 @@
 [[cha:pci-parallel-port]]
 = PCI Parallel Port
 
-// 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}
-
 When you add a second parallel port to your PCI bus you have to find
 out the address before you can use it with LinuxCNC.
 
@@ -38,14 +32,14 @@ else on the PCI bus:
 
 In my case the address was the first one so I changed my .hal file from
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg=0x378
 ----
 
 to
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0x378 0xa800 in"
 ----
@@ -54,7 +48,7 @@ loadrt hal_parport cfg="0x378 0xa800 in"
 
 and then added the following lines so the parport will be read and written:
 
-[source,{hal}]
+[source,hal]
 ----
 addf parport.1.read base-thread
 addf parport.1.write base-thread
diff --git a/docs/src/examples/spindle.adoc b/docs/src/examples/spindle.adoc
index 67ff0427d8b..b79e117c8fd 100644
--- a/docs/src/examples/spindle.adoc
+++ b/docs/src/examples/spindle.adoc
@@ -4,12 +4,6 @@
 [[cha:spindle-control]]
 = Spindle Control
 
-// 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}
-
 LinuxCNC can control up to 8 spindles. The number is set in the INI file.
 The examples below all refer to a single-spindle config with spindle
 control pins with names like 'spindle.0..'.
@@ -32,7 +26,7 @@ We have to add a scale component to the HAL file to scale the
 _spindle.N.speed-out_ to the 0 to 10 needed by the VFD if your DAC
 card does not do scaling.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt scale count=1
 addf scale.0 servo-thread
@@ -47,7 +41,7 @@ net spindle-speed-DAC scale.0.out => 
 If your spindle can be controlled by a PWM signal,
 use the 'pwmgen' component to create the signal:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt pwmgen output_type=0
 addf pwmgen.update servo-thread
@@ -73,7 +67,7 @@ To link these pins to a parallel port pin put something like
 the following in your .hal file, making sure you pick the
 pin that is connected to your control device.
 
-[source,{hal}]
+[source,hal]
 ----
 net spindle-enable spindle.0.on => parport.0.pin-14-out
 ----
@@ -90,7 +84,7 @@ To link these pins to a parallel port pin, put something like the
 following in your .hal file making sure you pick the pin that is
 connected to your control device.
 
-[source,{hal}]
+[source,hal]
 ----
 net spindle-fwd spindle.0.forward => parport.0.pin-16-out
 net spindle-rev spindle.0.reverse => parport.0.pin-17-out
@@ -109,7 +103,7 @@ motion can begin.
 
 In the 0-10 Volt example the line
 
-[source,{hal}]
+[source,hal]
 ----
 net spindle-speed-scale spindle.0.speed-out => scale.0.in
 ----
@@ -131,7 +125,7 @@ to the two HAL components used in the following example.
 More info is available in the documentation for HAL components, or from
 the man pages, just say 'man limit2' or 'man near' in a terminal.
 
-[source,{hal}]
+[source,hal]
 ----
 # load the real time modules limit2 and near with names so it is easier to follow their connections
 loadrt limit2 names=spindle-ramp
@@ -197,7 +191,7 @@ footnote:[It is because we selected 'non-quadrature simple counting...'
 above that we can get away with 'quadrature' counting without having any
 B quadrature input.]
 
-[source,{hal}]
+[source,hal]
 ----
 # Add the encoder to HAL and attach it to threads.
 loadrt encoder num_chan=4
@@ -245,7 +239,7 @@ file to enable Spindle At Speed. If you already have near in your HAL
 file then increase the count and adjust code to suit. Check to make
 sure the signal names are the same in your HAL file.
 
-[source,{hal}]
+[source,hal]
 ----
 # load a near component and attach it to a thread
 loadrt near
diff --git a/docs/src/gcode/coordinates.adoc b/docs/src/gcode/coordinates.adoc
index eb81ac45b64..f35a7cdd324 100644
--- a/docs/src/gcode/coordinates.adoc
+++ b/docs/src/gcode/coordinates.adoc
@@ -4,11 +4,6 @@
 [[cha:coordinate-system]]
 = Coordinate Systems
 
-// 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}
 
 == Introduction
 
@@ -44,7 +39,7 @@ Regardless of any offset that may be active, a G53 in a line of
 code tells the interpreter to move to the actual axes positions
 (absolute positions) specified. For example:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G53 G0 X0 Y0 Z0
 ----
@@ -125,7 +120,7 @@ reference for each of the locations and all of the work to be done
 there. The following code is offered as an example of making a square
 using the G55 offsets that we set above.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G55 ; use coordinate system 2
 G0 X0 Y0 Z0
@@ -149,7 +144,7 @@ command would not have been modal and any commands issued after it would
 have returned to using the G55 offsets because that coordinate system
 would still be in effect.
 
-[source,{ngc}](((G54)))(((G55)))(((G56)))(((G57)))(((G58)))(((G59)))(((G59.1)))(((G59.2)))(((G59.3)))
+[source,ngc](((G54)))(((G55)))(((G56)))(((G57)))(((G58)))(((G59)))(((G59.1)))(((G59.2)))(((G59.3)))
 ----
 G54	uses parameters of coordinate system 1
 G55	uses parameters of coordinate system 2
@@ -406,7 +401,7 @@ This sample engraving project mills a set of four .1 radius circles in
 roughly a star shape around a center circle. We can setup the
 individual circle pattern like this.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L2 P1 X0 Y0 Z0 (ensure that G54 is set to machine zero)
 G0 X-0.1 Y0 Z0
@@ -419,7 +414,7 @@ M2
 We can issue a set of commands to create offsets for the four other
 circles like this.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L2 P2 X0.5 (offsets G55 X value by 0.5 inch)
 G10 L2 P3 X-0.5 (offsets G56 X value by -0.5 inch)
@@ -429,7 +424,7 @@ G10 L2 P5 Y-0.5 (offsets G58 Y value by -0.5 inch)
 
 We put these together in the following program:
 
-[source,{ngc}]
+[source,ngc]
 ----
 (a program for milling five small circles in a diamond shape)
 
diff --git a/docs/src/gcode/g-code.adoc b/docs/src/gcode/g-code.adoc
index c9840103486..66f1a2b776f 100644
--- a/docs/src/gcode/g-code.adoc
+++ b/docs/src/gcode/g-code.adoc
@@ -4,9 +4,6 @@
 [[cha:g-codes]]
 = G-Codes
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
 
 == Conventions
 
@@ -121,7 +118,7 @@ as the 'L number', and so on for any other letter.
 [[gcode:g0]]
 == G0 Rapid Move(((G0 Rapid Move)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G0 
 ----
@@ -141,7 +138,7 @@ MAX_VELOCITY setting in the [TRAJ] section if an axis MAX_VELOCITY or
 trajectory constraints limit it.
 
 .G0 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute distance mode)
 G0 X1 Y-2.3 (Rapid linear move from current location to X1 Y-2.3)
@@ -177,10 +174,10 @@ It is an error if:
 [[gcode:g1]]
 == G1 Linear Move(((G1 Linear Move)))
 
-[source,{ngc}]
--------------------
+[source,ngc]
+----
 G1 axes
--------------------
+----
 
 For linear (straight line) motion at programmed <>
 (for cutting or not), program 'G1 'axes'', where all the axis words are
@@ -189,7 +186,7 @@ will produce coordinated motion to the destination point at the current
 feed rate (or slower).
 
 .G1 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute distance mode)
 G1 X1.2 Y-3 F10 (linear move at a feed rate of 10 from current position to X1.2 Y-3)
@@ -217,7 +214,7 @@ It is an error if:
 [[gcode:g2-g3]]
 == G2, G3 Arc Move(((G2, G3 Arc Move)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G2 or G3 axes offsets (center format)
 G2 or G3 axes R- (radius format)
@@ -322,7 +319,7 @@ For more information on 'Absolute Arc Distance Mode see the
 <> section.
 
 .XY-plane (G17)
-[source,{ngc}]
+[source,ngc]
 ----
 G2 or G3 
 ----
@@ -333,7 +330,7 @@ G2 or G3 
 * 'P' - number of turns
 
 .XZ-plane (G18)
-[source,{ngc}]
+[source,ngc]
 ----
 G2 or G3 
 ----
@@ -344,7 +341,7 @@ G2 or G3 
 * 'P' - number of turns
 
 .YZ-plane (G19)
-[source,{ngc}]
+[source,ngc]
 ----
 G2 or G3 
 ----
@@ -388,7 +385,7 @@ us an offset from the start position of 1 in the X axis and 0 in the Y
 axis. In this case only an I offset is needed.
 
 .G2 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X0 Y0
 G2 X1 Y1 I1 F10 (clockwise arc in the XY plane)
@@ -404,7 +401,7 @@ both moves. The G2 move the J offset is 0.5 and the G3 move the J
 offset is -0.5.
 
 .G2-G3 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X0 Y0
 G2 X0 Y1 I1 J0.5 F25 (clockwise arc in the XY plane)
@@ -418,7 +415,7 @@ In the next example we show how the arc can make a helix in the Z axis
 by adding the Z word.
 
 .G2 Example Helix
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X0 Y0 Z0
 G17 G2 X10 Y16 I3 J4 Z-1 (helix arc with Z added)
@@ -428,7 +425,7 @@ In the next example we show how to make more than one turn using the P
 word.
 
 .P word Example
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X0 Y0 Z0
 G2 X0 Y1 Z-1 I1 J0.5 P2 F25
@@ -462,7 +459,7 @@ It is an error if:
 
 === Radius Format Arcs
 
-[source,{ngc}]
+[source,ngc]
 ----
 G2 or G3 axes R- 
 ----
@@ -497,7 +494,7 @@ It is an error if:
 * the end point of the arc is the same as the current point.
 
 .G2 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G17 G2 X10 Y15 R20 Z5 (radius format with arc)
 ----
@@ -511,7 +508,7 @@ otherwise it is a helical arc.
 [[gcode:g4]]
 == G4 Dwell(((G4 Dwell)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G4 P-
 ----
@@ -524,7 +521,7 @@ used.
 G4 does not affect spindle, coolant and any I/O.
 
 .G4 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G4 P0.5 (wait for 0.5 seconds before proceeding)
 ----
@@ -536,7 +533,7 @@ It is an error if:
 [[gcode:g5]]
 == G5 Cubic Spline(((G5 Cubic spline)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G5 X- Y-  P- Q-
 ----
@@ -559,7 +556,7 @@ Q).
 For example, to program a curvy N shape:
 
 .G5 Sample initial cubic spline
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G17
 G0 X0 Y0
@@ -570,7 +567,7 @@ A second curvy N that attaches smoothly to this one can now be made
 without specifying I and J:
 
 .G5 Sample subsequent cubic spline
-[source,{ngc}]
+[source,ngc]
 ----
 G5 P0 Q-3 X2 Y2
 ----
@@ -586,7 +583,7 @@ It is an error if:
 [[gcode:g5.1]]
 == G5.1 Quadratic Spline(((G5.1 Quadratic spline)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G5.1 X- Y- I- J-
 ----
@@ -602,7 +599,7 @@ For example, to program a parabola, through the origin, from X-2 Y4 to
 X2 Y4:
 
 .G5.1 Sample quadratic spline
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G17
 G0 X-2 Y4
@@ -618,7 +615,7 @@ It is an error if:
 [[gcode:g5.2-g5.3]]
 == G5.2 G5.3 NURBS Block(((G5.2 G5.3 NURBS Block)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G5.2   
 X- Y- 
@@ -641,7 +638,7 @@ The default weight if P is unspecified is 1.  The default order if L is
 unspecified is 3.
 
 .G5.2 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X0 Y0 (rapid move)
 F10 (set feed rate)
@@ -669,7 +666,7 @@ https://wiki.linuxcnc.org/cgi-bin/wiki.pl?NURBS[https://wiki.linuxcnc.org/cgi-bi
 [[gcode:g7]]
 == G7 Lathe Diameter Mode(((G7 Lathe Diameter Mode)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G7
 ----
@@ -682,7 +679,7 @@ to the center of the lathe. For example X1 would move the cutter to
 [[gcode:g8]]
 == G8 Lathe Radius Mode(((G8 Lathe Radius Mode)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G8
 ----
@@ -695,7 +692,7 @@ G8 is default at power up.
 [[gcode:g10-l0]]
 == G10 L0 Reload Tool Table Data(((G10 L0 Reload Tool Table Data)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L0
 ----
@@ -714,7 +711,7 @@ remain in effect until updated by new G43 commands.
 [[gcode:g10-l1]]
 == G10 L1 Set Tool Table(((G10 L1 Tool Table)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L1 P- axes 
 ----
@@ -732,7 +729,7 @@ A valid G10 L1 rewrites and reloads the tool table for the specified
 tool.
 
 .G10 L1 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L1 P1 Z1.5 (set tool 1 Z offset from the machine origin to 1.5)
 G10 L1 P2 R0.015 Q3 (lathe example setting tool 2 radius to 0.015 and orientation to 3)
@@ -751,7 +748,7 @@ see the <> diagram.
 [[gcode:g10-l2]]
 == G10 L2 Set Coordinate System(((G10 L2 Coordinate System)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L2 P- 
 ----
@@ -814,7 +811,7 @@ It is an error if:
 * An axis is programmed that is not defined in the configuration.
 
 .G10 L2 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L2 P1 X3.5 Y17.2
 ----
@@ -825,7 +822,7 @@ Because only X and Y are specified, the origin point is only moved in X
 and Y; the other coordinates are not changed.
 
 .G10 L2 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L2 P1 X0 Y0 Z0 (clear offsets for X,Y & Z axes in coordinate system 1)
 ----
@@ -839,7 +836,7 @@ The coordinate system is described in the
 [[gcode:g10-l10]]
 == G10 L10 Set Tool Table(((G10 L10 Set Tool Table)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L10 P- axes 
 ----
@@ -858,7 +855,7 @@ specified in the G10 L10 command will not be changed. This could be
 useful with a probe move as described in the <> section.
 
 .G10 L10 Example
-[source,{ngc}]
+[source,ngc]
 ----
 T1 M6 G43 (load tool 1 and tool length offsets)
 G10 L10 P1 Z1.5 (set the current position for Z to be 1.5)
@@ -879,7 +876,7 @@ It is an error if:
 [[gcode:g10-l11]]
 == G10 L11 Set Tool Table(((G10 L11 Set Tool Table)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L11 P- axes 
 ----
@@ -915,7 +912,7 @@ It is an error if:
 [[gcode:g10-l20]]
 == G10 L20 Set Coordinate System(((G10 L20 Set Coordinate System)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L20 P- axes
 ----
@@ -927,7 +924,7 @@ offset/entry to the given value, it is set to a calculated value that
 makes the current coordinates become the given value.
 
 .G10 L20 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G10 L20 P1 X1.5 (set the X axis current location in coordinate system 1 to 1.5)
 ----
@@ -991,7 +988,7 @@ all axes will go to the <>.
   5161-5166.
 
 .G28 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G28 Z2.5 (rapid to Z2.5 then to Z location specified in #5163)
 ----
@@ -1030,7 +1027,7 @@ if TOOL_CHANGE_AT_G30=1 is in the [EMCIO] section of the INI file.
   5181-5186.
 
 .G30 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G30 Z2.5 (rapid to Z2.5 then to the Z location specified in #5183)
 ----
@@ -1042,7 +1039,7 @@ It is an error if :
 [[gcode:g33]]
 == G33 Spindle Synchronized Motion(((G33 Spindle Synchronized Motion)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G33 X- Y- Z- K- $-
 ----
@@ -1095,7 +1092,7 @@ See the Integrators Manual for more information on spindle synchronized
 motion.
 
 .G33 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (absolute distance mode)
 G0 X1 Z0.1 (rapid to position)
@@ -1119,7 +1116,7 @@ It is an error if:
 [[gcode:g33.1]]
 == G33.1 Rigid Tapping(((G33.1 Rigid Tapping)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G33.1 X- Y- Z- K- I- $-
 ----
@@ -1163,7 +1160,7 @@ so multiple passes line up.'G33.1' moves end at the original coordinate.
 All the axis words are optional, except that at least one must be used.
 
 .G33.1 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute mode)
 G0 X1.000 Y1.000 Z0.100 (rapid move to starting position)
@@ -1185,7 +1182,7 @@ It is an error if:
 [[gcode:g38]]
 == G38._n_ Straight Probe(((G38.n Probe)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G38.n axes
 ----
@@ -1258,7 +1255,7 @@ position must be high enough above the tool height probe to compensate
 for the use of G49.
 
 .G38.2 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G49
 G38.2 Z-100 F100
@@ -1295,7 +1292,7 @@ It is an error if:
   It is OK to turn compensation off when it is already off.
 
 .G40 Example
-[source,{ngc}]
+[source,ngc]
 ----
 ; current location is X1 after finishing cutter compensated move
 G40 (turn compensation off)
@@ -1314,7 +1311,7 @@ It is an error if:
 [[gcode:g41-g42]]
 == G41, G42 Cutter Compensation(((G41 G42 Cutter Compensation)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G41  (left of programmed path)
 G42  (right of programmed path)
@@ -1369,7 +1366,7 @@ It is an error if:
 [[gcode:g41.1-g42.1]]
 == G41.1, G42.1 Dynamic Cutter Compensation(((G41.1 G42.1 Dynamic Compensation)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G41.1 D-  (left of programmed path)
 G42.1 D-  (right of programmed path)
@@ -1392,7 +1389,7 @@ It is an error if:
 [[gcode:g43]]
 == G43 Tool Length Offset(((G43 Tool Length Offset)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G43 
 ----
@@ -1423,7 +1420,7 @@ in the tool table file (or causes an error if T0 is not defined in the
 tool table).
 
 .G43 H- Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G43 H1 (set tool offsets using the values from tool 1 in the tool table)
 ----
@@ -1439,7 +1436,7 @@ It is an error if:
 [[gcode:g43.1]]
 == G43.1 Dynamic Tool Length Offset(((G43.1 Dynamic Tool Length Offset)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G43.1 axes
 ----
@@ -1449,7 +1446,7 @@ G43.1 axes
   that axis's endpoint is the compensated location.
 
 .G43.1 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute mode)
 T1 M6 G43 (load tool 1 and tool length offsets, Z is at machine 0 and DRO shows Z1.500)
@@ -1469,7 +1466,7 @@ G43.1 does not write to the tool table.
 [[gcode:g43.2]]
 == G43.2 Apply additional Tool Length Offset(((G43.2 Apply additional Tool Length Offset)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G43.2 H- or axes-
 ----
@@ -1481,7 +1478,7 @@ G43.2 H- or axes-
 * 'G43.2 axes' - applies an additional simultaneous tool offset to subsequent motions by adding the value(s) of any axis words.
 
 .G43.2 H__n__ Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute mode)
 T1 M6 (load tool 1)
@@ -1491,7 +1488,7 @@ M2 (end program)
 ----
 
 .G43.2 axes Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute mode)
 T1 M6 (load tool 1)
@@ -1528,7 +1525,7 @@ used.
 [[gcode:g52]]
 == G52 Local Coordinate System Offset(((Local Offsets)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G52 axes
 ----
@@ -1539,7 +1536,7 @@ For more information about `G92` and `G52` and how they interact see <>
 ----
@@ -1657,7 +1654,7 @@ G64 >
 It is a good idea to include a path control specification in the preamble of each G-code file.
 
 .G64 P- Q- Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G64 P0.015 Q0.015 (set path following to be within 0.015 of the actual path)
 ----
@@ -1665,7 +1662,7 @@ G64 P0.015 Q0.015 (set path following to be within 0.015 of the actual path)
 The P- and Q- values ​​are chosen small. Usually smaller than the machine accuracy or the accuracy of commonly manufactured parts. Below are examples with extreme P- and Q- values ​​to understand the G64 function.
 
 .G64 Without values
-[source,{ngc}]
+[source,ngc]
 ----
 G64 (set without P- and Q- values)
 ----
@@ -1674,7 +1671,7 @@ G64 (set without P- and Q- values)
 image::images/G64_Rectangle.png["G64 Rectangle",align="center"]
 
 .G64 With big Q- value
-[source,{ngc}]
+[source,ngc]
 ----
 G64 P0.015 Q6
 ----
@@ -1685,7 +1682,7 @@ image::images/G64_Rectangle_with_radius.png["G64 Rectangle with radius before mi
 .G64 Rectangle with radius after milling
 image::images/G64_Rectangle_with_radius_q6.png["G64 Rectangle with radius after milling",align="center"]
 
-[source,{ngc}]
+[source,ngc]
 ----
 G64 P0.015 Q2
 ----
@@ -1696,7 +1693,7 @@ image::images/G64_Heart_Q2.png["G64 Heart",align="center"]
 [[gcode:g70]]
 == G70 Lathe finishing cycle(((G70 Lathe finishing cycle)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G70 Q-     
 ----
@@ -1744,7 +1741,7 @@ It is an error if:
 The G71 and G72 cycles are currently somewhat fragile.
 See issue https://github.com/LinuxCNC/linuxcnc/issues/2939[#2939] for example.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G71   Q-     
 G71.1 Q-     
@@ -1809,7 +1806,7 @@ It is an error if:
 [[gcode:g73]]
 == G73 Drilling Cycle with Chip Breaking(((G73 Drilling Cycle with Chip Break)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G73 X- Y- Z- R- Q- D- 
 ----
@@ -1841,7 +1838,7 @@ It is an error if:
 [[gcode:g74]]
 == G74 Left-hand Tapping Cycle with Dwell(((G74 Left-hand Tapping Cycle with Dwell)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G74 (X- Y- Z-) or (U- V- W-) R- L- P- $- F-
 ----
@@ -1877,7 +1874,7 @@ In example S100 with 1.25MM per revolution thread pitch gives a feed of F125.
 [[gcode:g76]]
 == G76 Threading Cycle(((G76 Threading Cycle)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G76 P- Z- I- J- R- K- Q- H- E- L- $-
 ----
@@ -1981,11 +1978,11 @@ can be previewed and executed on any machine using the 'sim/lathe.ini'
 configuration.
 
 .G76 Example Code
-[source,{ngc}]
----------------
+[source,ngc]
+----
 G0 Z-0.5 X0.2
 G76 P0.05 Z-1 I-.075 J0.008 K0.045 Q29.5 L2 E0.045
----------------
+----
 
 In the figure the tool is in the final position after the G76 cycle
 is completed. You can see the entry path on the right from the Q29.5
@@ -2122,7 +2119,7 @@ Line numbers are not needed but help clarify these examples.
 
 .Eight Holes
 
-[source,{ngc}]
+[source,ngc]
 ----
 N100 G90 G0 X0 Y0 Z0 (move coordinate home)
 N110 G1 F10 X0 G4 P0.1
@@ -2147,7 +2144,7 @@ incremental drill cycles for successive blocks of code within the same
 G81 motion mode. Here we produce 12 holes using five lines of code in
 the canned motion mode.
 
-[source,{ngc}]
+[source,ngc]
 ----
 N1000 G90 G0 X0 Y0 Z0 (move coordinate home)
 N1010 G1 F50 X0 G4 P0.1
@@ -2180,7 +2177,7 @@ It is an error if:
 *  Axis words are programmed when G80 is active.
 
 .G80 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G81 X1 Y1 Z1.5 R2.8 (absolute distance canned cycle)
 G80 (turn off canned cycle motion)
@@ -2191,7 +2188,7 @@ The following code produces the same final position and machine state as
 the previous code.
 
 .G0 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G81 X1 Y1 Z1.5 R2.8 (absolute distance canned cycle)
 G0 X0 Y0 Z0 (rapid move to coordinate home)
@@ -2208,7 +2205,7 @@ that contains an X, Y, or Z word. The following file drills (G81) a set
 of eight holes as shown in the following caption.
 
 .G80 Example 1
-[source,{ngc}]
+[source,ngc]
 ----
 N100 G90 G0 X0 Y0 Z0 (coordinate home)
 N110 G1 X0 G4 P0.1
@@ -2241,7 +2238,7 @@ to the canned cycle.
 [[gcode:g81]]
 == G81 Drilling Cycle(((G81 Drilling Cycle)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G81 (X- Y- Z-) or (U- V- W-) R- L-
 ----
@@ -2261,7 +2258,7 @@ image::images/g81mult_en.svg["G81 Cycle",align="center"]
 
 [[gcode:g81-example]]
 .Example 1 - Absolute Position G81
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G98 G81 X4 Y5 Z1.5 R2.8
 ----
@@ -2288,7 +2285,7 @@ The following moves take place:
 image::images/g81ex1_en.svg[align="center"]
 
 .Example 2 - Relative Position G81
-[source,{ngc}]
+[source,ngc]
 ----
 G91 G98 G81 X4 Y5 Z-0.6 R1.8 L3
 ----
@@ -2330,7 +2327,7 @@ The third repeat consists of 3 moves. The X position is reset to 13
 image::images/g81ex2_en.svg[align="center"]
 
 .Example 3 - Relative Position G81
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G98 G81 X4 Y5 Z1.5 R2.8
 ----
@@ -2349,7 +2346,7 @@ image::images/g81_en.svg[align="center"]
 
 This is a plot of the path of motion for the second g81 block of code.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G91 G98 G81 X4 Y5 Z-0.6 R1.8 L3
 ----
@@ -2363,7 +2360,7 @@ image::images/g81a_en.svg[align="center"]
 
 .Example 5 - Relative position R > Z
 
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G98 G81 X4 Y5 Z-0.6 R1.8
 ----
@@ -2377,7 +2374,7 @@ would make the Z move in the same location again.
 [[gcode:g82]]
 == G82 Drilling Cycle, Dwell(((G82 Drilling Cycle Dwell)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G82 (X- Y- Z-) or (U- V- W-) R- L- P-
 ----
@@ -2396,7 +2393,7 @@ The motion of a G82 canned cycle looks just like G81 with the
 addition of a dwell at the bottom of the Z move. The length of
 the dwell is specified by a 'P-' word in the G82 block.
 
-[source,{ngc}]
+[source,ngc]
 ----
 G90 G82 G98 X4 Y5 Z1.5 R2.8 P2
 ----
@@ -2407,7 +2404,7 @@ seconds at the bottom of the hole.
 [[gcode:g83]]
 == G83 Peck Drilling Cycle(((G83 Peck Drilling)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G83 (X- Y- Z-) or (U- V- W-) R- L- Q- D-
 ----
@@ -2439,7 +2436,7 @@ It is an error if:
 [[gcode:g84]]
 == G84 Right-hand Tapping Cycle, Dwell(((G84 Right-hand Tapping Cycle Dwell)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G84 (X- Y- Z-) or (U- V- W-) R- L- P- $- F-
 ----
@@ -2476,7 +2473,7 @@ F125.
 [[gcode:g85]]
 == G85 Boring Cycle, Feed Out(((G85 Boring, Feed Out)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G85 (X- Y- Z-) or (U- V- W-) R- L-
 ----
@@ -2495,7 +2492,7 @@ drilling or milling.
 [[gcode:g86]]
 == G86 Boring Cycle, Spindle Stop, Rapid Move Out(((G86 Boring, Spindle Stop, Rapid Move Out)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G86 (X- Y- Z-) or (U- V- W-) R- L- P- $-
 ----
@@ -2531,7 +2528,7 @@ the behavior is undefined.
 [[gcode:g89]]
 == G89 Boring Cycle, Dwell, Feed Out(((G89 Boring, Dwell, Feed Out)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G89 (X- Y- Z-) or (U- V- W-) R- L- P-
 ----
@@ -2557,14 +2554,14 @@ where P specifies the number of seconds to dwell.
   numbers usually represent increments from the current coordinate.
 
 .G90 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G90 (set absolute distance mode)
 G0 X2.5 (rapid move to coordinate X2.5 including any offsets in effect)
 ----
 
 .G91 Example
-[source,{ngc}]
+[source,ngc]
 ----
 G91 (set incremental distance mode)
 G0 X2.5 (rapid move 2.5 from current position along the X axis)
@@ -2584,7 +2581,7 @@ G0 X2.5 (rapid move 2.5 from current position along the X axis)
 [[gcode:g92]]
 == G92 Coordinate System Offset(((G92 Coordinate System Offset)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G92 axes
 ----
@@ -2693,7 +2690,7 @@ It is an error if:
 [[gcode:g96-g97]]
 == G96, G97 Spindle Control Mode(((G96, G97 Spindle Control Mode)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 G96  S- <$-> (Constant Surface Speed Mode)
 G97 S- <$-> (RPM Mode)
@@ -2718,7 +2715,7 @@ for each spindle prior to issuing M3.
 * 'G97' selects RPM mode.
 
 .G96 Example Line
-[source,{ngc}]
+[source,ngc]
 ----
 G96 D2500 S250 (set CSS with a max rpm of 2500 and a surface speed of 250)
 ----
@@ -2746,7 +2743,7 @@ used. The R word has different meanings in absolute distance mode and
 incremental distance mode.
 
 .G98 Retract to Origin
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X1 Y2 Z3
 G90 G98 G81 X4 Y5 Z-0.6 R1.8 F10
diff --git a/docs/src/gcode/m-code.adoc b/docs/src/gcode/m-code.adoc
index a16fb5f92aa..629d1dde75d 100644
--- a/docs/src/gcode/m-code.adoc
+++ b/docs/src/gcode/m-code.adoc
@@ -4,9 +4,6 @@
 [[cha:m-codes]]
 = M-Codes
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
 
 == M-Code Quick Reference Table
 
@@ -115,7 +112,7 @@ Use $-1 to operate on all active spindles.
 This example will start spindles 0, 1, and 2 simultaneously at different
 speeds:
 
-[source,{ngc}]
+[source,ngc]
 ----
 S100 $0
 S200 $1
@@ -126,14 +123,14 @@ M3 $-1
 This example will then reverse spindle 1 but leave the other spindles
 rotating forwards:
 
-[source,{ngc}]
+[source,ngc]
 ----
 M4 $1
 ----
 
 And this will stop spindle 2 and leave the other spindles rotating:
 
-[source,{ngc}]
+[source,ngc]
 ----
 M5 $2
 ----
@@ -219,7 +216,7 @@ state.
 
 (((M19 Orient Spindle)))
 
-[source,{ngc}]
+[source,ngc]
 ----
 M19 R- Q- [P-] [$-]
 ----
@@ -400,7 +397,7 @@ connected in your HAL file to outputs.
 == M66 Wait on Input
 
 (((M66 Wait on Input)))
-[source,{ngc}]
+[source,ngc]
 ----
 M66 P- | E- 
 ----
@@ -422,7 +419,7 @@ M66 P- | E- 
 
 .M66 Example Lines
 
-[source,{ngc}]
+[source,ngc]
 ----
 M66 P0 L3 Q5 (wait up to 5 seconds for digital input 0 to turn on)
 ----
@@ -452,7 +449,7 @@ net signal-name motion.digital-in-00 <= parport.0.pin10-in
 == M67 Analog Output, Synchronized
 
 (((M67 Analog Output, Synchronized)))
-[source,{ngc}]
+[source,ngc]
 ----
 M67 E- Q-
 ----
@@ -479,7 +476,7 @@ connected in your HAL file to outputs.
 == M68 Analog Output, Immediate
 
 (((M68 Analog Output)))
-[source,{ngc}]
+[source,ngc]
 ----
 M68 E- Q-
 ----
@@ -588,7 +585,7 @@ modal state around a subroutine call using 'M70' and 'M72'. Note that
 the 'imperialsub' subroutine is not "aware" of the M7x features and can be
 used unmodified:
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub
 (DEBUG, imperial=#<_imperial> absolute=#<_absolute> feed=#<_feed> rpm=#<_rpm>)
@@ -641,7 +638,7 @@ against inadvertent modal changes. Note the use of
 <> in
 the 'showstate' subroutine.
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub
 (DEBUG, imperial=#<_imperial> absolute=#<_absolute> feed=#<_feed> rpm=#<_rpm>)
@@ -692,7 +689,7 @@ statements. The idea is to remember the modes to be restored at the
 beginning of the subroutine, and restore these before exiting. Here is
 an example, based on snippet of 'nc_files/tool-length-probe.ngc':
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub   (measure reference tool)
 ;
@@ -715,7 +712,7 @@ O endsub
 == M100-M199 User Defined Commands
 
 (((M100-M199 User Defined Commands)))
-[source,{ngc}]
+[source,ngc]
 ----
 M1-- 
 ----
@@ -780,7 +777,7 @@ exit 0
 
 To pass a variable to a M1nn file you use the P and Q option like this:
 
-[source,{ngc}]
+[source,ngc]
 ----
 M100 P123.456 Q321.654
 ----
diff --git a/docs/src/gcode/machining-center.adoc b/docs/src/gcode/machining-center.adoc
index 5005ab9d07c..e6760936099 100644
--- a/docs/src/gcode/machining-center.adoc
+++ b/docs/src/gcode/machining-center.adoc
@@ -4,12 +4,6 @@
 [[cha:cnc-machine-overview]]
 = CNC Machine Overview
 
-// 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}
-
 (((Machine Overview)))
 This section gives a brief description of how a CNC machine is viewed
 from the input and output ends of the Interpreter.
@@ -324,7 +318,7 @@ A tool table is required to use the Interpreter. The file tells which
 tools are in which tool changer slots and what the size and type of
 each tool is. The name of the tool table is defined in the INI file:
 
-[source,{ini}]
+[source,ini]
 ----
 [EMCIO]
 # tool table file
@@ -335,14 +329,14 @@ The default filename probably looks something like the above, but
 you may prefer to give your machine its own tool table, using the
 same name as your INI file, but with a tbl extension:
 
-[source,{ini}]
+[source,ini]
 ----
 TOOL_TABLE = acme_300.tbl
 ----
 
 or:
 
-[source,{ini}]
+[source,ini]
 ----
 TOOL_TABLE = EMC-AXIS-SIM.tbl
 ----
diff --git a/docs/src/gcode/o-code.adoc b/docs/src/gcode/o-code.adoc
index c2a4362127d..ec59aa79ad9 100644
--- a/docs/src/gcode/o-code.adoc
+++ b/docs/src/gcode/o-code.adoc
@@ -4,11 +4,6 @@
 [[cha:o-codes]]
 = O Codes(((O Codes)))
 
-// 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}
 
 == Use of O-codes
 
@@ -41,7 +36,7 @@ Within a single subroutine body (or the main program), each o-number should
 still be used for only one control flow block.
 
 .Numbering Example
-[source,{ngc}]
+[source,ngc]
 ----
 (the start of o100)
 o100 sub
@@ -57,7 +52,7 @@ o100 endsub
 ----
 
 .Reusing Control Flow Numbers Across Subroutines (valid)
-[source,{ngc}]
+[source,ngc]
 ----
 (o100 if in helper.ngc does not conflict with o100 if in another.ngc)
 
@@ -98,7 +93,7 @@ Subroutines starts at 'oNNN sub' and ends at 'oNNN endsub'. The lines between
 with 'oNNN call'. Each subroutine must use a unique number.
 
 .Subroutine Example
-[source,{ngc}]
+[source,ngc]
 ----
 o100 sub
   G53 G0 X0 Y0 Z0 (rapid move to machine home)
@@ -116,7 +111,7 @@ Inside a subroutine, 'o- return' can be executed.
 This immediately returns to the calling code, just as though 'o- endsub' was encountered.
 
 .O- Return Example
-[source,{ngc}]
+[source,ngc]
 ----
 o100 sub
   (test if parameter #2 is greater than 5)
@@ -142,7 +137,7 @@ Because '1 2 3' is parsed as the number 123, the parameters must be enclosed in
 The following calls a subroutine with 3 arguments:
 
 .O- Call Example
-[source,{ngc}]
+[source,ngc]
 ----
 o100 sub
   (test if parameter #2 is greater than 5)
@@ -163,7 +158,7 @@ Defining a subroutine inside another subroutine is not allowed and will
 produce an error.  For example, the following is *invalid*:
 
 .Invalid Nested Subroutine Definition (produces an error)
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
   o100 sub       (INVALID: nested subroutine definition)
@@ -177,7 +172,7 @@ valid.  It is the `sub`/`endsub` definition that cannot be nested, not the
 `call`:
 
 .Valid Nested Subroutine Call
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
   (code here)
@@ -212,7 +207,7 @@ possibility of confusion, the interpreter will raise an error if
 definitions of one style are mixed with calls of another.
 
 .Numbered Subprogram Simple Example
-[source,{ngc}]
+[source,ngc]
 ----
 o1 (Example 1)    ; Main program 1, "Example 1"
 M98 P100          ; Call subprogram 100
@@ -273,7 +268,7 @@ block delete program end `/M30` block might be used to stop the cycle
 at a tidy point when the operator is ready.
 
 .Numbered Subprogram Full Example
-[source,{ngc}]
+[source,ngc]
 ----
 o1                             ; Main program 1
   #1 = 0
@@ -312,7 +307,7 @@ loop runs the code in the loop then checks the test condition. The
 'while/endwhile' loop does the test first.
 
 .While Endwhile Example
-[source,{ngc}]
+[source,ngc]
 ----
 (draw a sawtooth shape)
 G0 X1 Y0 (move to start position)
@@ -327,7 +322,7 @@ M2 (end program)
 ----
 
 .Do While Example
-[source,{ngc}]
+[source,ngc]
 ----
 #1 = 0 (assign parameter #1 the value of 0)
 o100 do
@@ -367,7 +362,7 @@ then the statements following the 'else' are executed. When a condition is
 evaluated to true no more conditions are evaluated in the group.
 
 .If Endif Example
-[source,{ngc}]
+[source,ngc]
 ----
 (if parameter #31 is equal to 3 set S2000)
 o101 if [#31 EQ 3]
@@ -376,7 +371,7 @@ o101 endif
 ----
 
 .If ElseIf Else EndIf Example
-[source,{ngc}]
+[source,ngc]
 ----
 (if parameter #2 is greater than 5 set F100)
 o102 if [#2 GT 5]
@@ -394,7 +389,7 @@ Several conditions may be tested for by 'elseif' statements until the
 'else' path is finally executed if all preceding conditions are false:
 
 .If Elseif Else Endif Example
-[source,{ngc}]
+[source,ngc]
 ----
 (if parameter #2 is greater than 5 set F100)
 o102 if [#2 GT 5]
@@ -417,7 +412,7 @@ you might mill a diagonal series of shapes starting at the present
 position.
 
 .Example with 'repeat'
-[source,{ngc}]
+[source,ngc]
 ----
 (Mill 5 diagonal shapes)
 G91 (Incremental mode)
@@ -434,7 +429,7 @@ G90 (Absolute mode)
 The o-number may be given by a parameter and/or calculation.
 
 .Indirection Example
-[source,{ngc}]
+[source,ngc]
 ----
 o[#101+2] call
 ----
@@ -461,13 +456,13 @@ namespace and can silently conflict across files.  If you need helper
 subroutines, place each one in its own file.
 
 .Named File Example
-[source,{ngc}]
+[source,ngc]
 ----
 o call
 ----
 
 .Numbered File Example
-[source,{ngc}]
+[source,ngc]
 ----
 o123 call
 ----
@@ -476,7 +471,7 @@ In the called file you must include the oxxx sub and endsub and the
 file must be a valid file.
 
 .Called File Example
-[source,{ngc}]
+[source,ngc]
 ----
 (filename myfile.ngc)
 o sub
@@ -496,7 +491,7 @@ Subroutines may optionally return a value by an optional expression at
 an 'endsub' or 'return' statement.
 
 .Return value example
-[source,{ngc}]
+[source,ngc]
 ----
 o123 return [#2 *5]
 ...
diff --git a/docs/src/gcode/overview.adoc b/docs/src/gcode/overview.adoc
index 5b9a34a9096..3a201f1c116 100644
--- a/docs/src/gcode/overview.adoc
+++ b/docs/src/gcode/overview.adoc
@@ -5,14 +5,6 @@
 [[cha:overview-of-g-code-programming]]
 = Overview of G-Code Programming
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-// begin a listing of INI/HAL/NGC files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
-
 == Overview
 
 The LinuxCNC G-code language is based on the RS274/NGC language.
@@ -621,12 +613,12 @@ to the values of INI file entries and HAL pins.
 
 For example, if the INI file looks like so:
 
-[source,{ini}]
----------------------------------------------------------------------
+[source,ini]
+----
 [SETUP]
 XPOS = 3.145
 YPOS = 2.718
----------------------------------------------------------------------
+----
 
 you may refer to the named parameters `#<_ini[setup]xpos>` and
 `#<_ini[setup]ypos>` within G-code.
@@ -634,14 +626,14 @@ you may refer to the named parameters `#<_ini[setup]xpos>` and
 `EXISTS` can be used to test for presence of a given INI file
 variable:
 
-[source,{ngc}]
----------------------------------------------------------------------
+[source,ngc]
+----
 o100 if [EXISTS[#<_ini[setup]xpos>]]
   (debug, [setup]xpos exists: #<_ini[setup]xpos>)
 o100 else
   (debug, [setup]xpos does not exist)
 o100 endif
----------------------------------------------------------------------
+----
 
 The value is read from the INI file once, and cached in the
 interpreter. These parameters are read-only - assigning a value will
@@ -660,24 +652,24 @@ contain lowercase characters can not be accessed from G-code.
 
 Example:
 
-[source,{ngc}]
----------------------------------------------------------------------
+[source,ngc]
+----
 (debug, #<_hal[motion-controller.time]>)
----------------------------------------------------------------------
+----
 
 Access of HAL items is read-only. Currently, only all-lowercase HAL
 names can be accessed this way.
 
 `EXISTS` can be used to test for the presence of a given HAL item:
 
-[source,{ngc}]
----------------------------------------------------------------------
+[source,ngc]
+----
 o100 if [EXISTS[#<_hal[motion-controller.time]>]]
   (debug, [motion-controller.time] exists: #<_hal[motion-controller.time]>)
 o100 else
   (debug, [motion-controller.time] does not exist)
 o100 endif
----------------------------------------------------------------------
+----
 
 This feature was motivated by the desire for stronger coupling between
 user interface components like `GladeVCP` and `PyVCP` to act as
@@ -787,7 +779,7 @@ It takes only one named parameter and returns 1 if it exists and 0 if it does
 not exist. It is an error if you use a numbered parameter or an expression.
 Here is an example for the usage of the EXISTS function:
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 o10 if [EXISTS[#<_global>]]
@@ -893,7 +885,7 @@ This can be confusing at first how this works in incremental mode.
 For example if you have the following program you might expect it to
 be a square pattern:
 
-[source,{ngc}]
+[source,ngc]
 ----
 F100 G1 @.5 ^90
 G91 @.5 ^90
@@ -913,7 +905,7 @@ image::images/polar01.png["Polar Spiral",align="center"]
 
 The following code will produce our square pattern:
 
-[source,{ngc}]
+[source,ngc]
 ----
 F100 G1 @.5 ^90
 G91 ^90
@@ -1024,7 +1016,7 @@ corresponding parameter. So, 'S100(set speed)F200(feed)' is OK while
 
 Here is an example of a commented program:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G0 (Rapid to start) X1 Y1
 G0 X1 Y1 (Rapid to start; but don't forget the coolant)
@@ -1256,7 +1248,7 @@ over from previous programs and from the MDI commands.
 
 .Example Preamble for a Mill
 
-[source,{ngc}]
+[source,ngc]
 ----
 G17 G20 G40 G49 G54 G80 G90 G94
 ----
diff --git a/docs/src/gcode/rs274ngc.adoc b/docs/src/gcode/rs274ngc.adoc
index d67b236f3ef..e92d92a28f7 100644
--- a/docs/src/gcode/rs274ngc.adoc
+++ b/docs/src/gcode/rs274ngc.adoc
@@ -4,11 +4,6 @@
 [[cha:rs274ngc-programs]]
 = RS274/NGC Differences
 
-// 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}
 
 == Changes from RS274/NGC
 
@@ -52,7 +47,7 @@ LinuxCNC only moves the named axes. This is common on other machine
 controls. To move some axes to an intermediate point and then
 move all axes to the predefined point, write two lines of G code:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G0 X- Y- (axes to move to intermediate point)
 G28 (move all axes to predefined point)
diff --git a/docs/src/gcode/tool-compensation.adoc b/docs/src/gcode/tool-compensation.adoc
index d67fdeb59b5..1a64946d36a 100644
--- a/docs/src/gcode/tool-compensation.adoc
+++ b/docs/src/gcode/tool-compensation.adoc
@@ -4,12 +4,6 @@
 [[cha:tool-compensation]]
 = Tool Compensation
 
-// 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}
-
 (((Tool Compensation)))
 
 [[sec:touch-off]]
@@ -213,7 +207,7 @@ Information about configuring a LinuxCNC tool changer is in the <>
 
 The most common is to use a x86 computer (standard Intel / AMD computer)
 
 ARM computers such as the Raspberry Pi or Orange Pi can be used
 
-= Hardware Interface to CNC machine
+== Hardware Interface to CNC machine
 An interface is necessary to transmit (and convert) signals and information between LinuxCNC (the software on the computer) and CNC hardware (such as stepper / servo drivers, limit switches, inputs and outputs etc.). There are multiple different ways to interface.
 
 Interfaces include:
diff --git a/docs/src/getting-started/updating-linuxcnc.adoc b/docs/src/getting-started/updating-linuxcnc.adoc
index c671778b709..006f8f233ea 100644
--- a/docs/src/getting-started/updating-linuxcnc.adoc
+++ b/docs/src/getting-started/updating-linuxcnc.adoc
@@ -4,12 +4,6 @@
 [[cha:updating-linuxcnc]]
 = Updating LinuxCNC
 
-// 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}
-
 Updating LinuxCNC to a new minor release (ie to a new version in
 the same stable series, for example from 2.9.7 to 2.9.8) is an
 automatic process if your PC is connected to the internet. You will
diff --git a/docs/src/gui/axis.adoc b/docs/src/gui/axis.adoc
index cf37dcf03cd..81c50d8e6d5 100644
--- a/docs/src/gui/axis.adoc
+++ b/docs/src/gui/axis.adoc
@@ -4,12 +4,6 @@
 [[cha:axis-gui]]
 = AXIS GUI
 
-// 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}
-
 (((AXIS GUI)))
 
 == Introduction
@@ -45,7 +39,7 @@ Configuration Chapter.
   (will accept time in seconds (.05 -.2) for legacy reasons -
   milliseconds preferred to match other screens).
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 CYCLE_TIME = 100
@@ -57,7 +51,7 @@ CYCLE_TIME = 100
   display. Specifying 0 or leaving the setting out results in no
   timeout.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 PREVIEW_TIMEOUT = 5
@@ -824,7 +818,7 @@ will be displayed in the text area, previewed in the display area, and
 executed by LinuxCNC when 'Run'. The following lines add support for the
 'image-to-gcode' converter included with LinuxCNC:
 
-[source,{ini}]
+[source,ini]
 ----
 [FILTER]
 PROGRAM_EXTENSION = .png,.gif Greyscale Depth Image
@@ -834,7 +828,7 @@ gif = image-to-gcode
 
 It is also possible to specify an interpreter:
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .py Python Script
 py = python
@@ -850,7 +844,7 @@ image::images/holes.png["Circular Holes",align="center"]
 If the environment variable AXIS_PROGRESS_BAR is set, then lines
 written to stderr of the form
 
-[source,{ini}]
+[source,ini]
 ----
 FILTER_PROGRESS=%d
 ----
@@ -1006,7 +1000,7 @@ This feature is enabled on an axis by altering the appropriate '[AXIS_x]' sectio
 
 Example:
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_Z]
 TOUCHOFF_ACTUAL = MINUS
diff --git a/docs/src/gui/filter-programs.adoc b/docs/src/gui/filter-programs.adoc
index c15ed1de3d9..9f3fa1e0bec 100644
--- a/docs/src/gui/filter-programs.adoc
+++ b/docs/src/gui/filter-programs.adoc
@@ -5,12 +5,6 @@
 
 == Introduction
 
-// 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}
-
 Most of LinuxCNC's screens have the ability to send loaded files through a
 'filter program' or use the filter program to make G-code.
 Such a filter can do any desired task: Something as simple as making sure
@@ -28,7 +22,7 @@ will be displayed in the text area, previewed in the display area, and
 executed by LinuxCNC when 'Run'. The following lines add support for the
 'image-to-gcode' converter included with LinuxCNC:
 
-[source,{ini}]
+[source,ini]
 ----
 [FILTER]
 PROGRAM_EXTENSION = .png,.gif Greyscale Depth Image
@@ -38,7 +32,7 @@ gif = image-to-gcode
 
 It is also possible to specify an interpreter:
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .py Python Script
 py = python
@@ -54,7 +48,7 @@ image::images/holes.png[align="center", alt="Circular Holes"]
 
 If the filter program sends lines to stderr of the form:
 
-[source,{ini}]
+[source,ini]
 ----
 FILTER_PROGRESS=10
 ----
diff --git a/docs/src/gui/gladevcp-libraries.adoc b/docs/src/gui/gladevcp-libraries.adoc
index 7e60b0102f6..f5645efbc2f 100644
--- a/docs/src/gui/gladevcp-libraries.adoc
+++ b/docs/src/gui/gladevcp-libraries.adoc
@@ -4,12 +4,6 @@
 [[cha:gladevcp-libraries]]
 = GladeVCP Library modules
 
-// 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}
-
 Libraries are prebuilt Python modules that give added features to GladeVCP.
 In this way you can select what features you want - yet don't have to build common ones yourself.
 
@@ -19,7 +13,7 @@ Info is a library to collect and filters data from the INI file.
 
 The available data and defaults:
 
-[source,{ini}]
+[source,ini]
 ----
 LINUXCNC_IS_RUNNING
 LINUXCNC_VERSION
diff --git a/docs/src/gui/gladevcp-panels.adoc b/docs/src/gui/gladevcp-panels.adoc
index 9dbf3378112..d686307f0a6 100644
--- a/docs/src/gui/gladevcp-panels.adoc
+++ b/docs/src/gui/gladevcp-panels.adoc
@@ -4,12 +4,6 @@
 [[cha:gladevcp:panels]]
 = GladeVCP Builtin Panels
 
-// 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}
-
 GladeVCP can be used to *create control panels* that interface with _HAL_ and/or the motion controller.
 
 [[sec:gladevcp:panels:builtin]]
@@ -39,7 +33,7 @@ The documentation and source code of the current version can be found here:
 
 **Modification of the INI file to use as embedded panel in Gmoccapy:**
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = gmoccapy
@@ -60,7 +54,7 @@ SUBROUTINE_PATH = ./macros:/usr/share/linuxcnc/nc_files/gtk_probe/
 
 **Example using dbounce with a Mesa card (HAL file):**
 
-[source,{hal}]
+[source,hal]
 ----
 # ---probe signal---
 loadrt dbounce names=dbounce.probe
@@ -81,7 +75,7 @@ This is a modification of the 2015 version of GTK Verser Probe. It moves the ele
 
 **Modification of the INI file to use as embedded panel in Gmoccapy:**
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = gmoccapy
@@ -105,7 +99,7 @@ Use only one such Probe Screen in one LCNC configuration.
 
 **Example using dbounce with a Mesa card (HAL file):**
 
-[source,{hal}]
+[source,hal]
 ----
 # ---probe signal---
 loadrt dbounce names=dbounce.probe
diff --git a/docs/src/gui/gladevcp.adoc b/docs/src/gui/gladevcp.adoc
index 9ac258e0007..b6a085afd49 100644
--- a/docs/src/gui/gladevcp.adoc
+++ b/docs/src/gui/gladevcp.adoc
@@ -10,14 +10,6 @@
 // - check wiki vs docs
 // - check other GladeVCP docs branch against this
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-// begin a listing of INI/HAL/NGC files like so:
-//[source,{ini}]
-//[source,{hal}]
-//[source,{ngc}]
-
 == What is GladeVCP?
 
 (((GladeVCP: Glade Virtual Control Panel)))
@@ -252,7 +244,7 @@ CAUTION: Do not add the GladeVCP HAL command file to the AXIS +[HAL]HALFILE=+ in
 
 Place the GladeVCP panel in the righthand side panel by specifying the following in the INI file:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # add GladeVCP panel where PyVCP used to live:
@@ -279,7 +271,7 @@ You may add arbitrary `gladevcp` options here, as long as they dont collide with
 
 It is possible to create a custom HAL component name by adding the +-c+ option:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # add GladeVCP panel where PyVCP used to live:
@@ -305,7 +297,7 @@ It might not be needed in your setup. The relative path specifier ../../nc_files
 
 To do so, edit your INI file and add to the DISPLAY and HAL sections of INI file as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # add GladeVCP panel as a tab next to Preview/DRO:
@@ -337,7 +329,7 @@ Make sure the UI file is the last option passed to GladeVCP in both the `GLADEVC
 
 To do add a GladeVCP tab to 'Touchy', edit your INI file as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # add GladeVCP panel as a tab
@@ -373,7 +365,7 @@ gladevcp gtk_verser_probe
 
 Embedding is the same, no filename extension, but other options are fine:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # add GladeVCP panel as a tab next to Preview/DRO:
diff --git a/docs/src/gui/gmoccapy.adoc b/docs/src/gui/gmoccapy.adoc
index 0802a8b8be1..25caed8e1bb 100644
--- a/docs/src/gui/gmoccapy.adoc
+++ b/docs/src/gui/gmoccapy.adoc
@@ -5,12 +5,6 @@
 [[cha:gmoccapy]]
 = GMOCCAPY
 
-// 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}
-:css: {basebackend@docbook:'':css}
 
 == Introduction
 
@@ -104,7 +98,7 @@ So let us take a closer look at the INI file and what you need to include to use
 [[gmoccapy:display-section]]
 === The DISPLAY Section
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = gmoccapy
@@ -185,7 +179,7 @@ You are able to execute complete CNC programs in MDI mode by just pushing one bu
 To do so, you first have to specify the search path for macros:
 
 [[gmocappy:rs274ngc]]
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 SUBROUTINE_PATH = macros
@@ -196,7 +190,7 @@ Several subroutine paths can be separated ":".
 Then you just have to add a section like this:
 
 .Configuration of Five Macros to be Shown in the MDI Button List
-[source,{ini}]
+[source,ini]
 ----
 [MACROS]
 MACRO = i_am_lost
@@ -230,7 +224,7 @@ If you have given several subroutine paths, they will be searched in the order o
 The first file found will be used.
 
 GMOCCAPY will also accept macros asking for parameters like:
-[source,{ini}]
+[source,ini]
 ----
 [MACROS]
 MACRO = go_to_position X-pos Y-pos Z-pos
@@ -238,7 +232,7 @@ MACRO = go_to_position X-pos Y-pos Z-pos
 
 The parameters must be separated by spaces.
 This example calls a file 'go_to_position.ngc' with the following content:
-[source,{ngc}]
+[source,ngc]
 ----
 ; Test file "go to position"
 ; will jog the machine to a given position
@@ -284,7 +278,7 @@ If you have never used a Glade panel, I recommend to read the excellent document
 
 .Embedded Tab Example
 
-[source,{ini}]
+[source,ini]
 ----
 EMBED_TAB_NAME = DRO
 EMBED_TAB_LOCATION = ntb_user_tabs
@@ -376,7 +370,7 @@ GMOCCAPY has the ability to create HAL driven user messages.
 To use them you need to introduce some lines in the [DISPLAY] section of the INI file.
 
 These three lines are needed to define a user pop up message dialog:
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_TEXT    = The text to be displayed, may be pango markup formatted
 MESSAGE_TYPE    = "status" , "okdialog" , "yesnodialog"
@@ -395,7 +389,7 @@ The following three dialog types are available:
 For more detailed information of the pins see <>.
 
 .Example of User Message Configuration
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_TEXT = This is a info-message test
 MESSAGE_TYPE = status
@@ -432,7 +426,7 @@ the GUI is displayed. The details of what may be written in the `~/.gmoccapyrc`
 to change during the development cycle.
 
 A configuration-specific Python file may be specified with an INI file setting
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 USER_COMMAND_FILE=filename.py
@@ -444,7 +438,7 @@ If this file is specified, this file is sourced just after the GMOCCAPY GUI is d
 The following example changes the size of the vertical buttons:
 .Example of .gmoccapyrc file
 [source,python]
------
+----
 self.widgets.vbtb_main.set_size_request(85,-1)
 BB_SIZE = (70, 70) # default = (90, 56)
 self.widgets.tbtn_estop.set_size_request(*BB_SIZE)
@@ -455,7 +449,7 @@ self.widgets.rbt_auto.set_size_request(*BB_SIZE)
 self.widgets.tbtn_setup.set_size_request(*BB_SIZE)
 self.widgets.tbtn_user_tabs.set_size_request(*BB_SIZE)
 self.widgets.btn_exit.set_size_request(*BB_SIZE)
------
+----
 
 The widget names can the looked up in the /usr/share/gmoccapy.glade file
 
@@ -465,7 +459,7 @@ Similar to the User command file it's possible to influence the appearance by ca
 If a file `~/.gmoccapy_css` exists, its contents are loaded into the stylesheet provider and are so being applied to the GUI.
 
 A configuration-specific CSS file may be specified with an INI file setting
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 USER_CSS_FILE=filename.css
@@ -476,7 +470,7 @@ Information what can be controlled by CSS can be found here: link:https://docs.g
 
 Here an example how the color of checked buttons can be set to yellow:
 .Example Yellow color for checked buttons
-[source,{css}]
+[source,css]
 ----
 button:checked {
     background: rgba(250,230,0,0.8);
@@ -492,7 +486,7 @@ The order is _VERBOSE_, _DEBUG_, _INFO_, _WARNING_, _ERROR_, _CRITICAL_.
 Default is _WARNING_, that means _WARNING_, _ERROR_ and _CRITICAL_ are printed.
 
 You can specify the log level in the INI file like this:
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = gmoccapy 
@@ -507,14 +501,14 @@ ERROR       -q
 ----
 
 .Example: Configure logging to print only errors
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = gmoccapy -q
 ----
 
 You can specify where to save the log file:
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 LOG_FILE = gmoccapy.log
@@ -531,7 +525,7 @@ The goal is to get a GUI that may be operated in a tool shop, completely/mostly
 ====
 You will have to do all connections to GMOCCAPY pins in your postgui.hal file.
 When GMOCCAPY is started, it creates the HAL pins for the GUI then it executes the post-GUI HAL file named in the INI file:
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 POSTGUI_HALFILE=
@@ -775,7 +769,7 @@ GMOCCAPY offers this HAL pin to toggle between turtle and rabbit jogging:
 === Jog Increment HAL Pins
 
 The jog increments given in the INI file like
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 INCREMENTS = 5mm 1mm .5mm .1mm .05mm .01mm
@@ -844,7 +838,7 @@ To add a user created message you need to add the message to the INI file in the
 See <>.
 
 .User Message Example (INI file)
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_TEXT = LUBE FAULT
 MESSAGE_TYPE = okdialog
@@ -859,7 +853,7 @@ To connect these new pins you need to do this in the postgui HAL file.
 Here are some example connections which connect the message signals to some place else in the HAL file.
 
 .Example Connection of User Messages (HAL file)
-[source,{hal}]
+[source,hal]
 ----
 net gmoccapy-lube-fault gmoccapy.messages.lube-fault
 net gmoccapy-lube-fault-waiting gmoccapy.messages.lube-fault-waiting
@@ -905,7 +899,7 @@ image::images/gmoccapy_manual_toolchange.png["Manual tool change",align="left"]
 
 Usually they are connected like this for a manual tool change:
 
-[source,{hal}]
+[source,hal]
 ----
 net tool-change gmoccapy.toolchange-change <= iocontrol.0.tool-change
 net tool-changed gmoccapy.toolchange-changed <= iocontrol.0.tool-changed
@@ -931,7 +925,7 @@ The tooloffset-x line is not needed on a mill, and will not be displayed on a mi
 
 To display the current offsets, the pins have to be connected like this in the postgui HAL file:
 
-[source,{hal}]
+[source,hal]
 ----
 net tooloffset-x gmoccapy.tooloffset-x <= motion.tooloffset.x
 net tooloffset-z gmoccapy.tooloffset-z <= motion.tooloffset.z
@@ -994,7 +988,7 @@ These pins are mostly used to be read from a G-code subroutine, so the code can
 Modify your INI file to include the following sections.
 
 .The RS274NGC Section
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 # is the sub, with is called when a error during tool change happens, not needed on every machine configuration
@@ -1010,7 +1004,7 @@ Make sure INI_VARS and HAL_PIN_VARS are not set to 0. They are set to 1 by defau
 The position of the tool sensor and the start position of the probing movement,
 all values are absolute coordinates, except MAXPROBE, which must be given in relative movement.
 
-[source,{ini}]
+[source,ini]
 ----
 [TOOLSENSOR]
 X = 10
@@ -1023,7 +1017,7 @@ MAXPROBE = -20
 This is not named TOOL_CHANGE_POSITION  on purpose - *canon uses that name and will interfere otherwise.*
 The position to move the machine before giving the change tool command. All values are in absolute coordinates.
 
-[source,{ini}]
+[source,ini]
 ----
 [CHANGE_POSITION]
 X = 10
@@ -1034,7 +1028,7 @@ Z = -2
 .The Python Section
 The Python plug ins serves interpreter and task.
 
-[source,{ini}]
+[source,ini]
 ----
 [PYTHON]
 # The path to start a search for user modules
@@ -1062,7 +1056,7 @@ to the directory specified as `SUBROUTINE_PATH`, see <
 G38.2 Z-4
@@ -1074,7 +1068,7 @@ You may want to modify this file to fit more your needs.
 
 Connect the tool probe in your HAL file like so:
 
-[source,{hal}]
+[source,hal]
 ----
 net probe  motion.probe-input <= 
 ----
@@ -1082,15 +1076,15 @@ net probe  motion.probe-input <= 
 The line might look like this:
 
 
-[source,{hal}]
--------
+[source,hal]
+----
 net probe  motion.probe-input <= parport.0.pin-15-in
--------
+----
 
 In your postgui.hal file add the following lines:
 
-[source,{hal}]
--------
+[source,hal]
+----
 # The next lines are only needed if the pins had been connected before
 unlinkp iocontrol.0.tool-change
 unlinkp iocontrol.0.tool-changed
@@ -1102,7 +1096,7 @@ net tool-change gmoccapy.toolchange-change <= iocontrol.0.tool-change
 net tool-changed gmoccapy.toolchange-changed => iocontrol.0.tool-changed
 net tool-prep-number gmoccapy.toolchange-number <= iocontrol.0.tool-prep-number
 net tool-prep-loop iocontrol.0.tool-prepare <= iocontrol.0.tool-prepared
--------
+----
 
 [[gmoccapy:settings-page]]
 == The Settings Page
@@ -1706,8 +1700,8 @@ Change that entry to MAX_VELOCITY = xxx.
 If you use a macro without movement, like this one:
 
 
-[source,{ngc}]
----------
+[source,ngc]
+----
  o sub
 
 G92.1
@@ -1718,15 +1712,15 @@ G10 L20 P0 X0 Y0
 
 o endsub
 m2
----------
+----
 
 GMOCCAPY will not see the end of the macro, because the interpreter needs to change its state to IDLE,
 but the macro does not even set the interpreter to a new state.
 To avoid that just add a G4 P0.1 line to get the needed signal.
 The correct macro would be:
 
-[source,{ngc}]
----------
+[source,ngc]
+----
  o sub
 
 G92.1
@@ -1739,6 +1733,6 @@ G4 P0.1
 
 o endsub
 m2
----------
+----
 
 // vim: set syntax=asciidoc:
diff --git a/docs/src/gui/gscreen.adoc b/docs/src/gui/gscreen.adoc
index f030dca6bee..7dfb2d2a9f4 100644
--- a/docs/src/gui/gscreen.adoc
+++ b/docs/src/gui/gscreen.adoc
@@ -4,11 +4,6 @@
 [[cha:gscreen]]
 = Gscreen
 
-// 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}
 
 == Introduction
 
@@ -410,7 +405,7 @@ interact with it.
 
 Under the [DISPLAY] heading:
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = gscreen -c tester
   options:
@@ -449,7 +444,7 @@ MESSAGE_TYPE:: specifies whether its a yes/no, ok, or status message
 
 Here is a sample INI code. It would be under the [DISPLAY] heading.
 
-[source,{ini}]
+[source,ini]
 ----
 # This just shows in the status bar and desktop notify popup.
 MESSAGE_BOLDTEXT = NONE
diff --git a/docs/src/gui/gui-dev-reference.adoc b/docs/src/gui/gui-dev-reference.adoc
index 865fd5d34d6..f126756f2dc 100644
--- a/docs/src/gui/gui-dev-reference.adoc
+++ b/docs/src/gui/gui-dev-reference.adoc
@@ -4,13 +4,6 @@
 [[cha:gui-dev-reference]]
 = GUI Development Reference
 
-// 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}
-:css: {basebackend@docbook:'':css}
-
 This document attempts to be a 'best practices' reference for general use screen development. +
 While it is possible to program just about anything to work with LinuxCNC, using a common frame work,
 language and configuration requirements allows easier transition between screens and more developers to maintain them. +
@@ -49,7 +42,7 @@ The most important of is specifying the name of the screen that the LinuxCNC scr
 The screen program usually recognizes switches such as to set full screen. +
 Title is for the window title and icon is used for iconizing the window.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = axis
@@ -62,7 +55,7 @@ If settable, this is how to set the cycle time of the display GUI. +
 This is often the update rate rather then sleep time between updates. +
 A value of 100 ms (0.1 s) is a common setting though a range of 50 - 200 ms is not unheard of.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 CYCLE_TIME = 100
@@ -72,7 +65,7 @@ CYCLE_TIME = 100
 If these functions are available in the screen here is how to specify the path to use. +
 These should reference from the current INI file, or allow '~' for the home folder, or allow use of absolute paths.
 
-[source,{ini}]
+[source,ini]
 ----
 MDI_HISTORY_FILE = mdi_history.txt
 PREFERENCE_FILE_PATH = gui.pref
@@ -85,7 +78,7 @@ The linear increments can be a mix of inches or millimeters. +
 Angular increments are specified in degrees. +
 The word 'continuous' is used to specify continuous jogging and probably should be added even if left out of the INI line.
 
-[source,{ini}]
+[source,ini]
 ----
 INCREMENTS = continuous, 10 mm, 1.0 mm, 0.10 mm, 0.01 mm, 1.0 inch, 0.1 inch, 0.01 inch
 ANGULAR_INCREMENTS = continuous, .5, 1, 45, 90, 360
@@ -96,7 +89,7 @@ The screen often needs to be adjusted based on machine type. Lathes have differe
 differently. Foam machine display the plot differently. +
 The old way to do this was adding switches LATHE = 1, FOAM = 1 etc
 
-[source,{ini}]
+[source,ini]
 ----
 MACHINE_TYPE_HINT = LATHE
 ----
@@ -105,7 +98,7 @@ MACHINE_TYPE_HINT = LATHE
 Overrides allows the user to adjust feed rate or spindle speed on the fly. Usually a slider or dial is used. +
 These settings are in percent.
 
-[source,{ini}]
+[source,ini]
 ----
 MAX_FEED_OVERRIDE       = 120
 MIN_SPINDLE_0_OVERRIDE    = 50
@@ -117,7 +110,7 @@ Most screens have slider controls to adjust the linear and angular jog speed rat
 These settings should be specified in machine units per minute for linear and degrees per minute for angular +
 'Default' refers to the starting rate when the screen is first loaded.
 
-[source,{ini}]
+[source,ini]
 ----
 DEFAULT_LINEAR_VELOCITY =
 MIN_LINEAR_VELOCITY =
@@ -133,7 +126,7 @@ Manual controls for spindle control could be, (or a combinations of) buttons, sl
 You can set limits that are less then the what the machine controller can utilize by setting these entries. +
 If your screen is capable of running multiple spindles, then should accept entries higher then the shown '_0_'.
 
-[source,{ini}]
+[source,ini]
 ----
 SPINDLE_INCREMENT = 100
 DEFAULT_SPINDLE_0_SPEED = 500
@@ -147,7 +140,7 @@ They can be specified like these compact examples. +
 NGC commands separated by colons are run to completion before the next. +
 The optional comma separates text for the button from the NGC code.
 
-[source,{ini}]
+[source,ini]
 ----
 [MDI_COMMAND_LIST]
 MDI_COMMAND_MACRO0 = G0 Z25;X0 Y0;Z0, Goto\nUser\nZero
@@ -162,7 +155,7 @@ PROGRAM_EXTENSION = .extension,.extension2[space]Description of extensions +
 The filter program definitions are such: +
 filter extension = program to run
 
-[source,{ini}]
+[source,ini]
 ----
 [FILTER]
 # Controls what programs are shown in the file manager:
@@ -183,7 +176,7 @@ Most screens will need some HAL pins. They need to be connected after the screen
 ==== Postgui Halfile
 These files should be run one after another in order, after all the GUI HAL pins have been made.
 
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 POSTGUI_HALFILE = keypad_postgui.hal
@@ -193,7 +186,7 @@ POSTGUI_HALFILE = vfd_postgui.hal
 ==== Postgui Halcmd
 These files should be run one after another in order, after all the POSTGUI files have been run.
 
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 POSTGUI_HALCMD = show pin qt
@@ -209,7 +202,7 @@ others only the native widget toolkit based panels. +
 Usually these are embedded in tabs or side panel widgets. +
 This is how to describe the optional title, loading command and location widget name: +
 
-[source,{ini}]
+[source,ini]
 ----
 EMBED_TAB_NAME=Vismach demo
 EMBED_TAB_COMMAND=qtvcp vismach_mill_xyz
@@ -220,7 +213,7 @@ User dialogs are used for popping up import information (usually errors), that t
 Some stay up till the problem is fixed, some require acknowledgement, others a yes/no choice. +
 A HAL I/O pin would pop up the dialog, the dialog would reset the I/O pin and set any response output pins.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MESSAGE_BOLDTEXT = This is an information message
@@ -234,7 +227,7 @@ MESSAGE_ICON = INFO
 This style gives multiple messages defined by a number. +
 This example shows 3 possible messages based around a VFD error number.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MULTIMESSAGE_ID = VFD
diff --git a/docs/src/gui/halui.adoc b/docs/src/gui/halui.adoc
index b94e8c0e861..37d92b8ff73 100644
--- a/docs/src/gui/halui.adoc
+++ b/docs/src/gui/halui.adoc
@@ -5,11 +5,6 @@
 [[cha:hal-user-interface]]
 = HAL User Interface
 
-// 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}
 
 == Introduction
 
@@ -20,7 +15,7 @@ is provided by a traditional GUI (AXIS, GMOCCAPY, QtDragon, etc.), is provided b
 The easiest way to add halui is to add the following to the [HAL]
 section of the INI file:
 
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 HALUI = halui
@@ -29,7 +24,7 @@ HALUI = halui
 An alternate way to invoke it (specially if you generate the configuration with StepConf) is to include the following in your `custom.hal` file. +
 Make sure you use the correct path to your INI file.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr halui -ini /path/to/inifile.ini
 ----
@@ -41,14 +36,14 @@ by the activation of a HAL pin.
 This is possible by adding MDI commands to the INI file in the [HALUI] section.
 Example:
 
-[source,{ini}]
+[source,ini]
 ----
 [HALUI]
 MDI_COMMAND = G0 X0
 MDI_COMMAND = G0 G53 Z0
 MDI_COMMAND = G28
 MDI_COMMAND = ocall
-...
+# ...
 ----
 
 When halui starts it will read the `MDI_COMMAND` fields in the INI and
@@ -62,7 +57,7 @@ control panels like shown in the example <> and <> G-codes.
 In the [HAL] section if you don't have a post gui file add the following and
 create a file called 'postgui.hal'.
 
-[source,{ini}]
+[source,ini]
 ----
 POSTGUI_HALFILE = postgui.hal
 ----
@@ -523,7 +518,7 @@ POSTGUI_HALFILE = postgui.hal
 In the 'postgui.hal' file add the following code to link the PyVCP button to the
 MDI command.
 
-[source,{hal}]
+[source,hal]
 ----
 net rth halui.mdi-command-00 <= pyvcp.rth-button
 ----
diff --git a/docs/src/gui/pyvcp.adoc b/docs/src/gui/pyvcp.adoc
index 30c8aae7c2f..f6d9782f58b 100644
--- a/docs/src/gui/pyvcp.adoc
+++ b/docs/src/gui/pyvcp.adoc
@@ -4,11 +4,6 @@
 [[cha:pyvcp]]
 = PyVCP
 
-// 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}
 
 == Introduction
 
@@ -66,7 +61,7 @@ For a list of widgets and their tags and options, see the
 Once you have created your panel, connecting HAL signals to and from
 the PyVCP pins is done with the halcmd:
 
-[source,{hal}]
+[source,hal]
 ----
 net    signal-name
 ----
@@ -92,7 +87,7 @@ In addition to or instead of displaying a PyVCP panel as described above,
 it is possible to display one or more PyVCP panels as embedded tabs in the AXIS GUI.
 This is achieved by the following in the `[DISPLAY]` section of the INI file:
 
-[source,{ini}]
+[source,ini]
 ----
 EMBED_TAB_NAME    = Spindle
 EMBED_TAB_COMMAND = pyvcp spindle.xml
@@ -125,7 +120,7 @@ and set the maximum value of the bar to 5000 (see < pyvcp.spindle-speed
 ----
@@ -171,7 +166,7 @@ This section describes how PyVCP panels can be displayed on their own with or wi
 
 To load a stand alone PyVCP panel with LinuxCNC use these commands:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn mypanel pyvcp -g WxH+X+Y -c mypanel panel_file.xml
 ----
@@ -201,14 +196,14 @@ GUI other than AXIS.
 
 To load a 'stand alone' PyVCP panel without LinuxCNC use this command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn mypanel pyvcp -g 250x500+800+0 -c mypanel mypanel.xml
 ----
 
 The minimum command to load a PyVCP panel is:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr pyvcp mypanel.xml
 ----
@@ -228,7 +223,7 @@ You must add the path name if the panel is not in the directory that the HAL scr
 An optional command to use if you want the panel to stop HAL from continuing commands / shutting down.
 After loading any other components you want the last HAL command to be:
 
-[source,{hal}]
+[source,hal]
 ----
 waitusr panelname
 ----
diff --git a/docs/src/gui/qtdragon.adoc b/docs/src/gui/qtdragon.adoc
index 8512b9d0f5f..692eac20a5d 100644
--- a/docs/src/gui/qtdragon.adoc
+++ b/docs/src/gui/qtdragon.adoc
@@ -5,9 +5,6 @@
 [[cha:qtdragon-gui]]
 = QtDragon GUI
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
 
 == Introduction
 
@@ -75,7 +72,7 @@ In the section `[DISPLAY]` change the `DISPLAY =` assignment to read:
 
 You can add `-v`, `-d`, `-i`, or `-q` for (respectably) verbose, debug, info or quiet output to the terminal.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DISPLAY = qtvcp qtdragon
@@ -89,7 +86,7 @@ It can use `~` for home directory or `WORKINGFOLDER` or `CONFIGFOLDER` to repres
 This example will save the file in the config folder of the launch screen.
 (Other options are possible see the QtVCP's screenoption widget docs.)
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 PREFERENCE_FILE_PATH = WORKINGFOLDER/qtdragon.pref
@@ -101,7 +98,7 @@ You can specify where to save history/logs. +
 These file names can be user selected. +
 In the section `[DISPLAY]` add:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MDI_HISTORY_FILE = mdi_history.dat
@@ -113,7 +110,7 @@ LOG_FILE = qtdragon.log
 
 These set qtdragon's override controls (1.0 = 100 percent):
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MAX_SPINDLE_0_OVERRIDE = 1.5
@@ -125,7 +122,7 @@ MAX_FEED_OVERRIDE       = 1.2
 
 Spindle control settings (in rpm and watts):
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 DEFAULT_SPINDLE_0_SPEED = 500
@@ -140,7 +137,7 @@ MAX_SPINDLE_POWER = 1500
 Set selectable jogging increments. +
 These increments can be user changed.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 INCREMENTS = Continuous, .001 mm, .01 mm, .1 mm, 1 mm, 1.0 inch, 0.1 inch, 0.01 inch
@@ -154,7 +151,7 @@ This will override the default sizes. +
 The grid selection box is shown when clicking the 'OPTN' button 
 on the graphics display.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 GRIDS = 0, .1 mm, 1 mm, 2 mm, 5 mm, 10 mm, .25 in, .5 in
@@ -164,7 +161,7 @@ GRIDS = 0, .1 mm, 1 mm, 2 mm, 5 mm, 10 mm, .25 in, .5 in
 
 Set jog speed controls (in units per second)
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MIN_LINEAR_VELOCITY     = 0
@@ -183,7 +180,7 @@ See `qtvcp/library/messages` for more information. +
 This example shows how to make a dialog that requires the user to select 'ok' to acknowledge and hide. +
 These dialogs could be used for such things as low lube oil warnings, etc.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MESSAGE_BOLDTEXT = This is the short text
@@ -195,7 +192,7 @@ MESSAGE_PINNAME = oktest
 
 Multimessages use an s32 HAL pin to pop multiple defined messages.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MULTIMESSAGE_ID = VFD
@@ -232,7 +229,7 @@ You also use `WINDOW` to create a pop up window that cab be shown/hidden with an
 
 ==== Embedding Vismach Mill
 .Sample adding a builtin panel to the utilities tab, i.e., a graphical animated machine using the vismach library.
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 EMBED_TAB_NAME = Vismach demo
@@ -245,7 +242,7 @@ EMBED_TAB_LOCATION = tabWidget_utilities
 This example panel is designed to display additional RS485 VFD data and also to configure a 4 sheave, 2 belt spindle drive via a series of buttons.
 
 image::images/qtdragon_spindle_belts.png["QtDragon spindle_belts Panel - Spindle Belts VCP",align="center"]
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 EMBED_TAB_NAME = Spindle Belts
@@ -260,7 +257,7 @@ This sample is typical of what is needed for NgcGui, Basic Probe. and Versa Prob
 These paths will need to be adjusted to point to the actual files on your system.
 <>
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 SUBROUTINE_PATH = :~/linuxcnc/nc_files/examples/ngcgui_lib:~/linuxcnc/nc_files/examples/ngcgui_lib/utilitysubs: \
@@ -271,7 +268,7 @@ SUBROUTINE_PATH = :~/linuxcnc/nc_files/examples/ngcgui_lib:~/linuxcnc/nc_files/e
 QtVCP's NGCGUI program also need to know where to open for subroutine selection and pre-selection. +
 NGCGUI_SUBFILE_PATH must point to an actual path on your system and also a path described in SUBROUTINE_PATHS.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # NGCGUI subroutine path.
@@ -302,7 +299,7 @@ You can control what programs are displayed in the filemanager window with progr
 Create a line with the '.' endings you wish to use separated by commas, then a space and the description. +
 You can add multiple lines for different selections in the combo box.
 
-[source,{ini}]
+[source,ini]
 ----
 [FILTER]
 PROGRAM_EXTENSION = .ngc,.nc,.tap G-Code file (*.ngc,*.nc,*.tap)
@@ -320,7 +317,7 @@ This output is what will be displayed in the text area, previewed in the display
 
 The following lines add support for the `image-to-gcode` converter included with LinuxCNC and running Python based filter programs:
 
-[source,{ini}]
+[source,ini]
 ----
 [FILTER]
 PROGRAM_EXTENSION = .png,.gif,.jpg Greyscale Depth Image
@@ -341,7 +338,7 @@ Comment/uncomment which ever you prefer.
 
 Both perform similar probing routines, though Versa probe optionally handles auto tool measurement.
 
-[source,{ini}]
+[source,ini]
 ----
 [PROBE]
 #USE_PROBE = versaprobe
@@ -354,7 +351,7 @@ By default, LinuxCNC does not report an abort in a useful way for the probe rout
 You need to add a ngc file to print out an error that can be detected.
 <>
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 # on abort, this ngc file is called. required for basic/versa probe routines. +
@@ -364,7 +361,7 @@ ON_ABORT_COMMAND=O  call
 This example code will send a message on abort. The probe routines can detect this sample. +
 According to the setting above, it would need to be saved as 'on_abort.ngc' within LinuxCNC's [RS274NGC] SUBROUTINE_PATHS and [DISPLAY] PROGRAM_PREFIX search paths.
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 
@@ -389,7 +386,7 @@ m2
 You should set default M/G code for start up. These will be overridden by running a NGC file. +
 These are only sample codes, integrator should choose appropriate codes.
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 # start up G/M codes when first loaded
@@ -411,7 +408,7 @@ The buttons can require the mode to be preset to MDI or to automatically switch
 setting preferences on the settings page. +
 These commands can be run with external HAL pins, if using the hal_bridge component. See <>
 
-[source,{ini}]
+[source,ini]
 ----
 [MDI_COMMAND_LIST]
 # for macro buttons
@@ -445,7 +442,7 @@ You can add multiple line for multiple file. Each one will be called in the orde
 Calling HAL files after QtDragon is already loaded assures that QtDragon's HAL pins are available.
 
 .Sample with typical entries for the specificion of HAL files to be read after the QtDragon was started. Adjust these lines to match actual requirements.
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 POSTGUI_HALFILE = qtdragon_hd_postgui.hal
@@ -459,7 +456,7 @@ You can add multiple line. Each one will be called in the order they appear. +
 Any HAL command can be used.
 
 .Sample with typical files in INI file to load modules after the GUI is available. Adjust these to match your actual requirements.
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 POSTGUI_HALCMD = loadusr qtvcp test_probe
@@ -483,7 +480,7 @@ setting preferences on the settings page.
 - ok/cancel of dialogs and notify (error) messages
 
 .Sample entry. Remove '-d' to quiet debugging messages.
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 HALBRIDGE= hal_bridge -d
@@ -564,7 +561,7 @@ There are of course are many more HAL pins that must be connected for LinuxCNC t
 If you need a manual tool change prompt, add these lines in your postgui file. +
 QtDragon emulates the hal_manualtoolchange HAL pins - don't load the separate HAL component 'hal_manualtoolchange'.
 
-[source,{hal}]
+[source,hal]
 ----
 net tool-change      hal_manualtoolchange.change   <=  iocontrol.0.tool-change
 net tool-changed     hal_manualtoolchange.changed  <=  iocontrol.0.tool-changed
@@ -573,14 +570,14 @@ net tool-prep-number hal_manualtoolchange.number   <=  iocontrol.0.tool-prep-num
 
 Also if you don't have an automatic tool changer make sure these pins are connected in one of the HAL files:
 
-[source,{hal}]
+[source,hal]
 ----
 net tool-prepare-loopback iocontrol.0.tool-prepare => iocontrol.0.tool-prepared
 ----
 
 This input pin should be connected to indicate probe state.
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.led-probe
 ----
@@ -589,7 +586,7 @@ These pins are inputs related to spindle VFD indicating. +
 The volt and amp pins are used to calculate spindle power.
 You must also set the MAX_SPINDLE_POWER in the INI.
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.spindle-modbus-connection
 qtdragon.spindle-modbus-errors
@@ -601,7 +598,7 @@ qtdragon.spindle-volts
 This bit pin is an output to the spindle control to pause it. +
 You would connect it to `spindle.0.inhibit`.
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.spindle-inhibit
 ----
@@ -611,28 +608,28 @@ QtDragon spindle speed display and spindle-at-speed LED require that
 Encoder or VFD feedback could be used, as long as the feedback is in revolutions per second (RPS). +
 If no feedback is available you can have the display show the requested speed by connecting pins like so:
 
-[source,{hal}]
+[source,hal]
 ----
 net spindle-speed-feedback spindle.0.speed-out-rps => spindle.0.speed-in
 ----
 
 This bit output pin can be connected to turn on a laser:
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.btn-laser-on
 ----
 
 This float output pin indicates the camera rotation in degrees:
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.cam-rotation
 ----
 
 These bit/s32/float pins are related to external offsets if they are used:
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.eoffset-clear
 qtdragon.eoffset-enable
@@ -644,7 +641,7 @@ qtdragon.eoffset-is-active
 
 These float output pins reflect the current slider jograte (in machine units):
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.slider-jogspeed-linear
 qtdragon.slider-jogspeed-angular
@@ -652,7 +649,7 @@ qtdragon.slider-jogspeed-angular
 
 These float output pins reflect the current slider override rates:
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.slider-override-feed
 qtdragon.slider-override-maxv
@@ -663,7 +660,7 @@ qtdragon.slider-override-spindle
 These output pins are available when setting the Versa Probe INI option.
 They can be used for auto-tool-length-probe at tool change - with added remap code.
 
-[source,{hal}]
+[source,hal]
 ----
 qtversaprobe.enable
 qtversaprobe.blockheight
@@ -676,7 +673,7 @@ qtversaprobe.backoffdist
 This pin will be true when the loaded tool equals the number set in the Versa Probe tool number in the preference file. +
 It can be used (for example) to inhibit the spindle when the probe is loaded by connecting it to `spindle.0.inhibit`.
 
-[source,{hal}]
+[source,hal]
 ----
 qtversaprobe.probe-loaded
 ----
@@ -685,20 +682,20 @@ This output pin is available when setting the Basic Probe INI option. +
 This pin will be true when the loaded tool equals the number set in the Basic Probe tool number edit box. +
 It can be used (for example) to inhibit the spindle when the probe is loaded by connecting it to `spindle.0.inhibit`.
 
-[source,{hal}]
+[source,hal]
 ----
 qtbasicprobe.probe-loaded
 ----
 
 This input pin is available to toggle pause/resume of a running program.
 
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.external-pause
 ----
 
 You can externally operate dialog responses on most qtdragon dialogs.
-[source,{hal}]
+[source,hal]
 ----
 qtdragon.dialog-ok
 qtdragon.dialog-no
@@ -717,7 +714,7 @@ If your machine requires manual tool changes, QtDragon can pop a message box to
 QtDragon emulates the hal_manualtoolchange HAL pins - don't load the separate HAL component 'hal_manualtoolchange'.
 Hereto you must connect the proper HAL pin in the postgui HAL file, for example:
 
-[source,{hal}]
+[source,hal]
 ----
 net tool-change      hal_manualtoolchange.change   <=  iocontrol.0.tool-change
 net tool-changed     hal_manualtoolchange.changed  <=  iocontrol.0.tool-changed
@@ -756,7 +753,7 @@ This optional behaviour requires additions to the INI and the QtDragon_postgui H
 
 In the INI, under the AXIS_Z heading.
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_Z]
 OFFSET_AV_RATIO  = 0.2
@@ -766,7 +763,7 @@ This will limit max velocity of the machine by 20% +
 
 In the qtdragon_postgui.hal file add:
 
-[source,{hal}]
+[source,hal]
 ----
 # Set up Z axis external offsets
 net eoffset_clear    qtdragon.eoffset-clear          =>  axis.z.eoffset-clear
@@ -832,7 +829,7 @@ This is only available in the QtDragon_hd version.
 If you use auto raise Z to lift the spindle on pause, you must combine the two with a HAL component and feed that to LinuxCNC's motion component.
 
 .Sample postgui HAL file for combined spindle raise and Z Level compensation
-[source,{hal}]
+[source,hal]
 ----
 # load components
 ########################################################################
@@ -1006,7 +1003,7 @@ Pressing the stop button or the keyboard escape key, will abort the probing.
 This can be used to inhibit the spindle when the probe is loaded. +
 You would connect it to spindle.0.inhibit
 
-[source,{hal}]
+[source,hal]
 ----
 qtbasicprobe.probe-loaded
 ----
@@ -1229,10 +1226,12 @@ This is only available in the QtDragon_hd version.
 * displays this help file.
 
 [NOTE]
+====
 * Any 2 points within the machine operating volume can be specified.
 * If the first point is higher than the second, the calculated height will be a positive number.
 * If the first point is lower than the second, the calculated height will be a negative number.
 * Units are irrelevant in this program. The probed values are not saved and only the difference is reported.
+====
 
 [CAUTION]
 Setting incorrect values can lead to crashes into fixtures on the machine work surface.
@@ -1259,7 +1258,7 @@ Modify your INI file to include the following:
 QtDragon allows you to select one of two styles of touch probe routines.
 Versa probe works with a M6 remap to add auto tool probing.
 
-[source,{ini}]
+[source,ini]
 ----
 [PROBE]
 #USE_PROBE = versaprobe
@@ -1275,7 +1274,7 @@ USE_PROBE = basicprobe
 These default entries should work fine in most situations. Some systems may need to use 'linuxcnc/nc_files/examples/'
 instead of 'linuxcnc/nc_files/'. please check that paths are valid. Custom entries pointing to modified file are possible.
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 
@@ -1317,7 +1316,7 @@ Z_MAX_CLEAR is the Z position to go to before moving to the tool setter when usi
 . rapid move to [VERSA_TOOLSETTER] Z position.
 
 Example settings:
-[source,{ini}]
+[source,ini]
 ----
 [VERSA_TOOLSETTER]
 X = 10
@@ -1334,7 +1333,7 @@ The position to which to move the machine before giving the change tool command.
 All values are in absolute coordinates.
 All values are in machine native units.
 
-[source,{ini}]
+[source,ini]
 ----
 [CHANGE_POSITION]
 X = 10
@@ -1348,7 +1347,7 @@ The Python section sets up what files LinuxCNC's Python interpreter looks for, e
 These default entries should work fine in most situations. Some systems may need to use 'linuxcnc/nc_files/examples/' instead of 'linuxcnc/nc_files/'.
 Custom entries pointing to modified file are possible.
 
-[source,{ini}]
+[source,ini]
 ----
 # The path start point for all remap searches, i.e. Python's sys.path.append()
 PATH_APPEND = ~/linuxcnc/nc_files/remap_lib/python-stdglue/python
@@ -1361,7 +1360,7 @@ TOPLEVEL = ~/linuxcnc/nc_files/remap_lib/python-stdglue/python/toplevel.py
 Make sure to connect the tool probe input in your HAL file:
 If connected properly, you should be able to toggle the probe LED in QtDragon if you press the probe stylus.
 
-[source,{hal}]
+[source,hal]
 ----
 net probe  motion.probe-input <= 
 ----
@@ -1639,7 +1638,7 @@ Sometimes these lines will be present and you can change them, otherwise you wil
 
 For instance, to change the DRO font (look for this entry and change the font name):
 
-[source,{ini}]
+[source,ini]
 ----
 DROLabel,
 StatusLabel#status_rpm {
@@ -1651,7 +1650,7 @@ StatusLabel#status_rpm {
 
 To change the DRO display font and display format:
 
-[source,{ini}]
+[source,ini]
 ----
 DROLabel {
     font: 25pt "Lato Heavy";
@@ -1671,7 +1670,7 @@ DROLabel {
 
 Change the axis select button's click menu items:
 
-[source,{ini}]
+[source,ini]
 ----
 AxisToolButton {
     /* Adjust all the menu options */
@@ -1686,7 +1685,7 @@ AxisToolButton {
 
 To change the text of the mist button to 'air' (add these lines)
 
-[source,{ini}]
+[source,ini]
 ----
 #action_mist{
     qproperty-true_state_string: "Air\\nOn";
@@ -1696,7 +1695,7 @@ To change the text of the mist button to 'air' (add these lines)
 
 To change the Offsets display font and format:
 
-[source,{ini}]
+[source,ini]
 ----
 ToolOffsetView {
     font: 20pt "Lato Heavy";
@@ -1714,7 +1713,7 @@ OriginOffsetView {
 
 To stop the blur effect with dialogs:
 
-[source,{ini}]
+[source,ini]
 ----
 #screen_options {
     qproperty-focusBlur_option: false;
@@ -1722,7 +1721,7 @@ To stop the blur effect with dialogs:
 ----
 
 To change status highlight/selection colors:
-[source,{ini}]
+[source,ini]
 ----
 #screen_options {
     qproperty-user1Color: white;     /*  default status     */
@@ -1735,7 +1734,7 @@ To change status highlight/selection colors:
 
 Change the G-code text display colors/fonts:
 
-[source,{ini}]
+[source,ini]
 ----
 EditorBase{
 background:black;
@@ -1764,7 +1763,7 @@ qproperty-styleFont7: "Times,15,-1,5,90,0,0,1,1,0";
 
 To have the manual spindle buttons also incrementally increase/decrease speed:
 
-[source,{ini}]
+[source,ini]
 ----
 #action_spindle_fwd{
     qproperty-spindle_up_action: true;
diff --git a/docs/src/gui/qtvcp-code-snippets.adoc b/docs/src/gui/qtvcp-code-snippets.adoc
index 38bf68a9b40..814d71e0627 100644
--- a/docs/src/gui/qtvcp-code-snippets.adoc
+++ b/docs/src/gui/qtvcp-code-snippets.adoc
@@ -1065,7 +1065,7 @@ Calling this O-word will update the param 'toolToLoad' +
 This uses 'Python hot comment' to communicate with the embedded python instance. +
 See the Remap section of the Documents for a description.
 
-[source,{ngc}]
+[source,ngc]
 ----
 (filename myofile.ngc)
 o sub
diff --git a/docs/src/gui/qtvcp-custom-widgets.adoc b/docs/src/gui/qtvcp-custom-widgets.adoc
index a0f95ad5e54..4b2520a3e66 100644
--- a/docs/src/gui/qtvcp-custom-widgets.adoc
+++ b/docs/src/gui/qtvcp-custom-widgets.adoc
@@ -604,7 +604,7 @@ Here is a sample stylesheet to change text color based on home state.
 In this case any widget based on the HomeLabel widget above will change text color. +
 You would usually pick specific widgets using `HomeLabel #specific_widget_name[homed=true]`:
 
-[source,{css}]
+[source,css]
 ----
 HomeLabel[homed=true] {
     color: green;
@@ -634,7 +634,7 @@ class Label(QLabel):
 
 Sample stylesheet that sets a custom widget property.
 
-[source,{css}]
+[source,css]
 ----
 Label{
     qproperty-styleFont0: "Times,12,-1,0,90,0,0,0,0,0";
diff --git a/docs/src/gui/qtvcp-libraries.adoc b/docs/src/gui/qtvcp-libraries.adoc
index c175c95e866..1f8965d1521 100644
--- a/docs/src/gui/qtvcp-libraries.adoc
+++ b/docs/src/gui/qtvcp-libraries.adoc
@@ -4,12 +4,6 @@
 [[cha:qtvcp:libraries]]
 = QtVCP Libraries modules
 
-// 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}
-
 Libraries are *prebuilt Python modules that give added features to QtVCP*.
 In this way you can select what features you want - yet don't have to build common ones yourself.
 
@@ -1026,7 +1020,7 @@ Here are sample INI message definition code blocks that would be found under the
 
 * Status bar and desktop notify pop up message:
 +
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_BOLDTEXT = NONE
 MESSAGE_TEXT = This is a statusbar test
@@ -1037,7 +1031,7 @@ MESSAGE_PINNAME = statustest
 
 * Pop up dialog asking a Yes/No question:
 +
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_BOLDTEXT = NONE
 MESSAGE_TEXT = This is a yes no dialog test
@@ -1048,7 +1042,7 @@ MESSAGE_PINNAME = yndialogtest
 
 * Pop up dialog asking an OK answer + Status bar and desktop notification:
 +
-[source,{ini}]
+[source,ini]
 ----
 MESSAGE_BOLDTEXT = This is the short text
 MESSAGE_TEXT = This is the longer text of the both type test. It can be longer then the status bar text
@@ -1103,7 +1097,7 @@ This allows screen 'focus' dimming/blurring and sounds to be added to alerts.
 
 Here are sample INI message definition code blocks that would be found under the `[DISPLAY]` heading:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 MULTIMESSAGE_ID = VFD
diff --git a/docs/src/gui/qtvcp-vcp-panels.adoc b/docs/src/gui/qtvcp-vcp-panels.adoc
index e1027e4383d..1f1795cd084 100644
--- a/docs/src/gui/qtvcp-vcp-panels.adoc
+++ b/docs/src/gui/qtvcp-vcp-panels.adoc
@@ -4,12 +4,6 @@
 [[cha:qtvcp:panels]]
 = QtVCP Virtual Control Panels
 
-// 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}
-
 QtVCP can be used to *create control panels* that interface with _HAL_.
 
 [[sec:qtvcp:panels:builtin]]
@@ -28,7 +22,7 @@ Used for *copying QtVCP's builtin Screens/VCP Panels/QtVismach code to a folder*
 
 In a terminal run:
 
-[source,{hal}]
+[source,hal]
 ----
 qtvcp copy
 ----
@@ -81,7 +75,7 @@ EMBED_TAB_LOCATION=tabWidget_utilities
 
 Here is how to load `spindle_belt` from a HAL script:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp spindle_belts
 ----
@@ -109,7 +103,7 @@ The Python handler file also provides a useful template for any custom panel.
 - The output can be scaled with the `spinbox`.
 - A `combobox` can be used to automatically select and connect to a signal.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp test_dial
 ----
@@ -131,7 +125,7 @@ image::images/qtvcp_test_dial.png["QtVCP test_dial Panel - Test Dial VCP",align=
 
 Here is how to load `test_button` from a HAL script:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp test_button
 loadusr qtvcp -o 4 test_button
@@ -155,7 +149,7 @@ image::images/qtvcp_test_button.png["QtVCP test_button - Test Button VCP",align=
 
 Here is how to load `test_led` from a HAL script:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp test_led
 loadusr qtvcp -o 4 test_led
@@ -173,7 +167,7 @@ image::images/qtvcp_test_led.png["QtVCP test_dial Panel - Test LED VCP",align="c
 *Collection of useful widgets for testing HAL component*, including
 speech of LED state.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp test_panel
 ----
@@ -191,7 +185,7 @@ image::images/qtvcp-cam-align.png["QtVCP cam_align Panel - Camera Based Alignmen
 
 .Usage
 Add these lines to the INI file:
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 EMBED_TAB_NAME = cam_align
@@ -241,7 +235,7 @@ Mouse controls:
 * middle mouse double click - reset circle diameter
 
 To use the top buttons you have to assign a command (or a sub-routine). This could look like this:
-[source,{ini}]
+[source,ini]
 ----
 [MDI_COMMAND_LIST]
 MDI_COMMAND_CAM_ALIGN1=G10 L20 P1 X0 Y0,Set XY\nOrigin
@@ -261,14 +255,14 @@ The selection and control group boxes can be hidden if not needed by using the '
 If you want to hide both, use a comma between them with no spaces. +
 The '-a' option will make the panel always-on-top of all windows.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp sim_panel
 ----
 
 Here we load the panel with no MPG selection buttons and the always-on-top option.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp -a -o hide=groupBoxSelection sim_panel
 ----
@@ -281,7 +275,7 @@ image::images/qtvcp_sim_panel.png["QtVCP sim_panel - Simulated Controls Panel Fo
 
 *Manual tool change dialog* that gives tool description.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn tool_dialog qtvcp -o speak_on -o audio_on tool_dialog
 ----
@@ -307,7 +301,7 @@ These are also embed-able in other screens such as AXIS or GMOCCAPY.
 
 3D OpenGL view of a _3-Axis milling machine_.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_mill_xyz
 ----
@@ -321,7 +315,7 @@ image::images/qtvismach.png["QtVCP vismach_mill_xyz - 3-Axis Mill 3D View Panel"
 This particular panel shows how to define and connect the model parts in the handler file,
 rather then importing the pre-built model from QtVCP's vismach library.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_router_atc
 ----
@@ -333,7 +327,7 @@ image::images/qtvismach_router_atc.png["QtVCP vismach_router_atc - 3-Axis Gantry
 
 3D OpenGL view of a _SCARA based milling machine_.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_scara
 ----
@@ -345,7 +339,7 @@ image::images/qtvismach_scara.png["QtVCP vismach_scara - SCARA Mill 3D View Pane
 
 3D OpenGL view of a _3-Axis milling machine with an A axis/spindle_.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_millturn
 ----
@@ -357,7 +351,7 @@ image::images/qtvismach_millturn.png["QtVCP vismach_millturn - 4 Axis MillTurn 3
 
 3D OpenGL view of a _5-Axis gantry type milling machine_.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_mill_5axis_gantry
 ----
@@ -369,7 +363,7 @@ image::images/qtvismach_5axis_gantry.png["QtVCP vismach_mill_5axis_gantry - 5-Ax
 
 3D openGL view of a _6 joint robotic arm_.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp vismach_fanuc_200f
 ----
@@ -391,7 +385,7 @@ halrun -I -f my_panel.hal
 ----
 
 .Example HAL file loading a QtVCP panel
-[source,{hal}]
+[source,hal]
 ----
 # load realtime components
 loadrt threads
@@ -426,7 +420,7 @@ QtVCP panels can be embedded into most QtVCP screens and avoids problems such as
 === Embedding Commands
 A typical screen such as QtDragon will search the INI file under the heading [DISPLAY] for commands to embed a panel.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 EMBED_TAB_NAME=Embedding demo
@@ -459,7 +453,7 @@ If your panel is to be able to run independently and embedded, you must trap err
 (Note, main screen objects are not available in an independent panel.)
 
 E.g., this would use the panel's preference file if there is one.
-[source,{hal}]
+[source,hal]
 ----
 try:
     belt_en = self.w.PREFS_.getpref('Front_Belt_enabled', 1, int, 'SPINDLE_EXTRAS')
@@ -468,7 +462,7 @@ except:
 ----
 
 This would use the main screen preference file if there is one.
-[source,{hal}]
+[source,hal]
 ----
 try:
     belt_en = self.w.MAIN.PREFS_.getpref('Front_Belt_enabled', 1, int, 'SPINDLE_EXTRAS')
diff --git a/docs/src/gui/qtvcp-vismach.adoc b/docs/src/gui/qtvcp-vismach.adoc
index 2ce2e4dc8a9..472cbc817db 100644
--- a/docs/src/gui/qtvcp-vismach.adoc
+++ b/docs/src/gui/qtvcp-vismach.adoc
@@ -253,7 +253,7 @@ The *rotation axis and translation vector move with the part*:
   `hal_pin`;; The _name of the HAL pin_ that will animate the motion. +
     This needs to match an existing HAL pin that describes the joint position such as:
 +
-[source,{hal}]
+[source,hal]
 ----
 "joint.2.pos-fb"
 ----
diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc
index 1a75c744866..7a77946e41d 100644
--- a/docs/src/gui/qtvcp-widgets.adoc
+++ b/docs/src/gui/qtvcp-widgets.adoc
@@ -4,13 +4,6 @@
 [[cha:qtvcp:widgets]]
 = QtVCP Widgets
 
-// 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}
-:css: {basebackend@docbook:'':css}
-
 *`Qtscreen`* uses _QtVCP widgets_ for LinuxCNC integration.
 
 *Widget* is the general name for the _UI objects_ such as buttons and
@@ -212,7 +205,7 @@ pinType and pinName properties can not be changed in stylesheets.
 [NOTE]
 In style sheets, stepColorList is a single string of color names separated by commas.
 
-[source,{css}]
+[source,css]
 ----
 HalBar{
     qproperty-backgroundColor: #000;
@@ -297,7 +290,7 @@ self.w.halpadname.set_highlight(self.w.halpadname.LEFTRIGHT)
 .`HALPad` Styles
 The above properties could be set in _styles sheets_.
 
-[source,{css}]
+[source,css]
 ----
 HALPad{
     qproperty-on_color: #000;
@@ -416,7 +409,7 @@ A *LED like indicator* that optionally follows a HAL pin's logic.
 The `LED` properties can be defined in a _stylesheet_ with the following code added to the `.qss` file,
 `name_of_led` being the widget name defined in Qt Designer's editor:
 
-[source,{css}]
+[source,css]
 ----
 LED #name_0f_led{
   qproperty-color: red;
@@ -464,7 +457,7 @@ The `TabWidget` properties can be defined in a _stylesheet_ with the following c
 If you omit the '#name_of_tab' text, all TabWidgets tab height will be set. +
 This shows how to set a particular widget's tab height:
 
-[source,{css}]
+[source,css]
 ----
 TabWidget #name_of_tab{
   qproperty-tabsize: 1.5;
@@ -647,7 +640,7 @@ These set _attributes_ of the selected action (availability depends on the widge
   in the INI file, under the heading `[MDI_COMMAND_LIST]`. +
   Commands separated by the `;` will be run one after another +
   The button label text can be set with any text after a comma, the `\n` symbol adds a line break.
-[source,{ini}]
+[source,ini]
 ----
 [MDI_COMMAND_LIST]
 MDI_COMMAND_MACRO0 = G0 Z25;X0 Y0;Z0, Goto\nUser\nZero
@@ -741,7 +734,7 @@ These are the click-and-hold menu properties: +
 
 Here is a sample stylesheet entry:
 
-[source,{css}]
+[source,css]
 ----
 AxisToolButton {
     /* Modify all the menu options */
@@ -833,7 +826,7 @@ Here is a sample stylesheet entry that:
 * Then sets the text color based on the Qt `isHomed` property.
 * show all the menu options.
 
-[source,{css}]
+[source,css]
 ----
 DROLabel {
     font: 25pt "Lato Heavy";
@@ -861,7 +854,7 @@ DROLabel[isHomed=true] {
 
 Here is how you specify a particular widget by its `objectName` in Qt Designer:
 
-[source,{css}]
+[source,css]
 ----
 DROLabel #dr0_x_axis [isHomed=false] {
     color: yellow;
@@ -899,7 +892,7 @@ if temp[1]:
   Single clicking a folder (False) is enabled by default and is intended for touch screen users. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #filemanager {
     qproperty-doubleClickSelection: True;
@@ -911,7 +904,7 @@ if temp[1]:
   Table view (False) is enabled by default. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #filemanager {
     qproperty-showListView: True;
@@ -943,7 +936,7 @@ It has a _signal_ *`percentDone(int)`* that can be connected to a slot (such as
 The `GcodeDisplay` properties can be set in a stylesheet with the following code added to the .qss file
 (the following color choices are random).
 
-[source,{css}]
+[source,css]
 ----
 EditorBase{
     qproperty-styleColorBackground: lightblue;
@@ -1016,7 +1009,7 @@ This *displays the current G-code in a graphical form*.
 *`dro-font/dro-large-font`* _(string)_::
   Sets the small and large DRO font properties +
   Here we reference with the widget base name; GCodeGraphics
-[source,{css}]
+[source,css]
 ----
 GCodeGraphics{
     qproperty-dro_font:"monospace  bold 12";
@@ -1031,7 +1024,7 @@ GCodeGraphics{
   Valid choices for a lathe are p, y, y2. For other screens, valid choices are p, x, y, z, z2. +
   The following shows an example of how to set this property (referenced using the widget user selected name):
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_view: z;
@@ -1042,7 +1035,7 @@ GCodeGraphics{
   Determines whether or not to _show the DRO_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_dro: False;
@@ -1053,7 +1046,7 @@ GCodeGraphics{
   Determine whether or not to _show the Distance To Go_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_dtg: False;
@@ -1064,7 +1057,7 @@ GCodeGraphics{
   Determines whether or not to _show the units in metric by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_metric: False;
@@ -1075,7 +1068,7 @@ GCodeGraphics{
   Determines whether or not to _show the overlay by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_overlay: False;
@@ -1086,7 +1079,7 @@ GCodeGraphics{
   Determines whether or not to _show the offsets by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_offsets: False;
@@ -1097,7 +1090,7 @@ GCodeGraphics{
   Determines whether or not to _show the small origin by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_small_origin: False;
@@ -1108,7 +1101,7 @@ GCodeGraphics{
   Sets the _default overlay color_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-overlay_color: blue;
@@ -1119,7 +1112,7 @@ GCodeGraphics{
   Sets the _default overlay alpha value_. This affects the opacity of the overlay when set between 0.0 and 1.0. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-overlay_alpha: 0.15;
@@ -1130,7 +1123,7 @@ GCodeGraphics{
   Sets the _default background color_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-background_color: blue;
@@ -1141,7 +1134,7 @@ GCodeGraphics{
   Determines whether or not _use a gradient background by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-_use_gradient_background: False;
@@ -1152,7 +1145,7 @@ GCodeGraphics{
   Sets the _default jog color_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-jog_color: red;
@@ -1163,7 +1156,7 @@ GCodeGraphics{
   Sets the _default feed color_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-Feed_color: green;
@@ -1174,7 +1167,7 @@ GCodeGraphics{
   Sets the _default rapid color_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-Rapid_color: rgba(0, 0, 255, .5);
@@ -1185,7 +1178,7 @@ GCodeGraphics{
   Determines whether or not to _inhibit external controls by default_. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-InhibitControls:True;
@@ -1197,7 +1190,7 @@ GCodeGraphics{
   the preview. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-MouseButtonMode: 1;
@@ -1234,7 +1227,7 @@ Modes 6-11 are intended for machines that only require a 2D preview such as plas
   Determines whether or not to _invert the zoom direction_ when zooming with the mouse wheel. +
   The following shows an example of how to set this property:
 +
-[source,{css}]
+[source,css]
 ----
 #gcodegraphics{
     qproperty-MouseWheelInvertZoom:True;
@@ -1324,7 +1317,7 @@ It uses _images for visual representation_ of the macro and for an icon.
 
 It searches for special macros using the _INI definition_:
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 SUBROUTINE_PATH =
@@ -1335,7 +1328,7 @@ The first three lines _must_ have the keywords below, the fourth is optional.
 
 Here is a sample for the first four lines in an _O-word file_:
 
-[source,{ini}]
+[source,ini]
 ----
 ; MACROCOMMAND = Entry1,Entry2
 ; MACRODEFAULTS = 0,true
@@ -1352,7 +1345,7 @@ There will be *one for every variable required* in the O-word function.
 
 If the macro does not require variables, leave it empty:
 
-[source,{ini}]
+[source,ini]
 ----
 ; MACROCOMMAND=
 ----
@@ -1382,7 +1375,7 @@ The images must be added to _SVG layers_ which are used to define the different
 +
 Value is comma separated list of three ordered fields:
 +
-[source,{ini}]
+[source,ini]
 ----
 ; MACROIMAGE=filename.svg,macro_layer_name[,icon_layer_name]
 ----
@@ -1400,7 +1393,7 @@ With:
 * *PNG/JPG Images*: +
   Value remains a comma separated list:
 +
-[source,{ini}]
+[source,ini]
 ----
 ; MACROIMAGE=macro_image.(png|jpg)[,icon_image.(png|jpg)]
 ----
@@ -1436,7 +1429,7 @@ It is a comma separated list of keyword and data, all of which are optional:
 
 Here are stylesheet hints for adjusting the MacroTab widget.
 
-[source,{css}]
+[source,css]
 ----
 MacroTab CustomButton{
     width: 20px;
@@ -1578,7 +1571,7 @@ The same MDILine embedded commands may be accessed from this widget.
 
 The history is _recorded on a file defined in the INI_ under the heading `[DISPLAY]` (this shows the default):
 
-[source,{ini}]
+[source,ini]
 ----
 MDI_HISTORY_FILE = '~/.axis_mdi_history'
 ----
@@ -1626,14 +1619,14 @@ The macro button _cycles though macros defined in the INI [DISPLAY] heading_.
 
 Add one or more `MACRO` lines of the following format:
 
-[source,{ini}]
+[source,ini]
 ----
 MACRO = macro_name [param1] [... paramN]
 ----
 
 In the example below, `increment` is the name of the macro, and it accepts two parameters, named `xinc` and `yinc`.
 
-[source,{ini}]
+[source,ini]
 ----
 MACRO = incerment xinc yinc
 ----
@@ -1643,7 +1636,7 @@ or into any directory in the `SUBROUTINE_PATH` specified in the INI file.
 
 Keeping on with the example above, it would be named `increment.ngc` and its content could look like:
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub
 G91 G0 X#1 Y#2
@@ -1721,7 +1714,7 @@ self.w.originoffsetview.setProperty('metric_template','%10.3f')
 ----
 * Or (if appropriate) in stylesheets
 +
-[source,{css}]
+[source,css]
 ----
 OriginOffsetView{
   qproperty-styleColorHighlist: lightblue;
@@ -2100,7 +2093,7 @@ self.w.screen_options.setProperty('play_sounds_option',False)
 * *In style sheets*: +
   Here we can reference the widget by Qt Designer user defined name or by widget class name.
 +
-[source,{css}]
+[source,css]
 ----
 /* red, green, blue 0-255, alpha 0-100% or 0.0 to 1.0 */
 /* the # sign is used to refer to Qt Designer defined widget name */
@@ -2254,7 +2247,7 @@ self.w.status_slider.setProperty('alertOver',100)
 
 * Or (if appropriate) in stylesheets.
 +
-[source,{css}]
+[source,css]
 ----
 /* warning colors for overrides if out of normal range*/
 /* widget object name is slider_spindle_ovr */
@@ -2326,7 +2319,7 @@ There are properties that can be changed:
 
 The LED properties can be defined in a stylesheet with the following code added to the `.qss` file. +
 
-[source,{css}]
+[source,css]
 ----
 State_LED #name_of_led{       <1>
   qproperty-color: red;
@@ -2465,7 +2458,7 @@ self.w.tooloffsetview.setProperty('metric_template','%10.3f')
 
 and in style sheets:
 
-[source,{css}]
+[source,css]
 ----
 ToolOffsetView{
   qproperty-styleColorHighlist: lightblue;
@@ -2722,10 +2715,11 @@ Additionally, there is a `machine_log_severity_option` property that may be chos
 
 Severity is conveyed via the `option` value sent along with the `STATUS` signal called `update-machine-log`.  The `option` parameter is a comma-delimited list, containing typically   
 
-```
+[source,python]
+----
 text = 'an error has occurred.'
 STATUS.emit('update-machine-log', text, 'TIME,ERROR')
-```
+----
 
 ==== Clearing the Log
 
@@ -2999,7 +2993,7 @@ The above properties could be set in:
   You would usually use the Qt Designer widget name with `#` _prefix_ to set individual widget properties,
   otherwise you would use the `JoyPad` _class name_ to set all `JoyPad` widgets the same:
 +
-[source,{css}]
+[source,css]
 ----
 #joypadname{
   qproperty-true_color: #000;
@@ -3072,7 +3066,7 @@ These properties are available to customize the indicator (not all are applicabl
 
 The LED indicator color can be defined in a _stylesheet_ with the following code added to the `.qss` file:
 
-[source,{css}]
+[source,css]
 ----
 Indicated_PushButton{
   qproperty-on_color: #000;
@@ -3082,7 +3076,7 @@ Indicated_PushButton{
 
 Or for a particular button:
 
-[source,{css}]
+[source,css]
 ----
 Indicated_PushButton #button_estop{
   qproperty-on_color: black;
@@ -3128,7 +3122,7 @@ Currently these status properties can be used to auto style buttons:
 
 Here is a sample stylesheet entry setting the background of mode button widgets when LinuxCNC is in that mode:
 
-[source,{css}]
+[source,css]
 ----
 ActionButton[isManual=true] {
     background: red;
@@ -3143,7 +3137,7 @@ ActionButton[isAuto=true] {
 
 Here is how you specify a particular widget by its objectName in Qt Designer:
 
-[source,{css}]
+[source,css]
 ----
 ActionButton #estop button [isEstopped=false] {
     color: yellow;
@@ -3183,7 +3177,7 @@ It uses the following properties to specify the text for each state:
 
 You can set/change these in stylesheets:
 
-[source,{css}]
+[source,css]
 ----
 ActionButton #action_aux{
   qproperty-true_state_string: "Air\\nOn";
@@ -3268,7 +3262,7 @@ QtVCP's version of NGC subroutine selector (Shown as used in QtDragon).
 LinuxCNC needs to know where to look to run the subroutines. +
 If the subroutine calls other subroutines or custom M codes, those paths must be added too.
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 SUBROUTINE_PATH = ~/linuxcnc/nc_files/examples/ngcgui_lib:~/linuxcnc/nc_files/examples/ngcgui_lib/utilitysubs
@@ -3277,7 +3271,7 @@ SUBROUTINE_PATH = ~/linuxcnc/nc_files/examples/ngcgui_lib:~/linuxcnc/nc_files/ex
 QtVCP needs to know where to open subroutines from. +
 You can also specify subroutines to be pre-opened in tabs.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 # NGCGUI subroutine path.
@@ -3312,7 +3306,7 @@ They must follow these rules:
 * Comments and presets may be included.
 * If an image file of the same name is in the folder, it will be shown.
 
-[source,{css}]
+[source,css]
 ----
 (info: feedrate -- simple example for setting feedrate)
 o sub
diff --git a/docs/src/gui/qtvcp.adoc b/docs/src/gui/qtvcp.adoc
index d74d1789fa8..62c3f3c1031 100644
--- a/docs/src/gui/qtvcp.adoc
+++ b/docs/src/gui/qtvcp.adoc
@@ -4,13 +4,6 @@
 [[cha:qtvcp]]
 = QtVCP
 
-// 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}
-:css: {basebackend@docbook:'':css}
-
 QtVCP is an *infrastructure to build custom CNC screens or control panels for LinuxCNC*.
 
 It displays a _`.ui` file built with Qt Designer_ screen editor
@@ -88,7 +81,7 @@ It does not add anything visually to the screen but, allows important details to
 
 If you are using QtVCP to make a CNC motion control screen (rather then a HAL based panel), in the INI file, in the `[DISPLAY]` section, add a line with the following pattern:
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = qtvcp  
 ----
@@ -127,7 +120,7 @@ QtVCP will first search the LinuxCNC configuration directory that was launched f
 
 .Cycle Times
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 CYCLE_TIME = 100
@@ -220,7 +213,7 @@ Stylesheets can be used to *set Qt properties*.
 If a widget uses properties then they usually can be modified by stylesheets.
 
 .Example of a widget with accompanying style sheet settings.
-[source,{css}]
+[source,css]
 ----
 State_LED #name_of_led{
   qproperty-color: red;
@@ -292,7 +285,7 @@ In the _INI file_ under the `[DISPLAY]` heading add *`USER_COMMAND_FILE = _PATH_
 _PATH_ can be any valid path.
 It can use `~` for home directory or `WORKINGFOLDER` or `CONFIGFOLDER` to represent QtVCP's idea of those directories, e.g.:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 USER_COMMAND_FILE = CONFIGFOLDER/
@@ -449,14 +442,14 @@ image::images/qtvismach.png["QtVismach - 3-Axis Mill Builtin Panel",align="cente
 
 You can load these from the terminal or from a HAL file with this basic command:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr qtvcp test_panel
 ----
 
 But more typically like this:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -Wn test_panel qtvcp test_panel
 ----
@@ -473,7 +466,7 @@ halrun -I -f my_panel.hal
 ----
 
 .Example HAL file loading a QtVCP panel
-[source,{hal}]
+[source,hal]
 ----
 # load realtime components
 loadrt threads
@@ -686,7 +679,7 @@ It does the minimum required to display the `tester.ui` defined screen and do ba
 
 If you are using QtVCP to make a CNC control screen, under the _INI file_ `[DISPLAY]` heading, set:
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = qtvcp 
 ----
diff --git a/docs/src/gui/tklinuxcnc.adoc b/docs/src/gui/tklinuxcnc.adoc
index 2743e4a507f..eb7e57cb45c 100644
--- a/docs/src/gui/tklinuxcnc.adoc
+++ b/docs/src/gui/tklinuxcnc.adoc
@@ -4,11 +4,6 @@
 [[cha:tklinuxcnc-intro]]
 = TkLinuxCNC GUI
 
-// 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}
 
 [[sec:tklinuxcnc-intro]]
 == Introduction
@@ -28,7 +23,7 @@ image::images/tkemc.png["TkLinuxCNC Window",align="center"]
 To select TkLinuxCNC as the front-end for LinuxCNC, edit the INI file.
 In the section '[DISPLAY]' change the 'DISPLAY' line to read
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = tklinuxcnc
 ----
diff --git a/docs/src/gui/tooledit.adoc b/docs/src/gui/tooledit.adoc
index 51a6e58feeb..c372d8f9d79 100644
--- a/docs/src/gui/tooledit.adoc
+++ b/docs/src/gui/tooledit.adoc
@@ -4,11 +4,6 @@
 [[cha:tooledit-gui]]
 = Tool Edit GUI
 
-// 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}
 
 == Overview
 
@@ -60,14 +55,14 @@ parameters, the columns displayed can be limited with the
 following INI file setting:
 
 .Syntax of INI file
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 TOOL_EDITOR = tooledit column_name column_name ...
 ----
 
 .Example for Z and DIAM columns
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 TOOL_EDITOR = tooledit Z DIAM
@@ -110,7 +105,7 @@ modified file with the ReRead button.
 
 The tool table is specified in the INI file with an entry:
 
-[source,{ini}]
+[source,ini]
 ----
 [EMCIO]TOOL_TABLE = tool_table_filename
 ----
@@ -121,7 +116,7 @@ a word processor).
 The AXIS GUI can optionally use an INI file setting to specify the tool
 editor program:
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]TOOL_EDITOR = path_to_editor_program
 ----
diff --git a/docs/src/gui/touchy.adoc b/docs/src/gui/touchy.adoc
index cbf707f5165..3370252ee6d 100644
--- a/docs/src/gui/touchy.adoc
+++ b/docs/src/gui/touchy.adoc
@@ -4,10 +4,6 @@
 [[cha:touchy-gui]]
 = The Touchy Graphical User Interface
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
-
 (((touchygui)))
 Touchy is a user interface for LinuxCNC meant for use on machine control panels,
 and therefore does not require keyboard or mouse.
@@ -106,7 +102,7 @@ Touchy can invoke O-word macros using the MDI interface.  To configure
 this, in the '[MACROS]' section of the INI file, add one or more 'MACRO'
 lines.  Each should be of the following format:
 
-[source,{ini}]
+[source,ini]
 ----
 MACRO=increment xinc yinc
 ----
@@ -119,7 +115,7 @@ Now, place the macro in a file named 'increment.ngc', in the
 
 It should look like:
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub
 G91 G0 X#1 Y#2
diff --git a/docs/src/hal/basic-hal.adoc b/docs/src/hal/basic-hal.adoc
index af2b5c3b9ce..f38c03e1696 100644
--- a/docs/src/hal/basic-hal.adoc
+++ b/docs/src/hal/basic-hal.adoc
@@ -4,12 +4,6 @@
 [[cha:basic-hal-reference]]
 = HAL Basics
 
-// 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}
-
 (((HAL Basics)))
 This document provides a reference to the basics of HAL.
 
@@ -34,7 +28,7 @@ Real time component functions need to be added to a thread to be updated at the
 You cannot load a non-realtime component into the realtime space.
 
 .loadrt Syntax and Example
-[source,{hal}]
+[source,hal]
 ----
 loadrt  
 loadrt mux4 count=1
@@ -92,7 +86,7 @@ Realtime Threads:
   This thread handles items that can tolerate a slower response, like the motion controller, ClassicLadder, and the motion command handler.
 
 .addf Syntax and Example
-[source,{hal}]
+[source,hal]
 ----
 addf  
 addf mux4.0 servo-thread
@@ -140,7 +134,7 @@ Flags may be one or more of the following:
 -n:: name a component when it is a valid option for that component.
 
 .Syntax and Examples of `loadusr`
-[source,{hal}]
+[source,hal]
 ----
 loadusr  
 loadusr halui
@@ -160,7 +154,7 @@ The optional direction arrows `<=`, `=>` and `<=>` make it easier to follow the
 The direction arrows must be separated by a space from the pin names.
 
 .Syntax and Examples of `net`
-[source,{hal}]
+[source,hal]
 ----
 net signal-name pin-name  
 net home-x joint.0.home-sw-in <= parport.0.pin-11-in
@@ -184,7 +178,7 @@ image::images/signal-direction.png["Signal Direction",align="center"]
 This example shows the signal xStep with the source being `stepgen.0.out` and with two readers, `parport.0.pin-02-out` and `parport.0.pin-08-out`.
 Basically the value of `stepgen.0.out` is sent to the signal xStep and that value is then sent to `parport.0.pin-02-out` and `parport.0.pin-08-out`.
 
-[source,{hal}]
+[source,hal]
 ----
 #   signal    source            destination          destination
 net xStep stepgen.0.out => parport.0.pin-02-out parport.0.pin-08-out
@@ -193,7 +187,7 @@ net xStep stepgen.0.out => parport.0.pin-02-out parport.0.pin-08-out
 Since the signal xStep contains the value of `stepgen.0.out` (the source) you can use the same signal again to send the value to another reader.
 To do this just use the signal with the readers on another line.
 
-[source,{hal}]
+[source,hal]
 ----
 #   signal       destination2
 net xStep => parport.0.pin-06-out
@@ -215,7 +209,7 @@ Parameters can be set before use or while running as needed.
 You cannot use setp on a pin that is connected to a signal.
 
 .Syntax and Examples of `setp`
-[source,{hal}]
+[source,hal]
 ----
 setp  
 setp parport.0.pin-08-out TRUE
@@ -228,7 +222,7 @@ setp parport.0.pin-08-out TRUE
 The command `sets` sets the value of a signal.
 
 .Syntax and Examples of `sets`
-[source,{hal}]
+[source,hal]
 ----
 sets  
 net mysignal and2.0.in0 pyvcp.my-led
@@ -250,7 +244,7 @@ If no signal was connected to the pin prior running the command, nothing happens
 The `unlinkp` command is useful for trouble shooting.
 
 .Syntax and Examples of `unlinkp`
-[source,{hal}]
+[source,hal]
 ----
 unlinkp 
 unlinkp parport.0.pin-02-out
@@ -267,7 +261,7 @@ These commands are included so older configurations will still work.
 The command `linksp` creates a 'connection' between a signal and one pin.
 
 .Syntax and Examples of `linksp`
-[source,{hal}]
+[source,hal]
 ----
 linksp  
 linksp X-step parport.0.pin-02-out
@@ -281,7 +275,7 @@ The command `linkps` creates a 'connection' between one pin and one signal.
 It is the same as `linksp` but the arguments are reversed.
 
 .Syntax and Examples of `linkps`
-[source,{hal}]
+[source,hal]
 ----
 linkps  
 linkps parport.0.pin-02-out X-Step
@@ -295,7 +289,7 @@ the command `newsig` creates a new HAL signal by the name __ and the da
 Type must be 'bit', 's32', 'u32', 's64', 'u64' or 'float'. Error if __ already exists.
 
 .Syntax and Examples of `newsig`
-[source,{hal}]
+[source,hal]
 ----
 newsig  
 newsig Xstep bit
@@ -534,7 +528,7 @@ xor2.n.out (bit, out)
 
 (((HAL Logic Examples)))
 .Example using `and2`
-[source,{hal}]
+[source,hal]
 ----
 loadrt and2 count=1
 addf and2.0 servo-thread
@@ -564,7 +558,7 @@ It's similar to 'binary coded decimal' but with more options.
 The 'hold' bit interrupts the input processing, so that the 'sum' value no longer changes.
 
 .Syntax for loading component `weighted_sum`
-[source,{hal}]
+[source,hal]
 ----
 loadrt weighted_sum wsum_sizes=size[,size,...]
 ----
@@ -574,7 +568,7 @@ Creates groups of ``weighted_sum``s, each with the given number of input bits (s
 To update the `weighted_sum`, the `process_wsums` must be attached to a thread.
 
 .Add `process_wsums` to servo thread
-[source,{hal}]
+[source,hal]
 ----
 addf process_wsums servo-thread
 ----
diff --git a/docs/src/hal/comp.adoc b/docs/src/hal/comp.adoc
index bb917eb2379..d382a70f475 100644
--- a/docs/src/hal/comp.adoc
+++ b/docs/src/hal/comp.adoc
@@ -4,12 +4,6 @@
 [[cha:hal-component-generator]]
 = HAL Component Generator
 
-// 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}
-
 (((HAL Component Generator)))
 
 == Introduction
@@ -498,7 +492,7 @@ For example, to allow up to 128 personality times:
 When using components with personality, normal usage is to specify a personality item for *each* specified component instance.
 Example for 3 instances of the logic component:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt logic names=and4,or3,nand5, personality=0x104,0x203,0x805
 ----
@@ -705,7 +699,7 @@ FUNCTION(_) {
 
 A typical load line for this component might be
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt logic count=3 personality=0x102,0x305,0x503
 ----
diff --git a/docs/src/hal/hal-examples.adoc b/docs/src/hal/hal-examples.adoc
index d908af261ba..faf1c5c9221 100644
--- a/docs/src/hal/hal-examples.adoc
+++ b/docs/src/hal/hal-examples.adoc
@@ -6,12 +6,6 @@
 
 (((HAL Examples)))
 
-// 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}
-
 All of these examples assume you are starting with a StepConf-based configuration and have two threads 'base-thread' and 'servo-thread'.
 The StepConf wizard will create an empty custom.hal and a custom_postgui.hal file.
 The custom.hal file will be loaded after the configuration HAL file and the custom_postgui.hal file is loaded after the GUI has been loaded.
@@ -87,7 +81,7 @@ A pin is provided for an external input to indicate the tool change is complete.
 
 This is an example of manual toolchange 'with' the HAL Manual Toolchange component:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -W hal_manualtoolchange
 net tool-change iocontrol.0.tool-change => hal_manualtoolchange.change
@@ -99,7 +93,7 @@ net tool-prepare-loopback iocontrol.0.tool-prepare => iocontrol.0.tool-prepared
 
 This is an example of manual toolchange 'without' the HAL Manual Toolchange component:
 
-[source,{hal}]
+[source,hal]
 ----
 net tool-number <= iocontrol.0.tool-prep-number
 net tool-change-loopback iocontrol.0.tool-change => iocontrol.0.tool-changed
@@ -118,7 +112,7 @@ Add the following to your custom.hal file.
 
 Load the realtime components.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt ddt count=1
 loadrt mult2 count=1
@@ -127,7 +121,7 @@ loadrt abs count=1
 
 Add the functions to a thread so it will get updated.
 
-[source,{hal}]
+[source,hal]
 ----
 addf ddt.0 servo-thread
 addf mult2.0 servo-thread
@@ -136,7 +130,7 @@ addf abs.0 servo-thread
 
 Make the connections.
 
-[source,{hal}]
+[source,hal]
 ----
 setp mult2.in1 60
 net xpos-cmd ddt.0.in
@@ -181,7 +175,7 @@ To find more information on these HAL components check the man pages.
 Place the following in a text file called softstart.hal.
 If you're not familiar with Linux place the file in your home directory.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt threads period1=1000000 name1=thread
 loadrt siggen
@@ -231,7 +225,7 @@ image::images/softstart-scope.png["Softstart screenshot"]
 To see the effect of changing the set point values of any of the components you can change them in the terminal window.
 To see what different gain settings do for lowpass just type the following in the terminal window and try different settings.
 
-[source,{hal}]
+[source,hal]
 ----
 setp lowpass.0.gain *.01
 ----
diff --git a/docs/src/hal/halmodule.adoc b/docs/src/hal/halmodule.adoc
index a34a198ca1a..7dfd229334b 100644
--- a/docs/src/hal/halmodule.adoc
+++ b/docs/src/hal/halmodule.adoc
@@ -85,7 +85,7 @@ The arguments are: pin name suffix, pin type, and pin direction.
 For parameters, the arguments are: parameter name suffix, parameter type, and parameter direction.
 
 .HAL Option Names
-[width="100%",cols="<3s,4*<"]
+[width="100%",cols="<3s,6*<"]
 |===
 |Pin and Parameter Types: |HAL_BIT |HAL_FLOAT |HAL_S32 |HAL_U32 |HAL_S64 |HAL_U64
 |Pin Directions:          |HAL_IN  |HAL_OUT   |HAL_IO  |        |        |
diff --git a/docs/src/hal/halshow.adoc b/docs/src/hal/halshow.adoc
index 6fce76ab21f..4e534084642 100644
--- a/docs/src/hal/halshow.adoc
+++ b/docs/src/hal/halshow.adoc
@@ -4,12 +4,6 @@
 [[sec:halshow]]
 == Halshow
 
-// 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}
-
 (((Halshow)))
 The script `halshow` can help you find your way around a running HAL.
 It displays chosen HAL values and updates them continuously.
@@ -228,14 +222,14 @@ Let's use this editor to add a differential module to a HAL and connect it to ax
 We first need to load a HAL component named ddt, add it to the servo thread, then connect it to the position pin of a joint.
 Once that is done we can find the output of the differentiator in halscope. So let's go.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt ddt
 ----
 
 Now look at the components node and you should see ddt in there someplace.
 
-[source,{hal}]
+[source,hal]
 ----
 Loaded HAL Components:
 ID Type        Name
@@ -272,7 +266,7 @@ Here we look for owner #08 and see a function named `ddt.0`.
 We should be able to add `ddt.0` to the servo thread and it will do its math each time the servo thread is updated.
 Once again we look up the addf command and find that it uses three arguments like this:
 
-[source,{hal}]
+[source,hal]
 ----
 addf   []
 ----
@@ -282,7 +276,7 @@ Here we see two threads, servo-thread and base-thread.
 The position of `ddt.0` in the thread is not critical.
 So we add the function `ddt.0` to the servo-thread:
 
-[source,{hal}]
+[source,hal]
 ----
 addf ddt.0 servo-thread
 ----
@@ -319,7 +313,7 @@ Owner Type  Dir Value       Name
 So it looks like Xpos-cmd should be a good signal to use.
 Back to the editor where we enter the following command:
 
-[source,{hal}]
+[source,hal]
 ----
 linksp Xpos-cmd ddt.0.in
 ----
diff --git a/docs/src/hal/haltcl.adoc b/docs/src/hal/haltcl.adoc
index 9208f5b7d02..db71f647b88 100644
--- a/docs/src/hal/haltcl.adoc
+++ b/docs/src/hal/haltcl.adoc
@@ -4,12 +4,6 @@
 [[cha:haltcl]]
 = HALTCL Files
 
-// 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}
-
 halcmd excels in specifying components and connections but these scripts offer no computational capabilities.
 As a result, INI files are limited in the clarity and brevity that is possible with higher level languages.
 
@@ -20,7 +14,7 @@ The .tcl extension is understood by the main script (`linuxcnc`) that processes
 Haltcl files are identified in the the HAL section of INI files (just like HAL files).
 
 .Example
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 HALFILE = conventional_file.hal
@@ -38,7 +32,7 @@ The halcmd language used in HAL files has a simple syntax that is actually a sub
 Haltcl files use the Tcl scripting language augmented with the specific commands of the LinuxCNC hardware abstraction layer (HAL).
 The HAL-specific commands are:
 
-[source,{hal}]
+[source,hal]
 ----
 addf, alias,
 delf, delsig,
@@ -68,19 +62,19 @@ list     hal list
 INI file variables are accessible by both `halcmd` and `haltcl` but with differing syntax.
 LinuxCNC INI files use SECTION and ITEM specifiers to identify configuration items:
 
-[source,{ini}]
+[source,ini]
 ----
 [SECTION_A]
 ITEM1 = value_1
 ITEM2 = value_2
-...
+# ...
 [SECTION_B]
-...
+# ...
 ----
 
 The INI file values are accessible by text substitution in HAL files using the form:
 
-[source,{hal}]
+[source,hal]
 ----
 [SECTION]ITEM
 ----
@@ -94,7 +88,7 @@ $::SECTION(ITEM)
 
 For example, an INI file item like:
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]
 MAX_VELOCITY = 4
@@ -115,7 +109,7 @@ In Tcl, this is written `[lindex $::SECTION(ITEM) 0]`.
 
 For example: given the following INI values
 
-[source,{ini}]
+[source,ini]
 ----
 [HOSTMOT2]
 DRIVER=hm2_eth
@@ -133,7 +127,7 @@ loadrt $::HOSTMOT2(DRIVER) board_ip=$::HOSTMOT2(IPADDR) config=$::HOSTMOT2(CONFI
 
 Here is the actual command that is run:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hm2_eth board_ip={"10.10.10.10"} config={"num_encoders=0 num_pwmgens=0 num_stepgens=6"}
 ----
@@ -190,7 +184,7 @@ Consider the topic of 'stepgen headroom'.
 Software `stepgen` runs best with an acceleration constraint that is "a bit higher" than the one used by the motion planner.
 So, when using `halcmd` files, we force INI files to have a manually calculated value.
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_0]
 MAXACCEL = 10.0
diff --git a/docs/src/hal/halui-examples.adoc b/docs/src/hal/halui-examples.adoc
index 72b72046946..2f237cc14cb 100644
--- a/docs/src/hal/halui-examples.adoc
+++ b/docs/src/hal/halui-examples.adoc
@@ -4,16 +4,10 @@
 [[cha:halui-examples]]
 = Halui Examples
 
-// 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}
-
 (((Halui Examples)))
 For any Halui examples to work you need to add the following line to the [HAL] section of the INI file.
 
-[source,{ini}]
+[source,ini]
 ----
 HALUI = halui
 ----
@@ -35,7 +29,7 @@ image::images/remote-start.png["Remote Start Example"]
 
 The hal commands needed to accomplish the above are:
 
-[source,{hal}]
+[source,hal]
 ----
 net program-start-btn halui.mode.auto and2.0.in0 <= 
 net program-run-ok and2.0.in1 <= halui.mode.is-auto
@@ -45,7 +39,7 @@ net remote-program-run halui.program.run <= and2.0.out
 Notice on line one that there are two reader pins, this can also be split
 up to two lines like this:
 
-[source,{hal}]
+[source,hal]
 ----
 net program-start-btn halui.mode.auto <= 
 net program-start-btn and2.0.in0
@@ -66,7 +60,7 @@ two lines that will be connected to your I/O to turn
 on the program pause or to resume when the external
 system wants LinuxCNC to continue.
 
-[source,{hal}]
+[source,hal]
 ----
 net ispaused halui.program.is paused => "your output pin"
 net resume halui.program.resume <= "your input pin"
diff --git a/docs/src/hal/intro.adoc b/docs/src/hal/intro.adoc
index ee9b1c611ae..7e611c72e9b 100644
--- a/docs/src/hal/intro.adoc
+++ b/docs/src/hal/intro.adoc
@@ -5,12 +5,6 @@
 
 = HAL Introduction
 
-// 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}
-
 (((HAL Introduction)))
 LinuxCNC is about interacting with hardware. But few users have the same exact hardware specifications - similar, but not the same.
 And even for the exact same hardware, there may be different ways to use it, say for different materials or with different mills, which would require adaptations to the control of an already running system.
@@ -184,7 +178,7 @@ image::images/hal_circuit_concept.png["HAL Circuit Concept",align="left"]
 
 Figure one would be written in HAL code like this:
 
-[source,{hal}]
+[source,hal]
 ----
 net signal-blue    component.0.pin1-in      component.1.pin1-out
 net signal-red     component.0.pin3-out     component.1.pin3-in     component.1.pin4-in
diff --git a/docs/src/hal/parallel-port.adoc b/docs/src/hal/parallel-port.adoc
index 5439c94927a..51e873b00e3 100644
--- a/docs/src/hal/parallel-port.adoc
+++ b/docs/src/hal/parallel-port.adoc
@@ -4,12 +4,6 @@
 [[cha:parport]]
 = Parallel Port Driver
 
-// 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}
-
 The hal_parport component is a driver for the traditional PC parallel port.
 The port has a total of 17 physical pins. The original parallel port divided those pins into three groups: data, control, and status.
 The data group consists of 8 output pins, the control group consists of 4 pins, and the status group consists of 5 input pins.
@@ -52,7 +46,7 @@ The hal_parport driver is a real time component so it must be loaded into the re
 The configuration string describes the parallel ports to be used, and (optionally) their types.
 If the configuration string does not describe at least one port, it is an error.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="port [type] [port [type] ...]"
 ----
@@ -67,7 +61,7 @@ A port of 0 is the first parallel port detected on the system, 1 is the next and
 
 This will use the first parallel port Linux detects:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0"
 ----
@@ -81,7 +75,7 @@ The directions are _in_, _out_, or _x_, and determine the direction of the physi
 If the direction is not specified, the data group will by default be configured as outputs. For example:
 
 .Command to load the real-time module 'hal_partport' with the additional __ to specify the port at which the parallel-port card is expected.
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0x278 0x378 in 0x20A0 out"
 ----
@@ -138,7 +132,7 @@ See the Note above about mode 'x'.
 
 This will enable two system-detected parallel ports, the first in output mode and the second in input mode:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0 out 1 in"
 ----
@@ -147,7 +141,7 @@ loadrt hal_parport cfg="0 out 1 in"
 
 You must also direct LinuxCNC to run the 'read' and 'write' functions.
 
-[source,{hal}]
+[source,hal]
 ----
 addf parport.0.read base-thread
 addf parport.0.write base-thread
@@ -183,7 +177,7 @@ From experimentation, I've found the first port (the on-card port) uses the thir
 and the second port (the one that attaches with a ribbon cable) uses the first address listed (b800).
 The following example shows the onboard parallel port and a PCI parallel port using the default out direction.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0x378 0xc000"
 ----
@@ -254,7 +248,7 @@ So that step can be asserted on every period in HAL and then toggled off by parp
 
 For example:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt hal_parport cfg="0x378 out"
 setp parport.0.reset-time 5000
@@ -297,7 +291,7 @@ Then use of this module will probably be necessary.
 
 Finally, HAL parport components should be loaded:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt probe_parport
 loadrt hal_parport ...
diff --git a/docs/src/hal/tools.adoc b/docs/src/hal/tools.adoc
index bf1b4ff3db2..933893fb71e 100644
--- a/docs/src/hal/tools.adoc
+++ b/docs/src/hal/tools.adoc
@@ -4,12 +4,6 @@
 [[cha:hal-tools]]
 = HAL Tools
 
-// 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}
-
 (((HAL Tools)))
 
 For most of the tools, a more detailed description can be found in the chapter <>
@@ -76,7 +70,7 @@ Multiple ``halmeter``s can be open at the same time.
 If you use a script to open multiple ``halmeter``s you can set the position of each one with `-g X Y` relative to the upper left corner of your screen.
 For example:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr halmeter pin hm2.0.stepgen.00.velocity-fb -g 0 500
 ----
@@ -284,7 +278,7 @@ or
 To generate the report for every LinuxCNC startup, include halreport and an output filename as an [APPLICATIONS]APP entry in the INI file.
 
 .halreport Example
-[source,{ini}]
+[source,ini]
 ----
 [APPLICATIONS]
 APP = halreport /tmp/halreport.txt
@@ -326,7 +320,7 @@ SIG:    motor-cmd-0
 
 In the example above, the HALFILE uses halcmd aliases to simplify pin names for an hostmot2 FPGA board with commands like:
 
-[source,{hal}]
+[source,hal]
 ----
 alias pin hm2_7i92.0.stepgen.00.position-fb h.00.position-fb
 ----
diff --git a/docs/src/hal/twopass.adoc b/docs/src/hal/twopass.adoc
index 1627a15277b..7fdc48fae2c 100644
--- a/docs/src/hal/twopass.adoc
+++ b/docs/src/hal/twopass.adoc
@@ -4,11 +4,6 @@
 [[cha:hal-twopass]]
 = HAL TWOPASS
 
-// 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}
 
 == TWOPASS
 
@@ -21,7 +16,7 @@ Normally, a set of one or more LinuxCNC configuration files must use a single, u
 For example, if you use a two-input AND gate component (and2) in three different places in your setup, you would need to have a single line somewhere to specify:
 
 .Example resulting in real-time components with default names `and2.0`, `and2.1`, `and2.2`.
-[source,{hal}]
+[source,hal]
 ----
 loadrt and2 count=3
 ----
@@ -30,7 +25,7 @@ loadrt and2 count=3
 Configurations are more readable if you specify with the `names=` option for components where it is supported, e.g.:
 
 .Example load command resulting in explicitly named components `aa`, `ab`, `ac`.
-[source,{hal}]
+[source,hal]
 ----
 loadrt and2 names=aa,ab,ac
 ----
@@ -39,7 +34,7 @@ It can be a maintenance problem to keep track of the components and their names,
 you must find and update the single loadrt directive applicable to the component.
 
 .TWOPASS processing is enabled by including an INI file parameter in the `[HAL]` section, where "anystring" can be any non-null string.
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 
@@ -48,7 +43,7 @@ TWOPASS = anystring
 
 With TWOPASS enabled, you can have multiple specifications like:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt and2 names=aa
 ...
@@ -64,7 +59,7 @@ The TWOPASS option can be specified with options to add output for debugging (ve
 The options are separated with commas.
 
 .Example
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 TWOPASS = on,verbose,nodelete
@@ -93,7 +88,7 @@ using the 'count=' method will give arcane component names like ddt.0, ddt.1, dd
 
 Alternatively, using the 'names=' option like:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt ddt names=xvel,yvel,zvel
 ...
@@ -113,7 +108,7 @@ Two-step processing occurs before the GUI is loaded.
 When using a [HAL]POSTGUI_HALFILE, it is convenient to place all the [HAL]POSTGUI_HALFILE loadrt declarations for the necessary components in a preloaded HAL file.
 
 .Example of a HAL section when using a POSTGUI_HALFILE
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 
@@ -136,15 +131,15 @@ include all loadrt items for components added by postgui HAL files in a separate
 The `addf` commands can also be included in the file.
 
 .Example
-[source,{ini}]
+[source,ini]
 ----
 [HAL]
 TWOPASS = on
 HALFILE = file_1.hal
-...
+# ...
 HALFILE = file_n.hal
 HALFILE = file_with_all_loads_for_postgui.hal
-...
+# ...
 POSTGUI_HALFILE = the_postgui_file.hal
 ----
 
diff --git a/docs/src/ladder/classic-ladder.adoc b/docs/src/ladder/classic-ladder.adoc
index 3501ab11739..6b2f9455aa8 100644
--- a/docs/src/ladder/classic-ladder.adoc
+++ b/docs/src/ladder/classic-ladder.adoc
@@ -4,12 +4,6 @@
 [[cha:cl-programming]]
 = ClassicLadder Programming
 
-// 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}
-
 (((ClassicLadder Programming,CL Programming)))
 
 == Ladder Concepts
@@ -58,7 +52,7 @@ Loading the ClassicLadder real time module (classicladder_rt) is possible from a
 The first line loads real time the ClassicLadder module. The second line adds the function classicladder.0.refresh to the servo thread.
 This line makes ClassicLadder update at the servo thread rate.
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt classicladder_rt
 addf classicladder.0.refresh servo-thread
@@ -109,7 +103,7 @@ numS32in and numS32out control how many HAL signed integers (+- integer range) p
 
 For example (you don't need all of these to change just a few):
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt classicladder_rt numRungs=12 numBits=100 numWords=10
 numTimers=10 numMonostables=10 numCounters=10 numPhysInputs=10
@@ -119,7 +113,7 @@ numS32in=5 numS32out=5
 
 To load the default number of objects:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt classicladder_rt
 ----
@@ -131,7 +125,7 @@ If you used the Stepper Config Wizard place any ClassicLadder HAL commands in th
 
 To load the non-realtime module:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr classicladder
 ----
@@ -140,7 +134,7 @@ NOTE: Only one .clp file can be loaded. If you need to divide your ladder then u
 
 To load a ladder file:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr classicladder myladder.clp
 ----
@@ -156,7 +150,7 @@ ClassicLadder Loading Options
 
 To use ClassicLadder with HAL without EMC:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -w classicladder
 ----
@@ -904,14 +898,14 @@ This is done by adding a couple of lines to the custom.hal file.
 
 This line loads the real time module:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt classicladder_rt
 ----
 
 This line adds the ClassicLadder function to the servo thread:
 
-[source,{hal}]
+[source,hal]
 ----
 addf classicladder.0.refresh servo-thread
 ----
@@ -972,7 +966,7 @@ Again if you used the StepConf Wizard to add ClassicLadder you can skip this ste
 To manually add a ladder you need to add add a line to your custom.hal file that will load your ladder file.
 Close your LinuxCNC session and add this line to your custom.hal file.
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -w classicladder --nogui MyLadder.clp
 ----
diff --git a/docs/src/ladder/ladder-examples.adoc b/docs/src/ladder/ladder-examples.adoc
index 2b752c74496..6f5df9be703 100644
--- a/docs/src/ladder/ladder-examples.adoc
+++ b/docs/src/ladder/ladder-examples.adoc
@@ -4,11 +4,6 @@
 [[cha:classicladder-examples]]
 = ClassicLadder Examples
 
-// 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}
 
 == Wrapping Counter
 
@@ -52,7 +47,7 @@ First we have to open the E-Stop loop in the main HAL file by
 commenting out by adding the pound sign as shown or removing the
 following lines.
 
-[source,{hal}]
+[source,hal]
 ----
 # net estop-out <= iocontrol.0.user-enable-out
 # net estop-out => iocontrol.0.emc-enable-in
@@ -61,7 +56,7 @@ following lines.
 Next we add ClassicLadder to our custom.hal file by adding these two
 lines:
 
-[source,{hal}]
+[source,hal]
 ----
 loadrt classicladder_rt
 addf classicladder.0.refresh servo-thread
@@ -78,7 +73,7 @@ estop.clp
 
 Now add the following line to your custom.hal file.
 
-[source,{hal}]
+[source,hal]
 ----
 # Load the ladder
 loadusr classicladder --nogui estop.clp
@@ -96,7 +91,7 @@ I/O assignments
 
 Next we add the following lines to the custom_postgui.hal file
 
-[source,{hal}]
+[source,hal]
 ----
 # E-Stop example using PyVCP buttons to simulate external components
 
diff --git a/docs/src/lathe/images/control-point_es.svg b/docs/src/lathe/images/control-point_es.svg
index 12b00560fcb..5292292debf 100644
--- a/docs/src/lathe/images/control-point_es.svg
+++ b/docs/src/lathe/images/control-point_es.svg
@@ -467,18 +467,17 @@
          x="212.70099"
          y="89.502655"
          style="font-size:18px;line-height:1.5;font-family:sans-serif">Punto de Control
-    tan    tan
+    > section for more details.
 
 To set up AXIS for Lathe Mode.
 
-[source,{ini}]
+[source,ini]
 ----
 [DISPLAY]
 
@@ -33,7 +27,7 @@ LATHE = TRUE
 Lathe Mode in AXIS does not set your default plane to G18 (XZ).
 You must program that in the preamble of each G-code file or (better) add it to your INI file, like this:
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 
diff --git a/docs/src/man/man9/hm2_7i43.9.adoc b/docs/src/man/man9/hm2_7i43.9.adoc
index 6dad644f519..26ea33f21c0 100644
--- a/docs/src/man/man9/hm2_7i43.9.adoc
+++ b/docs/src/man/man9/hm2_7i43.9.adoc
@@ -7,7 +7,7 @@ Anything IO board with HostMot2 firmware.
 
 == SYNOPSIS
 
-**loadrt hm2_7i43 [ ioaddr=**__N__[,_N_...] ] [ **ioaddr_hi=**__N__[,_N_...] ] [ **epp_wide=**__N__[,_N_...] ] [ **config="**__str[,str...]**"** ] [**debug_epp=**__N__[,_N_...] ]
+**loadrt hm2_7i43 [ ioaddr=**__N__[,_N_...] ] [ **ioaddr_hi=**__N__[,_N_...] ] [ **epp_wide=**__N__[,_N_...] ] [ pass:[config="]__str[,str...]pass:["] ] [**debug_epp=**__N__[,_N_...] ]
 
 ____
 *ioaddr* [default: 0 (parport0)]::
diff --git a/docs/src/man/man9/hm2_rpspi.9.adoc b/docs/src/man/man9/hm2_rpspi.9.adoc
index 82280d76777..766864e8061 100644
--- a/docs/src/man/man9/hm2_rpspi.9.adoc
+++ b/docs/src/man/man9/hm2_rpspi.9.adoc
@@ -147,7 +147,7 @@ and the discrete SPI clock frequency (250 MHz / (2__n__) for _n_ > 1):
 
 |  13 |  9616 |  9.615 MHz
 
-| 14+ | ....
+| 14+ | ....   | ....
 |===
 
 The lowest selectable SPI clock frequency is 30 kHz (spiclk_rate=30) for
diff --git a/docs/src/motion/5-axis-kinematics.adoc b/docs/src/motion/5-axis-kinematics.adoc
index a30427e6682..9391f8611a9 100644
--- a/docs/src/motion/5-axis-kinematics.adoc
+++ b/docs/src/motion/5-axis-kinematics.adoc
@@ -8,12 +8,6 @@ use image:: for equation png files -- no latexmath
 [[cha:5-axis-kinematics]]
 = 5-Axis Kinematics
 
-// 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}
-
 (((5-Axis Kinematics)))
 
 == Introduction
@@ -306,7 +300,7 @@ using the LinuxCNC vismach facility.
 
 Vismach is a library of python routines to display a dynamic simulation of a CNC machine on the PC screen. The python script for a particular machine is loaded in HAL and data passed by HAL pin connections.  The non-realtime vismach model is loaded by a HAL command like:
 
-[source,{hal}]
+[source,hal]
 ----
 loadusr -W xyzac-trt-gui
 ----
@@ -329,7 +323,7 @@ image::5-axis-figures/equation__38.png[align="center"]
 
 The required HAL connection (for xyzac-trt) is:
 
-[source,{hal}]
+[source,hal]
 ----
 net :tool-offset motion.tooloffset.z xyzac-trt-kins.tool-offset
 ----
@@ -373,7 +367,7 @@ Once it is compiled and installed you can reference it in your config setup of
 your machine. This is done in the INI file of your config directory. For
 example, the common INI specificaion:
 
-[source,{ini}]
+[source,ini]
 ----
 [KINS]
 KINEMATICS = trivkins
@@ -381,7 +375,7 @@ KINEMATICS = trivkins
 
 is replaced by
 
-[source,{ini}]
+[source,ini]
 ----
 [KINS]
 KINEMATICS = kinsname
@@ -392,7 +386,7 @@ Additional HAL pins may be created by the module for variable configuration item
 such as the D~x~, D~y~, D~z~, tool-offset used in the xyzac-trt kinematics module.
 These pins can be connected to a signal for dynamic control or set once with HAL connections like:
 
-[source,{hal}]
+[source,hal]
 ----
 # set offset parameters
 net :tool-offset motion.tooloffset.z xyzac-trt-kins.tool-offset
diff --git a/docs/src/motion/external-offsets.adoc b/docs/src/motion/external-offsets.adoc
index b304d4ebec0..9548d705a4a 100644
--- a/docs/src/motion/external-offsets.adoc
+++ b/docs/src/motion/external-offsets.adoc
@@ -4,13 +4,6 @@
 [[cha:external-offsets]]
 = External Axis Offsets
 
-
-// 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}
-
 (((externaloffsets)))
 
 External axis offsets are supported during teleop (world) jogs
@@ -25,7 +18,7 @@ connected to an encoder INI component that counts pulses.
 
 For each axis letter (*L* in xyzabcuvw):
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_L]OFFSET_AV_RATIO = value (controls accel/vel for external offsets)
 ----
@@ -201,7 +194,7 @@ man page for details (*$ man eoffset_per_angle*).
 The external axis offset capability is enabled by adding
 an '[AXIS_L]' setting for each candidate axis.  For example:
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_Z]
 OFFSET_AV_RATIO = 0.2
@@ -228,7 +221,7 @@ Example INI file settings to simulate the HAL pin
 eoffset connections and display eoffset information for the
 z axis (for identity kinematics with z==joint2):
 
-[source,{ini}]
+[source,ini]
 ----
 [APPLICATIONS]
 APP = sim_pin \
diff --git a/docs/src/motion/switchkins.adoc b/docs/src/motion/switchkins.adoc
index f92bf28a782..adeecb2d1cc 100644
--- a/docs/src/motion/switchkins.adoc
+++ b/docs/src/motion/switchkins.adoc
@@ -4,11 +4,6 @@
 [[cha:switchable-kinematics]]
 = Switchable Kinematics (switchkins)
 
-// 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}
 
 == Introduction
 
@@ -54,11 +49,11 @@ for backwards compatibility.  The provided sim configs alter the
 type0/type1 convention by forcing type0==identity kinematics using the
 module string parameter 'sparm' with an INI file setting like:
 
-[source,{ini}]
+[source,ini]
 ----
 [KINS]
 KINEMATICS = xyzac-trt-kins sparm=identityfirst
-...
+# ...
 ----
 
 === Identity letter assignments
@@ -68,7 +63,7 @@ When using an *identity* kinematics type, the module parameter
 arbitrary order from the set of allowed coordinate letters.
 Examples:
 
-[source,{ini}]
+[source,ini]
 ----
 [KINS]
 JOINTS = 6
@@ -141,7 +136,7 @@ Switchkins functionality is enabled by the pin
 analog output pin like motion.analog-out-03 so that it can be
 set by M68 commands.  Example:
 
-[source,{hal}]
+[source,hal]
 ----
 net :kinstype-select <= motion.analog-out-03
 net :kinstype-select => motion.switchkins-type
@@ -151,7 +146,7 @@ net :kinstype-select => motion.switchkins-type
 
 Kinstype selection is managed using G-code sequences like:
 
-[source,{ngc}]
+[source,ngc]
 ----
 ...
 M68 E3 Q1 ;update analog-out-03 to select kinstype 1
@@ -200,7 +195,7 @@ velocity, and acceleration for each applicable coordinate letter
 specified in the configuration INI file.  Example for letter L
 (in the set 'XYZABCUVW'):
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_L]
 MIN_LIMIT =
@@ -223,7 +218,7 @@ See the milltask manpage for more information ($ man milltask).
 
 The relevant INI-HAL pins for a joint number (_N_) are:
 
-[source,{hal}]
+[source,hal]
 ----
 ini.N.min_limit
 ini.N.max_limit
@@ -233,7 +228,7 @@ ini.N.max_velocity
 
 The relevant INI-HAL pins for an axis coordinate (_L_) are:
 
-[source,{hal}]
+[source,hal]
 ----
 ini.L.min_limit
 ini.L.max_limit
diff --git a/docs/src/plasma/plasma-cnc-primer.adoc b/docs/src/plasma/plasma-cnc-primer.adoc
index 7c748ea8b5f..3a5ed00ad32 100644
--- a/docs/src/plasma/plasma-cnc-primer.adoc
+++ b/docs/src/plasma/plasma-cnc-primer.adoc
@@ -4,12 +4,6 @@
 [[cha:plasma-primer]]
 = Plasma Cutting Primer for LinuxCNC Users
 
-// 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}
-
 (((Plasma Cutting Primer)))
 
 == What Is Plasma?
@@ -246,7 +240,7 @@ The following HAL code can be pasted into your QtPlasmaC's custom.hal to enable
 Install the correct bit file and connect the THCAD to IDX+ and IDX-.
 Be sure to change the calibration settings to agree with your THCAD-5.
 
-[source,{hal}]
+[source,hal]
 ----
 # --- Load the Component ---
 loadrt ohmic names=ohmicsense
@@ -434,7 +428,7 @@ How this is implemented is totally arbitrary.
 Lets look at how the LinuxCNC QtPlasmaC configuration does this:
 
 .Select Material Settings in QtPlasmaC and Use the Feedrate for that Material.
-[source,{ngc}]
+[source,ngc]
 ----
 M190 Pn
 M66 P3 L3 Q1
@@ -446,7 +440,7 @@ NOTE: Users with a very large number of entries in the QtPlasmaC Materials Table
 
 === Enable/Disable THC Operation:
 
-[source,{ngc}]
+[source,ngc]
 ----
 M62 P2 will disable THC (synchronised with motion)
 M63 P2 will enable THC (synchronised with motion)
@@ -455,7 +449,7 @@ M65 P2 will enable THC (immediately)
 ----
 
 .Reduce Cutting Speeds: (e.g., for hole cutting)
-[source,{ngc}]
+[source,ngc]
 ----
 M67 E3 Q0 would set the velocity to 100% of requested~speed
 M67 E3 Q40 would set the velocity to 40% of requested~speed
@@ -464,7 +458,7 @@ M67 E3 Q100 would set the velocity to 100% of requested~speed
 ----
 
 .Cutter Compensation:
-[source,{ngc}]
+[source,ngc]
 ----
 G41.1 D#<_hal[plasmac_run.kerf-width-f]> ; for left of programmed path
 G42.1 D#<_hal[plasmac_run.kerf-width-f]> for right of programmed path
@@ -499,7 +493,7 @@ Example:
 On a metric machine with a NEMA23 motor with a direct drive to a 5 mm ball screw, 60 mm/s maximum velocity and 700 mm/s^2^ acceleration were determined to be safe values without loss of steps.
 For this machine, set the Z axis in the INI file as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 [AXIS_Z]
 OFFSET_AV_RATIO = 0.5
@@ -509,7 +503,7 @@ MAX_ACCELERATION = 1400
 
 The joint associated with this axis would have the velocity and acceleration variables set as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 [JOINT_n]
 MAX_VELOCITY = 60
@@ -566,7 +560,7 @@ Assuming it is connected to a Mesa 7I76E, connect the output to the spindle enco
 
 Make sure you have the following lines in your INI file (assuming a Mesa 7I76E):
 
-[source,{hal}]
+[source,hal]
 ----
 setp hm2_7i76e.0.encoder.00.scale -1
 setp hm2_7i76e.0.encoder.00.counter-mode 1
diff --git a/docs/src/plasma/qtplasmac.adoc b/docs/src/plasma/qtplasmac.adoc
index 4d609012900..7b3b17478c8 100644
--- a/docs/src/plasma/qtplasmac.adoc
+++ b/docs/src/plasma/qtplasmac.adoc
@@ -4,11 +4,6 @@
 [[cha:qtplasmac]]
 = QtPlasmaC
 
-// 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}
 
 == Preamble
 
@@ -373,7 +368,7 @@ To apply a low-pass filter to the arc-voltage, the user would edit the following
 
 For example:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.lowpass-frequency 100
 ----
@@ -542,7 +537,7 @@ QtPlasmaC has some specific __.ini file variables as follows:
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 PROGRAM_EXTENSION = .ngc,.nc,.tap G-code File (*.ngc, *.nc, *.tap)
 ngc               = qtplasmac_gcode
@@ -555,7 +550,7 @@ tap               = qtplasmac_gcode
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 RS274NGC_STARTUP_CODE = G21 G40 G49 G80 G90 G92.1 G94 G97 M52P1
 SUBROUTINE_PATH       = ./:../../nc_files
@@ -573,7 +568,7 @@ SEE <> FOR RS274NGC_STARTUP_CODE INFORMATI
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 HALUI           = halui (required)
 HALFILE         = __.hal (the machine HAL file)
@@ -591,7 +586,7 @@ The user could place custom HAL commands in the custom.hal file as this file is
 
 This variable  is mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = qtvcp qtplasmac      (use 16:9 resolution)
         = qtvcp qtplasmac_9x16 (use 9:16 resolution)
@@ -603,7 +598,7 @@ link:../gui/qtvcp.html#_ini_settings[QtVCP INI Settings]
 
 For example, the following would start a 16:9 resolution QtPlasmaC screen in full screen mode:
 
-[source,{ini}]
+[source,ini]
 ----
 DISPLAY = qtvcp -f qtplasmac
 ----
@@ -612,7 +607,7 @@ DISPLAY = qtvcp -f qtplasmac
 
 This variable is mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 SPINDLES = 3
 ----
@@ -621,7 +616,7 @@ SPINDLES = 3
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 MAX_VELOCITY     = double the value in the corresponding joint
 MAX_ACCELERATION = double the value in the corresponding joint
@@ -632,7 +627,7 @@ OFFSET_AV_RATIO  = 0.5
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 MAX_VELOCITY     = double the value in the corresponding joint
 MAX_ACCELERATION = double the value in the corresponding joint
@@ -643,7 +638,7 @@ OFFSET_AV_RATIO  = 0.5
 
 These variables are mandatory.
 
-[source,{ini}]
+[source,ini]
 ----
 MIN_LIMIT        = just below the top of the table's slats
 MAX_VELOCITY     = double the value in the corresponding joint
@@ -932,7 +927,7 @@ See <> for detailed informati
 
 It is possible to hide this tab so the conversational feature cannot be used by an operator. This may be achieved either by wiring the pin to a physical key-switch or similar or it may also be set in a HAL file using the following command:
 
-[source,{hal}]
+[source,hal]
 ----
 setp qtplasmac.conv_disable 1
 ----
@@ -950,7 +945,7 @@ This tab is used to display configuration parameters that are modified infrequen
 
 It is possible to hide this tab so machine settings cannot be modified by unauthorized personnel. This may be achieved either by wiring the pin to a physical key-switch or similar or it may also be set in a HAL file using the following command:
 
-[source,{hal}]
+[source,hal]
 ----
 setp qtplasmac.param_disable 1
 ----
@@ -1139,7 +1134,7 @@ This tab is used to display GUI configuration parameters, button text, and shutd
 
 It is possible to hide this tab so machine settings cannot be modified by unauthorized personnel. This may be achieved either by wiring the pin to a physical key-switch or similar or it may also be set in a HAL file using the following command:
 
-[source,{hal}]
+[source,hal]
 ----
 setp qtplasmac.settings_disable 1
 ----
@@ -1286,13 +1281,13 @@ If the metric user wanted to cut the G-code file using imperial material, then t
 The following stanzas are the minimum recommended codes to include in the preamble and postamble of any G-code file to be run by QtPlasmaC:
 
 Metric:
-[source,{ngc}]
+[source,ngc]
 ----
 G21 G40 G49 G64p0.1 G80 G90 G92.1 G94 G97
 ----
 
 Imperial:
-[source,{ngc}]
+[source,ngc]
 ----
 G20 G40 G49 G64p0.004 G80 G90 G92.1 G94 G97
 ----
@@ -1335,14 +1330,14 @@ QtPlasmaC is able to read a material file to load all the required cut parameter
 To enable to G-code file to use the cut feed rate setting from the cut parameters use the following code in the G-code file:
 
 
-[source,{ngc}]
+[source,ngc]
 ----
 F#<_hal[plasmac.cut-feed-rate]>
 ----
 
 It is possible to use the standard G-code *F* word to set the cut feed rate as follows:
 
-[source,{ngc}]
+[source,ngc]
 ----
 F 1000
 ----
@@ -1394,7 +1389,7 @@ WARNING: It is the responsibility of the operator to ensure that the variables a
 
 The material file uses the following format:
 
-[source,{ini}]
+[source,ini]
 ----
 [MATERIAL_NUMBER_1]
 NAME                = name
@@ -1424,14 +1419,14 @@ After any changes have been saved, press *Reload* in the MATERIAL section of the
 For manual material handling, the user would manually select the material from the materials list in the MATERIAL section of the <> before starting the G-code program.
 In addition to selecting materials with materials list in the MATERIAL section of the <>, the user could use the MDI to change materials with the following command:
 
-[source,{ngc}]
+[source,ngc]
 ----
 M190 Pn
 ----
 
 The following code is the minimum code necessary to have a successful cut using the manual material selection method:
 
-[source,{ngc}]
+[source,ngc]
 ----
 F#<_hal[plasmac.cut-feed-rate]>
 M3 $0 S1
@@ -1457,7 +1452,7 @@ For automatic material handling, the codes MUST be applied in the order shown.
 If a G-code program is loaded which contains one or more material change commands then the first material will be displayed in the top header of the PREVIEW WINDOW on the <> as the program is loading.
 
 .Minimum code necessary to have a successful cut using the automatic material selection method:
-[source,{ngc}]
+[source,ngc]
 ----
 M190 Pn
 M66 P3 L3 Q1
@@ -1539,14 +1534,14 @@ Optional parameters are:
 
 A complete example (metric):
 
-[source,{ngc}]
+[source,ngc]
 ----
 (o=0, nu=2, na=5mm Mild Steel 40A, ph=3.1, pd=0.1, ch=0.75, fr=3000, mt=5, kw=0.5, th=1, ca=40, cv=110, pe=0.1, gp=5, cm=1, jh=0, jd=0)
 ----
 
 A complete example (imperial):
 
-[source,{ngc}]
+[source,ngc]
 ----
 (o=0, nu=2, na=0.197" Mild Steel 40A, ph=0.122, pd=0.1, ch=0.029, fr=118, mt=0.197, kw=0.020, th=1, ca=40, cv=110, pe=0.1, gp=72, cm=1, jh=0, jd=0)
 ----
@@ -1625,7 +1620,7 @@ To use this feature, the user must set the laser's offset from the torch center
 
 To modify the offsets manually, the user could edit either or both the following options in the *[LASER_OFFSET]* section of the __.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 X axis = n.n
 Y axis = n.n
@@ -1635,7 +1630,7 @@ where _n.n_ is distance from the center line of the torch to the laser's cross h
 
 Additionally, the laser can be tied to any available output to turn the laser on and off via a HAL pin with the following name:
 
-[source,{hal}]
+[source,hal]
 ----
 qtplasmac.laser_on
 ----
@@ -1685,7 +1680,7 @@ To use this feature, the user must set the camera's offset from the torch center
 
 To modify the offsets manually, the user could edit either or both the following axes options in the *[CAMERA_OFFSET]* section of the __.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 X axis = n.n
 Y axis = n.n
@@ -1732,13 +1727,13 @@ If no G64 command is found it will insert a `G64 P0.1` command which sets the pa
 For a imperial config the command will be `G64 P0.004`.
 
 .For Metric:
-[source,{ngc}]
+[source,ngc]
 ----
 G64 P0.1
 ----
 
 .For Imperial:
-[source,{ngc}]
+[source,ngc]
 ----
 G64 P0.004
 ----
@@ -1753,14 +1748,14 @@ This is also a requirement for <_.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 X axis = n.n
 Y axis = n.n
@@ -1995,7 +1990,7 @@ There are two ways of enabling this feature:
 . Utilize the default <> to toggle between the cut types.
 . Adding the following line to the G-code program before the first cut to enable *Pierce Only* mode for the current file:
 
-[source,{ngc}]
+[source,ngc]
 ----
 # = 1
 ----
@@ -2037,14 +2032,14 @@ This is also a requirement for <> during <
> section.
 
 .Sample code for hole cutting with reduced velocity.
-[source,{ngc}]
+[source,ngc]
 ----
 G21 (metric)
 G64 P0.005
@@ -2095,7 +2090,7 @@ It is important to thoroughly understand the difference between *Synchronized wi
 
 Sample code:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G21 (metric)
 G64 P0.005
@@ -2153,7 +2148,7 @@ It is possible to change this value with the following command in a G-code file:
 This feature can be used in addition to setting the desired hole sensing mode via the appropriate G-code parameter by setting the <> parameter in the MATERIAL frame of the <>.
 
 .Sample code:
-[source,{ngc}]
+[source,ngc]
 ----
 G21 (metric)
 G64 P0.005
@@ -2442,7 +2437,7 @@ After the above directions are completed, the scribe may be tested manually by i
 
 To use the scribe from G-code:
 
-[source,{ngc}]
+[source,ngc]
 ----
 ...
 M52 P1 (enable adaptive feed)
@@ -2489,7 +2484,7 @@ For this reason, a minimal movement at a high speed is required to be programmed
 
 An example G-code is:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G21 (metric)
 F99999 (high feed rate)
@@ -2690,14 +2685,14 @@ If the user wishes for the generated G-code to have each code on an individual l
 
 This will place all codes on the same line:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G21 G40 G49 G64p0.1 G80 G90 G92.1 G94 G97
 ----
 
 This will place each code on its own line:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G21\nG40\nG49\nM52P1\nG64p0.1\nG80\nG90\nG92.1\nG94\nG97
 ----
@@ -2863,7 +2858,7 @@ __.prefs must be edited with QtPlasmaC closed or any changes will
 
 Additionally, it is possible for *ERROR SENT TO MACHINE LOG* to flash to get the user's attention by adding or editing the following option in the *[GUI_OPTIONS]* section of the __.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 Flash error = True
 ----
@@ -3044,7 +3039,7 @@ This would be done with the following code in qtplasmac_custom.qss:
 
 Custom style sheets are enabled by setting the following option in the *[GUI_OPTIONS]* section of the __.prefs file. This option must be set to the filename of the style sheet as shown below.
 
-[source,{ini}]
+[source,ini]
 ----
 Custom style = the_cool_style.qss
 ----
@@ -3098,7 +3093,7 @@ background of conversational shape buttons
 background of active camera/laser buttons +
 foreground of G-code editor cursor
 |color4 (#36362e) |Alt Background |background of G-code display's active line
-|color5 (#b0b0b0) |foreground of disabled buttons
+|color5 (#b0b0b0) |Disabled |foreground of disabled buttons
 |===
 
 [[plasma:default_styling]]
@@ -3138,7 +3133,7 @@ Custom code can be added in two different ways: a user command file or a user pe
 
 A user command file is specified in the DISPLAY section of the __.ini file and contains Python code that is processed only once during startup.
 
-[source,{ini}]
+[source,ini]
 ----
 USER_COMMAND_FILE = my_custom_code.py
 ----
@@ -3219,7 +3214,7 @@ All __.prefs file settings for the buttons are found in the *[BUTT
 
 The text that appears on the button is set the following way:
 
-[source,{ini}]
+[source,ini]
 ----
 n Name = HAL Show
 ----
@@ -3228,14 +3223,14 @@ Where _n_ is the button number and *HAL Show* is the text.
 
 For text on multiple lines, split the text with a \ (backslash):
 
-[source,{ini}]
+[source,ini]
 ----
 n Name = HAL\Show
 ----
 
 If an ampersand is required to be displayed as text then two consecutive ampersands are required:
 
-[source,{ini}]
+[source,ini]
 ----
 n Name = PIERCE&&CUT
 ----
@@ -3270,7 +3265,7 @@ Buttons can run the following:
 
 To run an external command, the command is preceded by a % character.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = %halshow
 ----
@@ -3281,7 +3276,7 @@ n Code = %halshow
 To run an external Python script, the script name is preceded by a % character and it also requires a .py extension.
 It is valid to use the ~ character as a shortcut for the user's home directory.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = %~/user_script.py
 ----
@@ -3291,14 +3286,14 @@ n Code = %~/user_script.py
 
 To run G-code, just enter the code to be run.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = G0 X100
 ----
 
 To run an existing subroutine.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = o call
 ----
@@ -3306,7 +3301,7 @@ n Code = o call
 __.ini file variables can be entered by using the standard LinuxCNC G-code format.
 If expressions are included, then they need to be surrounded by brackets.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = G0 X#<_ini[joint_0]home> Y1
 n Code = G53 G0 Z[#<_ini[axis_z]max_limit> - 1.001]
@@ -3316,7 +3311,7 @@ __.prefs file variables and also __.ini variables ca
 You must put a space after each *}* if there are any following characters.
 If expressions are included, then they need to be surrounded by brackets.
 
-[source,{ini}]
+[source,ini]
 ----
 BUTTON_n_CODE = G0 X{LASER_OFFSET X axis} Y{LASER_OFFSET Y axis}
 BUTTON_n_CODE = G0 X{JOINT_0 HOME} Y1
@@ -3326,14 +3321,14 @@ BUTTON_n_CODE = G53 G0 Z[{AXIS_Z MAX_LIMIT} - 1.001]
 Multiple codes can be run by separating the codes with a "\" (backslash) character.
 The exception is the special commands which are required to be a single command per button.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = G0 X0 Y0 \ G1 X5 \ G1 Y5
 ----
 
 External commands and G-code may be mixed on the same button.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = %halshow \ g0x.5y.5 \ %halmeter
 ----
@@ -3347,7 +3342,7 @@ The button text will alternate with each button press and the indicator light ma
 It is mandatory to specify the button code in the following order: "dual-code", the first code, the alternate button text, and the second code separated by double semicolons.
 If an indicator is required then optionally add ";; true" at the end.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = dual-code ;; code1 ;; name1 ;; code2 ;; true
 ----
@@ -3360,7 +3355,7 @@ code1 and code2 both follow the rule of the preceding code explanations, <_.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = G0 X{LASER_OFFSET X axis} Y{LASER_OFFSET Y axis} \ toggle-laser
 ----
@@ -3441,7 +3436,7 @@ The position of the "toggle-laser" command is not important as it is always the
 
 The following code will allow the user to use a button to pulse a HAL bit pin for a duration of 0.5 seconds:
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = pulse-halpin the-hal-pin-name 0.5
 ----
@@ -3469,7 +3464,7 @@ If the user has "View Material" selected in the GUI SETTINGS section of the <>, Pierce and Cut (default cutting mode) or Pierce Only.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = cut-type
 ----
@@ -3519,7 +3514,7 @@ There are three methods to return to the previous coordinates:
 . Press *CYCLE RESUME* - the torch will return to the original coordinates and the program will resume.
 . Press *CYCLE STOP* - the torch will return to the original coordinates and the program will abort.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = change-consumables X10 Y10 F1000
 ----
@@ -3533,7 +3528,7 @@ HAL connections to this HAL pin needs to be specified in a postgui HAL file as t
 
 Loading a G-code program from the directory specified by the *PROGRAM_PREFIX* variable in the __.ini file (usually ~/linuxcnc/nc_files) is possible by using the following format:
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = load G-code.ngc
 ----
@@ -3541,7 +3536,7 @@ n Code = load G-code.ngc
 If the user's G-code file is located in a sub-directory of the *PROGRAM_PREFIX* directory, it would be accessed by adding the sub-directory name to the beginning of the G-code file name.
 Example for a sub-directory named *plasma*:
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = load plasma/G-code.ngc
 ----
@@ -3564,7 +3559,7 @@ as will pressing 'Esc' if keyboard shortcuts are enabled in the <> feature.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = single-cut
 ----
@@ -3610,28 +3605,28 @@ The following GUI buttons and Keyboard Shortcuts (if enabled in the <>.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = manual-cut
 ----
@@ -3655,7 +3650,7 @@ n Code = manual-cut
 This allows the showing/hiding of an offset viewing screen that displays all machine offsets.
 All relative offsets can be edited and the G54 ~ G59.3 work system coordinates are able to be given custom names.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = offsets-view
 ----
@@ -3666,7 +3661,7 @@ n Code = offsets-view
 This allows the loading of the last modified file in a directory.
 The directory name is optional and if omitted will default to the last directory a file was loaded from.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = latest-file /home/me/linuxcnc/nc_files/qtplasmac-test
 ----
@@ -3677,7 +3672,7 @@ n Code = latest-file /home/me/linuxcnc/nc_files/qtplasmac-test
 This allows the showing/hiding of the online HTML user manual specific to the version of LinuxCNC currently running.
 Note that internet access is required for this functionality.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = user-manual
 ----
@@ -3687,7 +3682,7 @@ n Code = user-manual
 
 This allows the toggling between joint mode and teleop mode. The machine must be on and homed for this button to be active.
 
-[source,{ini}]
+[source,ini]
 ----
 n Code = toggle-joint
 ----
@@ -3741,7 +3736,7 @@ By default, QtPlasmaC will remove all Z motion from a loaded G-code file and add
 If the user wishes to use their table with a marker, drag knife, diamond scribe, etc. mounted in the torch holder,
 QtPlasmaC has the ability to retain the Z movements when executing a program by adding the following command in a G-code file:
 
-[source,{ngc}]
+[source,ngc]
 ----
 # = 1
 ----
@@ -3843,7 +3838,7 @@ The following HAL bit output pins are always created and can be used by either t
 If the user has external buttons and/or a pendant that emulates any of the program buttons, CYCLE START, CYCLE PAUSE, or CYCLE STOP
 then it is possible to hide any or all of these GUI program buttons by adding the following options to the *[GUI_OPTIONS]* section of the __.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 Hide run = True
 Hide pause = True
@@ -3876,7 +3871,7 @@ There are also two HAL pins that have been provided to allow the user to tune th
 
 The following example would set the number of valid consecutive readings required to 6:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.arc-ok-counts 6
 ----
@@ -3893,7 +3888,7 @@ It is important to note that the THC will be disabled and locked at the cutting
 
 The following code would set a delay of 0.1 seconds:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.arc-lost-delay 0.1
 ----
@@ -3913,7 +3908,7 @@ The pin for adjusting this value is named plasmac.zero-window and the default va
 
 The following example would set the voltage window to be displayed as 0 V from -5 V to +5 V:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.zero-window 5
 ----
@@ -3928,7 +3923,7 @@ These HAL pins are:
 
 The following example would set the number of on cycles required to 3:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.void-on-cycles 3
 ----
@@ -3948,7 +3943,7 @@ It is not recommended to use values less than 5 mm as offset overrun may cause
 
 The following example would set the distance from Z MAX_LIMIT to 10 mm:
 
-[source,{hal}]
+[source,hal]
 ----
 setp plasmac.max-offset 10
 ----
@@ -3958,7 +3953,7 @@ setp plasmac.max-offset 10
 By default, all tabs except the <> are disabled during automated motion.
 It is possible for every tab but the <> to be enabled during automated motion by setting the following HAL pin True:
 
-[source,{hal}]
+[source,hal]
 ----
 setp qtplasmac.tabs_always_enabled 1
 ----
@@ -4012,7 +4007,7 @@ The plasmac HAL component has a HAL pin named *plasmac.state-out* which can be u
 |24   m|CONSUMABLE_CHANGE_OFF |return from consumable change coordinates
 |25   m|CUT_RECOVERY_ON       |cut recovery is active
 |26   m|CUT_RECOVERY_OFF      |cut recovery is deactivated
-|27   m|DEBUG
+|27   m|DEBUG                 |debug state, for testing purposes only
 |===
 
 The DEBUG state is for testing purposes only and will not normally be encountered.
@@ -4040,7 +4035,7 @@ If the PM_PORT option is not set in the __.prefs file then the wid
 
 Example showing enabling the Hypertherm PowerMax Communications on USB0:
 
-[source,{ini}]
+[source,ini]
 ----
 [POWERMAX]
 Port = /dev/ttyusb0
@@ -4095,7 +4090,7 @@ A moving pierce allows the torch to move during the pierce delay period. This ha
 Through the use of M159 a moving pierce can be configured.
 
 The syntax for the M159 command is as follows: +
-[source,{ngc}]
+[source,ngc]
 ----
 M159 Pn Qn
 ----
@@ -4140,13 +4135,13 @@ For example:
 This means that the length of the wiggle is 4 x 3 = 12 mm. At the 18 mm/s feed rate, the pierce delay needs to be approx 0.7 seconds to support the wiggle distance at pierce height.
 
 The G-code needed invoke this behaviour is: +
-[source,{ngc}]
+[source,ngc]
 ----
 M159 P601 Q1
 ----
 
 The  G-code needed to reset to standard behaviour is: +
-[source,{ngc}]
+[source,ngc]
 ----
 M159 P609
 ----
@@ -4171,7 +4166,7 @@ As with wiggle pierce it is up the CAM tooling or the user to program a ramping
 
 Below is a sample of code to setup a ramp pierce: +
 
-[source,{ngc}]
+[source,ngc]
 ----
 (o=0,kw=2, ph=4, pd=1, ch=1.5, fr=490, th=1, cv=99, pe=0.3, jh=0, jd=0)
 
@@ -4673,7 +4668,7 @@ G-code editor is active, MDI is active. When QtPlasmaC is shut down, the Operati
 If the user wishes to prevent QtPlasmaC from changing the Operating System's autorepeat settings,
 enter the following option in the *[GUI_OPTIONS]* section of the __.prefs file:
 
-[source,{ini}]
+[source,ini]
 ----
 Autorepeat all == True
 ----
@@ -4688,7 +4683,7 @@ The user must restart QtPlasmaC to disable the autorepeat feature again.
 
 QtPlasmaC does not currently adhere to the following stanza in the __.ini file:
 
-[source,{ini}]
+[source,ini]
 ----
 NO_FORCE_HOMING = 1
 ----
diff --git a/docs/src/remap/remap.adoc b/docs/src/remap/remap.adoc
index c0e4972606b..6c7d28855a3 100644
--- a/docs/src/remap/remap.adoc
+++ b/docs/src/remap/remap.adoc
@@ -4,9 +4,6 @@
 [[cha:remap]]
 = Remap Extending G-code
 
-:ini: {basebackend@docbook:'':ini}
-:hal: {basebackend@docbook:'':hal}
-:ngc: {basebackend@docbook:'':ngc}
 
 == Introduction: Extending the RS274NGC Interpreter by Remapping Codes
 
@@ -56,7 +53,7 @@ M- and G-codes, and O-words subroutine calls have some fairly different syntax.
 
 O-word procedures, for example, take positional parameters with a specific syntax like so:
 
-[source,{ngc}]
+[source,ngc]
 ----
 o call [1.234] [4.65]
 ----
@@ -132,7 +129,7 @@ In the tool table, tools numbers above 10000 are wear offsets, e.g. in the tool
 
 Here is what you need in the INI to use them:
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 REMAP=T python=index_lathe_tool_with_wear
@@ -218,7 +215,7 @@ For this reason, you need to choose an appropriate modal group for your code to
 To give you an idea how the pieces fit together, let's explore a fairly minimal but complete remapped code definition.
 We choose an unallocated M-code and add the following option to the INI file:
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 REMAP=M400  modalgroup=10 argspec=Pq ngc=myprocedure
@@ -388,7 +385,7 @@ Assume the code is defined as
 
 and `m400.ngc` looks as follows:
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 (P is required since it is uppercase in the argspec)
@@ -413,7 +410,7 @@ Assume the code is defined as
 
 and `m410.ngc` looks as follows:
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 (debug, [1]=#1 [2]=#2 [3]=#3)
@@ -567,7 +564,7 @@ $ echo 'import remap' >toplevel.py
 
 Now edit ``/home/user/``__xxx__``/``__xxx__``.ini`` and add the following:
 
-[source,{ini}]
+[source,ini]
 ----
 [PYTHON]
 TOPLEVEL=/home/user/xxx/python/toplevel.py
@@ -734,7 +731,7 @@ You will find that most prolog functions look very similar:
 Our first iteration of the O-word procedure is unexciting - just verify we got parameters right, and signal success by returning a positive value;
 steps 3-5 would eventually be covered here (see <> for the variables referring to INI file settings):
 
-[source,{ngc}]
+[source,ngc]
 ----
 O sub
 (debug, change: current_tool=#)
@@ -788,7 +785,7 @@ However, we don't need the HAL pin wiggling anymore - all `iocontrol` is left to
 This means that the corresponding `iocontrol` pins have no function any more.
 Therefore, we configure `iocontrol` to immediately acknowledge a change by configuring like so:
 
-[source,{hal}]
+[source,hal]
 ----
 # loop change signals when remapping M6
 net tool-change-loop iocontrol.0.tool-change iocontrol.0.tool-changed
@@ -833,7 +830,7 @@ Slightly twisting a built in would look like so (in the case of `M6`):
 REMAP=M6   modalgroup=6  ngc=mychange
 ----
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 M6 (use built in M6 behavior)
@@ -858,7 +855,7 @@ What you could do, for instance, is:
 
 Again, the `iocontrol` tool-prepare/tool-prepared pins would be unused and replaced by `motion.*` pins, so those would pins must be looped:
 
-[source,{hal}]
+[source,hal]
 ----
 # loop prepare signals when remapping T
 net tool-prep-loop iocontrol.0.tool-prepare iocontrol.0.tool-prepared
@@ -900,7 +897,7 @@ def prepare_prolog(self,**words):
 
 The minimal ngc prepare procedure again looks like so:
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 ; returning a positive value to commit:
@@ -947,7 +944,7 @@ which might be used for conditional cleanup.
 
 The reasons are defined in nml_intf/emc.hh
 
-[source,{ini}]
+[source,ini]
 ----
 EMC_ABORT_TASK_EXEC_ERROR = 1,
 EMC_ABORT_AUX_ESTOP = 2,
@@ -962,7 +959,7 @@ EMC_ABORT_INTERPRETER_ERROR_MDI = 10,	// interpreter failed during MDI execution
 EMC_ABORT_USER = 100  // user-defined abort codes start here
 ----
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 ON_ABORT_COMMAND=O  call
@@ -970,7 +967,7 @@ ON_ABORT_COMMAND=O  call
 
 The suggested on_abort procedure would look like so (adapt to your needs):
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 
@@ -1021,7 +1018,7 @@ If displaying an operator error message and stopping the current program is good
 use the `(abort, `____`)` feature to terminate the handler with an error message.
 Note that you can substitute numbered, named, INI and HAL parameters in the text like in this example (see also `tests/interp/abort-hot-comment/test.ngc`):
 
-[source,{ngc}]
+[source,ngc]
 ----
 o100 if [..] (some error condition)
      (abort, Bad Things! p42=#42 q=# INI=#<_ini[a]x> pin=#<_hal[component.pin])
@@ -1074,7 +1071,7 @@ A G-code cycle as used here is meant to behave as follows:
 An example: Assume you have `G84.3` defined as remapped G-code cycle with the following INI segment
 (see <> for a detailed description of +cycle_prolog+ and +cycle_epilog+):
 
-[source,{ini}]
+[source,ini]
 ----
 [RS274NGC]
 # A cycle with an O-word procedure: G84.3 
@@ -1083,7 +1080,7 @@ REMAP=G84.3 argspec=xyzabcuvwpr prolog=cycle_prolog ngc=g843 epilog=cycle_epilog
 
 Executing the following lines:
 
-[source,{ngc}]
+[source,ngc]
 ----
 g17
 (1)   g84.3 x1 y2 z3  r1
@@ -1148,7 +1145,7 @@ Note that the interpreter instance is available here as `this`, so you could als
 
 Here is an approach to use an O-word subroutine to read a preference file entry and add it as a G-code parameter.
 
-[source,{ngc}]
+[source,ngc]
 ----
 (filename myofile.ngc)
 o sub
@@ -1431,7 +1428,7 @@ def retrieve_param(self, **words):
     return INTERP_OK
 ----
 
-[source,{ngc}]
+[source,ngc]
 ----
 o sub
 (debug, call_level=#<_call_level> myname=#)
@@ -1558,7 +1555,7 @@ def _pi(self):
     return 3.1415926535
 ----
 
-[source,{ngc}]
+[source,ngc]
 ----
 # = [2 * # * #<_pi>]
 ----
@@ -1648,7 +1645,7 @@ and do a more thorough investigation of the block manually in order to give bett
 
 The suggested argspec is as follows:
 
-[source,{ini}]
+[source,ini]
 ----
 REMAP=G argspec=xyzabcuvwqplr prolog=cycle_prolog ngc= epilog=cycle_epilog modalgroup=1
 ----
@@ -2037,7 +2034,7 @@ the interpreter must be able to predict the machine position after each line of
 Let's look at a simple example program which does relative moves (G91), and assume the machine starts at x=0,y=0,z=0.
 Relative moves imply that the outcome of the next move relies on the position of the previous one:
 
-[source,{ngc}]
+[source,ngc]
 ----
 N10 G91
 N20 G0 X10 Y-5 Z20
@@ -2056,7 +2053,7 @@ and so can parse the whole program and generate canonical operations well in adv
 However, complete read ahead is only possible when the interpreter can predict the position impact for *every* line in the program in advance.
 Let's look at a modified example:
 
-[source,{ngc}]
+[source,ngc]
 ----
 N10 G91
 N20 G0 X10 Y-5 Z20
diff --git a/docs/src/tooldatabase/tooldatabase.adoc b/docs/src/tooldatabase/tooldatabase.adoc
index eb61b621187..0fab0191b21 100644
--- a/docs/src/tooldatabase/tooldatabase.adoc
+++ b/docs/src/tooldatabase/tooldatabase.adoc
@@ -4,12 +4,6 @@
 [[cha:tooldatabase]]
 = Tool Database Interface
 
-// 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}
-
 Tool data is conventionally described by a tool table file specified by an inifile setting: [EMCIO]TOOL_TABLE=tooltable_filename.
 A tool table file consists of a text line for each available tool describing the tool's parameters, see <>.
 
@@ -21,7 +15,7 @@ The tool database interface provides an alternative method for obtaining tool da
 
 INI file settings enable the (optional) operation of a user-provided tool database program:
 
-[source,{ini}]
+[source,ini]
 ----
 [EMCIO]
 DB_PROGRAM = db_program [args]
diff --git a/docs/src/user/user-concepts.adoc b/docs/src/user/user-concepts.adoc
index 17388dc502a..0ca5dd88867 100644
--- a/docs/src/user/user-concepts.adoc
+++ b/docs/src/user/user-concepts.adoc
@@ -4,12 +4,6 @@
 [[cha:important-user-concepts]]
 = Important User Concepts
 
-// 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}
-
 (((User Concepts)))
 This chapter covers important user concepts that should be understood before attempting to run a CNC machine with G-code.
 
@@ -27,7 +21,7 @@ Trajectory planning, in general, is the means by which LinuxCNC follows the path
 A G-code program can never be fully obeyed.
 For example, imagine you specify as a single-line program the following move:
 
-[source,{ngc}]
+[source,ngc]
 ----
 G1 X1 F10 (G1 is linear move, X1 is the destination, F10 is the speed)
 ----
diff --git a/src/hal/components/lut5.comp b/src/hal/components/lut5.comp
index 7ba0aa3d066..755fd763134 100644
--- a/src/hal/components/lut5.comp
+++ b/src/hal/components/lut5.comp
@@ -46,7 +46,7 @@ be *FALSE*.
 ^h|Bit 2
 ^h|Bit 1
 ^h|Bit 0
-2+^h|Weight
+^h|Weight
 
 |0|0|0|0|0|0x00000001
 |0|0|0|0|1|0x00000002

From 2f6b1179b3e4f979a107e5035a326748b2759efe Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:24:44 +0800
Subject: [PATCH 08/10] docs: rewrite gen_complist.py + po4a.cfg for
 per-language aliases

- gen_complist.py: produce content-stable mtime via write_if_changed
  helper and single-write add_links.  Bertho identified that
  components_gen.adoc was being rewritten with HTML-existence-
  dependent content every build, bumping documentation.pot's mtime
  and making po4a look like it ran twice.

- po4a.cfg: master config sourced for per-language target lists in
  the Submakefile (LANGUAGES derives from po4a_langs entry).
  AsciiDoc_def / man_def / xhtml_def / Text_def aliases for the
  asciidoctor pipeline.
---
 docs/po4a.cfg            |   6 +--
 docs/src/gen_complist.py | 110 ++++++++++++++++++++++-----------------
 2 files changed, 64 insertions(+), 52 deletions(-)

diff --git a/docs/po4a.cfg b/docs/po4a.cfg
index 64d10d967a9..7550a595cac 100644
--- a/docs/po4a.cfg
+++ b/docs/po4a.cfg
@@ -14,7 +14,7 @@
 [po4a_paths] po/documentation.pot $lang:po/$lang.po
 
 [po4a_alias:AsciiDoc_def] AsciiDoc opt:"--keep 0 --option 'entry=lang' --option 'tablecells'"
-[po4a_alias:man_def] man opt:"--keep 0 -o groff_code=translate -o inline=URL -o untranslated=FF,FU"
+[po4a_alias:man_def] man opt:"--keep 0 -o groff_code=translate -o inline=URL,MTO -o untranslated=FF,FU,als -o unknown_macros=untranslated"
 [po4a_alias:xhtml_def] xhtml opt:"--keep 0"
 
 # Should stay at 0 percent to make sure the imported python script is
@@ -128,6 +128,7 @@
 [type: AsciiDoc_def] src/hal/general-ref.adoc $lang:src/$lang/hal/general-ref.adoc
 [type: AsciiDoc_def] src/hal/hal-examples.adoc $lang:src/$lang/hal/hal-examples.adoc
 [type: AsciiDoc_def] src/hal/halmodule.adoc $lang:src/$lang/hal/halmodule.adoc
+[type: AsciiDoc_def] src/hal/halscope.adoc $lang:src/$lang/hal/halscope.adoc
 [type: AsciiDoc_def] src/hal/halshow.adoc $lang:src/$lang/hal/halshow.adoc
 [type: AsciiDoc_def] src/hal/haltcl.adoc $lang:src/$lang/hal/haltcl.adoc
 [type: AsciiDoc_def] src/hal/halui-examples.adoc $lang:src/$lang/hal/halui-examples.adoc
@@ -360,9 +361,6 @@
 [type: AsciiDoc_def] src/plasma/plasma-cnc-primer.adoc $lang:src/$lang/plasma/plasma-cnc-primer.adoc
 [type: AsciiDoc_def] src/plasma/qtplasmac.adoc $lang:src/$lang/plasma/qtplasmac.adoc
 [type: AsciiDoc_def] src/remap/remap.adoc $lang:src/$lang/remap/remap.adoc
-[type: AsciiDoc_def] src/source-highlight/hal-demo.adoc $lang:src/$lang/source-highlight/hal-demo.adoc
-[type: AsciiDoc_def] src/source-highlight/ini-demo.adoc $lang:src/$lang/source-highlight/ini-demo.adoc
-[type: AsciiDoc_def] src/source-highlight/ngc-demo.adoc $lang:src/$lang/source-highlight/ngc-demo.adoc
 [type: AsciiDoc_def] src/tooldatabase/tooldatabase.adoc $lang:src/$lang/tooldatabase/tooldatabase.adoc
 [type: AsciiDoc_def] src/user/starting-linuxcnc.adoc $lang:src/$lang/user/starting-linuxcnc.adoc
 [type: AsciiDoc_def] src/user/user-concepts.adoc $lang:src/$lang/user/user-concepts.adoc
diff --git a/docs/src/gen_complist.py b/docs/src/gen_complist.py
index 0c311aa0b84..bcb02363005 100644
--- a/docs/src/gen_complist.py
+++ b/docs/src/gen_complist.py
@@ -9,6 +9,19 @@
 import re
 import sys
 
+def write_if_changed(path, content):
+    """Write content to path only if it differs from existing.
+    Keeps mtime stable across no-op invocations so make stays idempotent."""
+    try:
+        with open(path, 'r') as f:
+            if f.read() == content:
+                return False
+    except FileNotFoundError:
+        pass
+    with open(path, 'w') as f:
+        f.write(content)
+    return True
+
 man1_path = '../docs/man/man1'
 man1_files = {f for f in os.listdir(man1_path) if f[0] != '.' and os.path.isfile(os.path.join(man1_path, f))}
 man9_path = '../docs/man/man9'
@@ -16,7 +29,30 @@
 man_files = man1_files.union(man9_files)
 complist_doc = set()
 miss_in_man = set()
-# complist_path = '../docs/src/hal/components.adoc'
+
+def add_links(lines, add_descr):
+    """Apply man-page link substitutions to the given lines (list of str,
+    each ending in newline), return the result as a single string."""
+    result = []
+    for line in lines:
+        if line and line[0] == '|' and line[1:2] != '=':
+            splitted = line.split('|')
+            if 'link:' in splitted[1]:
+                link = re.search('(?<=link:).*(?=\\[)', splitted[1]).group()
+                if not os.path.isfile(os.path.join('../docs/html/hal', link)):
+                    print('gen_complist: Broken link:', link)
+            else:
+                comp_man = splitted[1].strip(' ')
+                if comp_man in man_files:
+                    comp, man = comp_man.split(".")
+                    line = line.replace(comp_man, 'link:../man/man'+man+'/'+comp_man+'.html['+comp+']', 1)
+                    if add_descr:
+                        splitted = line.split('|')
+                        splitted[2] = extract_descr('../docs/man/man'+man+'/'+comp_man)\
+                            .replace(comp + ' ', ' ', 1).strip('\n -')
+                        line = '|'.join(splitted)
+        result.append(line)
+    return ''.join(result)
 
 def generate_complist(complist_path):
     file1 = open(complist_path, 'r')
@@ -27,7 +63,7 @@ def generate_complist(complist_path):
                 if 'link:' in splitted[1]:
                     link = re.search('(?<=link:).*(?=\\[)', splitted[1]).group()
                     comp_man = re.search("[a-zA-Z0-9-_\\.]+(?=\\.html)", link).group()
-                    if os.path.isfile(os.path.join('../docs/html/hal',link)):
+                    if os.path.isfile(os.path.join('../docs/html/hal', link)):
                         complist_doc.add(comp_man)
                     else:
                         print('gen_complist: Broken link:', link, file=sys.stderr)
@@ -39,60 +75,38 @@ def generate_complist(complist_path):
     miss_in_list = man_files.difference(complist_doc)
 
     gen_filename = '../docs/src/hal/components_gen.adoc'
-    file2 = open(gen_filename, 'w')
+    parts = []
     if len(miss_in_list) > 0:
-        file2.write('\n== Not categorized (auto generated from man pages)\n')
-        file2.write('[{tab_options}]\n|===\n')
+        parts.append('\n== Not categorized (auto generated from man pages)\n')
+        parts.append('[{tab_options}]\n|===\n')
         for i in sorted(miss_in_list):
-            file2.write('| ' + i + ' |||\n')
-        file2.write('|===\n')
+            parts.append('| ' + i + ' |||\n')
+        parts.append('|===\n')
     if len(miss_in_man) > 0:
-        file2.write('\n== Without man page or broken link (auto generated from component list)\n')
-        file2.write('[{tab_options}]\n|===\n')
+        parts.append('\n== Without man page or broken link (auto generated from component list)\n')
+        parts.append('[{tab_options}]\n|===\n')
         for i in sorted(miss_in_man):
-            file2.write('| ' + i + ' |||\n')
-        file2.write('|===\n')
-    file2.close()
+            parts.append('| ' + i + ' |||\n')
+        parts.append('|===\n')
 
-    generate_links(gen_filename, False, True)
+    # Build links in memory rather than writing tables-only, reading back,
+    # and writing tables+links.  The two-write pattern caused the on-disk
+    # file to be rewritten on every run (final content always differs from
+    # the tables-only intermediate), bumping mtime and re-triggering po4a.
+    final_content = add_links(''.join(parts).splitlines(keepends=True),
+                              add_descr=True)
+    write_if_changed(gen_filename, final_content)
     print('gen_complist: Added {} uncategorized and {} potentially obsolete entry/entries to hal component list'.format(len(miss_in_list), len(miss_in_man)))
 
-
 def generate_links(filename, create_backup=True, add_descr=False):
-    file = open(filename, 'r')
-    file_links = []
-    links_added = 0
-    for line in file:
-        if line[0] == '|' and line[1] != '=':
-            splitted = line.split('|')
-
-            if 'link:' in splitted[1]:
-                link = re.search('(?<=link:).*(?=\\[)', splitted[1]).group()
-                if not os.path.isfile(os.path.join('../docs/html/hal',link)):
-                    print('gen_complist: Broken link:', link)
-            else:
-                comp_man = splitted[1].strip(' ')
-                if comp_man in man_files:
-                    comp, man = comp_man.split(".")
-                    line = line.replace(comp_man, 'link:../man/man'+man+'/'+comp_man+'.html['+comp+']', 1)
-                    links_added += 1
-                    if add_descr:
-                        splitted = line.split('|')
-                        splitted[2] = extract_descr('../docs/man/man'+man+'/'+comp_man)\
-                        .replace(comp + ' ', ' ',1).strip('\n -')
-                        line = '|'.join(splitted)
-        file_links.append(line)
-    file.close()
-
-    if links_added:
-        if create_backup:
-            os.rename(filename, filename+'~')
-        file = open(filename, 'w')
-        for line in file_links:
-            file.write(line)
-        file.close()
-        print('gen_complist: Added {} link(s) to {}'.format(links_added, filename))
-
+    """Public API: read filename, add links, write back. Kept for the
+    'links' CLI subcommand path."""
+    with open(filename, 'r') as f:
+        lines = f.readlines()
+    new_content = add_links(lines, add_descr)
+    if create_backup:
+        os.rename(filename, filename+'~')
+    write_if_changed(filename, new_content)
 
 def extract_descr(filename):
     file = open(filename, 'r')

From 75f41e4b40a4d65092bc98318ffbe25b81e7f3b9 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:24:54 +0800
Subject: [PATCH 09/10] build: misc hygiene (gitignore, autom4te.cache, manpage
 images)

- .gitignore: drop nocheck workaround, ignore autom4te.cache,
  .checklink.*.tmp leftovers from docs/src/checkref.
- docs/src/.gitignore: ignore generated objects/.fonts and per-lang
  build leftovers.
- docs/man/images/Images_info.adoc: small note refresh.
---
 .gitignore                       | 4 ++++
 docs/man/images/Images_info.adoc | 2 +-
 docs/src/.gitignore              | 1 +
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 94e742f2bd7..3d286f605e4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,6 +50,8 @@ position.txt
 # Ignore temp files
 *.swp
 *~
+# Ignore checkref leftover output (docs/src/checkref)
+.checklink.*.tmp
 # Ignore po4a temp files
 *.failed.po
 *-new_??.po
@@ -57,3 +59,5 @@ position.txt
 *.*-stamp
 # Ignore VSCode settings
 .vscode/settings.json
+# autoreconf cache from debian/configure
+/autom4te.cache/
diff --git a/docs/man/images/Images_info.adoc b/docs/man/images/Images_info.adoc
index 1359fdfd124..b8461c51656 100644
--- a/docs/man/images/Images_info.adoc
+++ b/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├──
    └───────────┘
-----
\ No newline at end of file
+----
diff --git a/docs/src/.gitignore b/docs/src/.gitignore
index 0fd226d123b..9c221e4a4c3 100644
--- a/docs/src/.gitignore
+++ b/docs/src/.gitignore
@@ -31,3 +31,4 @@ vi/*
 zh_CN/*
 index_*.tmpl
 man/man1/linuxcnc.1.adoc
+rouge-*.css

From 239dd3fa1f451b414b807375ed76c19aab837dc7 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sat, 30 May 2026 09:25:00 +0800
Subject: [PATCH 10/10] ci: enable translated docs build in build-doc.sh

Pass --enable-build-documentation-translation to configure so the docs
CI builds the translated HTML/PDF set, not only English.  Exercises
the po4a / per-language pipeline end-to-end on every PR.
---
 .github/scripts/build-doc.sh | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/scripts/build-doc.sh b/.github/scripts/build-doc.sh
index 12dea6b7650..758655e244e 100755
--- a/.github/scripts/build-doc.sh
+++ b/.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