From 3b6db7e540d3b0c381d5c48788f827970b641ef6 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 21:39:08 +0800 Subject: [PATCH 01/30] docs: add asciidoctor extensions and PDF theme Three pieces of glue that let asciidoctor produce documentation that matches the look and behaviour of the existing asciidoc-py + dblatex output. Nothing is wired in yet; the Submakefile swap follows in the next commit. xref_resolver.rb -- asciidoctor preprocessor that mirrors what asciidoc-py used to do via objects/xref_.links: bare <> references are looked up in a tree-wide anchor index and rewritten to qualified <> form. The index is cached on disk keyed by source mtimes, and accepts an xref-exclude regex so each translated tree stays isolated. image_resolver.rb -- treeprocessor that resolves image targets the way asciidoc-py's image-wildcard pair did: relative paths in an included file resolve against that included file's directory, not the master. For PDF only it also defaults pdfwidth=75% on images without an explicit width, because prawn renders raster sources at native-pixel dimensions interpreted as 72 DPI and otherwise blows screenshots up to the full text column. pdf-theme.yml -- asciidoctor-pdf theme that approximates emc2.sty: A4 page, Times-like body, blue headings and links matching dblatex, top header with 'doc-title | chapter | page / total' and a thin rule, bottom rule only, no alternating page numbers. Falls back to Noto Serif CJK SC for non-Latin glyphs missing from the base font; DejaVu Sans Mono in code blocks so Cyrillic in listing/source blocks renders. otf2ttf.py -- Debian only ships Noto Serif CJK as a CFF/OTF TrueType Collection and prawn 2.4 corrupts the PDF when asked to embed CFF outlines directly. This is a tiny build-time helper that subsets the font to the CJK characters used anywhere in the docs (~600 glyphs out of 65000) and converts the curves with cu2qu before saving as TTF. Output is ~300 KB per face, ~1.5 s per face. --- docs/src/.gitignore | 2 + docs/src/extensions/image_resolver.rb | 79 ++++++++++++++++ docs/src/extensions/xref_resolver.rb | 130 ++++++++++++++++++++++++++ docs/src/otf2ttf.py | 102 ++++++++++++++++++++ docs/src/pdf-theme.yml | 130 ++++++++++++++++++++++++++ 5 files changed, 443 insertions(+) create mode 100644 docs/src/extensions/image_resolver.rb create mode 100644 docs/src/extensions/xref_resolver.rb create mode 100644 docs/src/otf2ttf.py create mode 100644 docs/src/pdf-theme.yml diff --git a/docs/src/.gitignore b/docs/src/.gitignore index 0fd226d123b..19ff749eb7e 100644 --- a/docs/src/.gitignore +++ b/docs/src/.gitignore @@ -2,6 +2,7 @@ *.xml !docs.xml !terms.xml +.fonts/ drivers/mb2hal_HOWTO.ini */drivers/mb2hal_HOWTO.ini # Ignore po4a-generated files for other languages @@ -31,3 +32,4 @@ vi/* zh_CN/* index_*.tmpl man/man1/linuxcnc.1.adoc +rouge-*.css diff --git a/docs/src/extensions/image_resolver.rb b/docs/src/extensions/image_resolver.rb new file mode 100644 index 00000000000..853bd208cfe --- /dev/null +++ b/docs/src/extensions/image_resolver.rb @@ -0,0 +1,79 @@ +# docs/src/extensions/image_resolver.rb +# +# Asciidoctor treeprocessor that resolves image targets the way the +# asciidoc-py + docs/src/image-wildcard pair did: +# - 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 +# +# 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 + + def process(document) + # For HTML output the relative target is correct as-is — asciidoctor + # writes it straight into and a sibling copy of the + # image tree makes it resolve at deploy time. Only PDF embedding + # needs absolute paths so prawn-svg / image reading can find the + # file at convert time. + return document unless document.backend == 'pdf' + document.find_by(context: :image) { |n| rewrite n } + document.find_by(context: :inline_image) { |n| rewrite n } + document + end + + def rewrite(node) + target = node.attr 'target' + return unless target + return if target.empty? + return if target.start_with?('http://', 'https://', '/') + return if target.include?('{') # leave macros alone + + src = node.file || node.document.attr('docfile') + return unless src + base_dir = File.dirname(File.expand_path(src)) + + candidate = File.expand_path(target, base_dir) + candidate = resolve_extension(candidate) unless File.file?(candidate) + return unless candidate && File.file?(candidate) + + node.set_attr('target', candidate) + apply_default_width(node) + 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 diff --git a/docs/src/otf2ttf.py b/docs/src/otf2ttf.py new file mode 100644 index 00000000000..9eb5820bc54 --- /dev/null +++ b/docs/src/otf2ttf.py @@ -0,0 +1,102 @@ +#!/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) + + if text: + 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', help='directory scanned for adoc/po sources; output subset to characters found there') + a = p.parse_args() + text = ''.join(sorted(scan_cjk(a.text_from))) if a.text_from else None + convert(a.input, a.output, a.ttc_index, text) + + +if __name__ == '__main__': + main() diff --git a/docs/src/pdf-theme.yml b/docs/src/pdf-theme.yml new file mode 100644 index 00000000000..60e7be926a7 --- /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: /usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf + bold: /usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf + italic: /usr/share/fonts/truetype/dejavu/DejaVuSansMono-Oblique.ttf + bold_italic: /usr/share/fonts/truetype/dejavu/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: 0000FF + 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 c13a73485c2a4ff76fb270c2edddae77d4cc4d84 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 21:39:36 +0800 Subject: [PATCH 02/30] docs: swap HTML, PDF, manpage build rules from asciidoc-py to asciidoctor The big switch. Every rule that used to invoke asciidoc, a2x or xsltproc now goes through asciidoctor or asciidoctor-pdf. HTML rules * 12 near-identical per-language target chains collapse into one ASCIIDOCTOR_HTML_RULE canned recipe instantiated with toUC for each language. Each call points asciidoctor at the shared xref_resolver extension and passes the language-specific xref-root and xref-exclude so anchors don't cross trees. * Stylesheet is the existing docs/html/linuxcnc.css (already tracked in the repo), referenced via -a stylesheet=linuxcnc.css -a linkcss. * Source highlighting moves from source-highlight to rouge. PDF rule * a2x/dblatex replaced by asciidoctor-pdf with our xref + image resolver extensions and pdf-theme.yml. * Version macro is fed in via -a lversion=$(cat ../VERSION) so the title page stays in sync without rewriting sources. * CJK fallback TTFs are generated lazily under $(DOC_FONT_DIR) via otf2ttf.py and pdf-fontsdir points at that directory plus GEM_FONTS_DIR. * asciidoctor-pdf (via prawn) emits very verbose PDF content streams: ~32 KB/page vs ~20 KB/page from xdvipdfmx for the same source, so the master document came out 39 MB vs the official 26 MB with identical image content. Add a ghostscript pass that re-deflates streams without touching images (no /ebook downsampling, PassThroughJPEGImages, FlateEncode only) and the master drops to 25 MB, matching dblatex. Manpages * a2x --doctype manpage --format manpage becomes asciidoctor --doctype manpage --backend manpage. Asciidoctor emits .als / .URL / .MTO macros that po4a's man parser doesn't recognise by default, so the man_def alias gains -o untranslated=FF,FU,als -o unknown_macros=untranslated -o inline=URL,MTO. * The .so alias dependency line was missing the section directory; fixed in the same place. HTML manpages * a2x --backend html5 -> asciidoctor --doctype manpage --backend html5. Wholesale image extraction step * The old html-images bash glue piped HTML through xsltproc to pull out elements. Replace with a portable grep -oE so we can drop xsltproc and links.xslt at the same time. Translation file generation * objects/xref_.links and the per-language link database pipeline are gone; xref_resolver.rb does the same job at parse time. MAN_DEPS path bug * grep '^\.so ' was emitting deps as $(DOC_DIR)/man/%s, missing the section directory. Use $(*D) prefix so deps land under $(DOC_DIR)/man/
/. --- docs/po4a.cfg | 2 +- docs/src/Submakefile | 371 ++++++++++++------------------------------- src/Makefile.inc.in | 1 - src/configure.ac | 100 ++---------- 4 files changed, 112 insertions(+), 362 deletions(-) diff --git a/docs/po4a.cfg b/docs/po4a.cfg index 64d10d967a9..a57073004ae 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 diff --git a/docs/src/Submakefile b/docs/src/Submakefile index b62c9d5546f..cda05aaf3e3 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -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:]') @@ -374,19 +381,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)) @@ -515,19 +509,11 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% echo "Error: Cannot find manpage '$<' in adoc format"; \ exit 1; \ fi; \ - asciidoc \ + asciidoctor \ --doctype=manpage \ - --backend=html \ + --backend=html5 \ -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=../.." \ @@ -600,10 +586,60 @@ $(DOC_DIR)/html/index.html: $(DOC_SRCDIR)/index.tmpl objects/index.incl $(DOC_SR (cat $(DOC_SRCDIR)/index.tmpl objects/index.incl $(DOC_SRCDIR)/index.foot) | sed "s/@VERSION@/`cat ../VERSION`/" | \ if [ "yes" != "$(BUILD_DOCS_TRANSLATED)" ]; then sed '/@TRANSLATIONS@/,/@ENDTRANSLATIONS@/d' ; else grep -Ev '@(END)?TRANSLATIONS@'; fi > $@ -$(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 = $(DOC_SRCDIR)/.fonts +NOTOCJK_TTC = /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ + /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc +CJK_TTFS = $(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf \ + $(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf + +# Build a TrueType (glyf-based) copy of the Simplified Chinese cut of the +# Noto Serif CJK font. Debian ships Noto Serif CJK 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. +$(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf: /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc $(DOC_SRCDIR)/otf2ttf.py + @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) $< $@.tmp && mv $@.tmp $@ + +$(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc $(DOC_SRCDIR)/otf2ttf.py + @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) $< $@.tmp && mv $@.tmp $@ + +$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(CJK_TTFS) $(ECHO) Building $@ - @rm -f $@ - $(Q)$(A2X) -L -d book -vf pdf $< || (X=$$?; rm -f $@; exit $$X) + @rm -f $@ $@.raw + $(Q)asciidoctor-pdf \ + -r $(realpath $(DOC_SRCDIR))/extensions/xref_resolver.rb \ + -r $(realpath $(DOC_SRCDIR))/extensions/image_resolver.rb \ + --sourcemap \ + -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 \ + -d book \ + -o $@.raw $< || (X=$$?; rm -f $@.raw; 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 +648,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 +659,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 @@ -736,187 +721,41 @@ $(DOC_SRCDIR)/%.html: STYLES_SCRIPTS=$(shell \ fi \ ) -$(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 \ +# 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 + $$(ECHO) "Building '$1' adoc to html: " $$< + $$(Q)asciidoctor -r $$(realpath $$(DOC_SRCDIR))/extensions/xref_resolver.rb \ + -a xref-root=$2 \ + -a "xref-exclude=$3" \ -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" \ + $$(STYLES_SCRIPTS) \ + -a "scriptdir=$$(DOC_SRCDIR)/" \ + -a "relindir=$$(shell dirname $$*)" \ -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 + -a source-highlighter=rouge \ + -d book -a toc -a numbered \ + -o $$@ $$< || (X=$$$$?; rm -f $$@; exit $$$$X) +endef -# Declare all final HTML targets -HTML_TARGETS := $(foreach L,$(LANGUAGES),$(DOC_DIR)/html/$(L)/xref.html) +# 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))/)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,ar,$(DOC_SRCDIR)/ar)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,de,$(DOC_SRCDIR)/de)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,es,$(DOC_SRCDIR)/es)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,fr,$(DOC_SRCDIR)/fr)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,nb,$(DOC_SRCDIR)/nb)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,ru,$(DOC_SRCDIR)/ru)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,sv,$(DOC_SRCDIR)/sv)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,ta,$(DOC_SRCDIR)/ta)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,tr,$(DOC_SRCDIR)/tr)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,uk,$(DOC_SRCDIR)/uk)) +$(eval $(call ASCIIDOCTOR_HTML_RULE,zh_CN,$(DOC_SRCDIR)/zh_CN)) -$(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 +787,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/*.* @@ -983,7 +823,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 '{printf " \\\n\t$(DOC_DIR)/man/$(*D)/%s", $$2}' >> $@.tmp $(Q)echo >> $@.tmp $(Q)mv -f $@.tmp $@ @@ -1020,26 +860,13 @@ 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 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/src/Makefile.inc.in b/src/Makefile.inc.in index 223062d996a..b21efaf58b9 100644 --- a/src/Makefile.inc.in +++ b/src/Makefile.inc.in @@ -130,7 +130,6 @@ BUILD_DOCS_TRANSLATED = @BUILD_DOCS_TRANSLATED@ 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@ diff --git a/src/configure.ac b/src/configure.ac index 3afc17337f2..93f8432b20a 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1063,80 +1063,24 @@ AC_ARG_ENABLE(build-documentation, # Programs required for building all documentation 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]) + AC_PATH_PROG(ASCIIDOCTOR,asciidoctor,"none") + if ( test "none" = "$ASCIIDOCTOR" ) ; then + AC_MSG_WARN([no asciidoctor, 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]) - BUILD_DOCS=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]) - BUILD_DOCS=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(GS,gs,"none") + if ( test "none" = "$GS" ) ; then + AC_MSG_WARN([no gs, documentation cannot be built]) BUILD_DOCS=no fi fi 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_PATH_PROG(RSVG_CONVERT,rsvg-convert,"none") + if ( test "none" = "$RSVG_CONVERT" ) ; then + AC_MSG_WARN([no rsvg-convert, documentation cannot be built]) BUILD_DOCS=no fi fi @@ -1144,35 +1088,15 @@ 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]) + AC_PATH_PROG(ASCIIDOCTOR_PDF,asciidoctor-pdf,"none") + if ( test "none" = "$ASCIIDOCTOR_PDF" ) ; then + AC_MSG_WARN([no asciidoctor-pdf, PDF documentation cannot be built]) BUILD_DOCS=no 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 - 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 - 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) - fi - AC_PATH_PROG(CHECKLINK,checklink,"none") if ( test "none" = "$CHECKLINK" ) ; then AC_MSG_WARN([no checklink, HTML documentation cannot be built From 2a8bcfa216d8edda4a162d5ba9d116f0c6592aa9 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 21:39:55 +0800 Subject: [PATCH 03/30] docs: drop the asciidoc-py / dblatex / xsltproc infrastructure With the Submakefile fully routed through asciidoctor, these files are no longer referenced by anything. asciidoc-py rendering hooks (XHTML and DocBook backends): * docs/src/xhtml11.conf, xhtml11-head-foot.conf, xhtml11-latexmath.conf, xhtml11-links.conf * docs/src/docbook.conf, docbook-image.conf * docs/src/asciidoc-dont-replace-arrows.conf * docs/src/attribute-colon.conf dblatex LaTeX style: * docs/src/emc2.sty (replaced by docs/src/pdf-theme.yml) xsltproc-based xref/image pipeline: * docs/src/html-images.xslt -- HTML img-src extraction (replaced by a grep -oE) * docs/src/html-latex-images -- shell glue around xsltproc * docs/src/image-wildcard -- relative-image-path resolution shim (replaced by docs/src/extensions/image_resolver.rb) * docs/src/links.xslt + docs/src/links_db_gen.py -- per-language anchor index (replaced by docs/src/extensions/xref_resolver.rb) Inkscape SVG shim from PR #4043: * scripts/inkscape -- routed dblatex's hard-coded inkscape call through rsvg-convert. asciidoctor-pdf renders SVGs natively via prawn-svg, so the shim has nothing to intercept and no warnings to suppress. --- 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/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 ------------- 15 files changed, 599 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/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/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/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 From 6ae32b5218210ff191b5094b0b36b24b5cb9563f Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 21:40:10 +0800 Subject: [PATCH 04/30] debian: switch documentation build-deps to the asciidoctor toolchain DOC_DEPENDS shrinks from twenty packages (dblatex stack, ten texlive-lang-*, source-highlight, inkscape, python3-lxml, xsltproc, dvipng, groff) to ten packages spanning the asciidoctor render path plus a couple of font/conversion helpers: * asciidoctor + ruby-asciidoctor-pdf + ruby-rouge -- the engines. * fonts-dejavu, fonts-noto-cjk -- code-block mono / CJK fallback. * python3-fonttools -- otf2ttf.py needs ttLib + cu2quPen. * ghostscript -- PDF post-process pass. * graphviz, librsvg2-bin, w3c-linkchecker -- unchanged carry-overs. control.top.in drops docbook-xsl, asciidoc and asciidoc-dblatex from top-level Build-Depends. ghostscript moves out from there because it is now an explicit doc-time dep, listed by name in DOC_DEPENDS. Distribution coverage verified: every package is in bookworm, trixie, sid, and noble (the suites our CI targets). --- debian/configure | 14 +------------- debian/control.top.in | 6 ++---- 2 files changed, 3 insertions(+), 17 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 1016d940fc9..1f783d1a263 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), From c5c75510646e1dbaa77f7f13381f9e62615147d6 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 21:41:06 +0800 Subject: [PATCH 05/30] ci: parallelize the Debian package build via DEB_BUILD_OPTIONS debuild leaves dpkg-buildpackage in serial mode unless DEB_BUILD_OPTIONS=parallel=N is in the environment. dh_auto_build honours that variable and translates it into make -jN, so opting in fans out the C/C++ build and the per-language doc rules across all the runner's CPUs. Local measurement on an 8-core box: binary-indep wall time 32 min -> 7 min for the doc-only stage. build-doc.sh already passes -j directly to make; this matches that behaviour for the deb package CI jobs. --- .github/scripts/build-package-arch.sh | 2 ++ .github/scripts/build-package-indep.sh | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/scripts/build-package-arch.sh b/.github/scripts/build-package-arch.sh index 1b6ba870fc4..2bbcd7480d1 100755 --- a/.github/scripts/build-package-arch.sh +++ b/.github/scripts/build-package-arch.sh @@ -8,4 +8,6 @@ debian/update-dch-from-git scripts/get-version-from-git | sed -re 's/^v(.*)$/\1/' >| VERSION; cat VERSION git diff apt-get --yes build-dep --arch-only . +DEB_BUILD_OPTIONS="parallel=$(nproc)" +export DEB_BUILD_OPTIONS debuild -us -uc --build=any diff --git a/.github/scripts/build-package-indep.sh b/.github/scripts/build-package-indep.sh index 53093597c49..9bb6b0642f3 100755 --- a/.github/scripts/build-package-indep.sh +++ b/.github/scripts/build-package-indep.sh @@ -8,4 +8,6 @@ debian/update-dch-from-git scripts/get-version-from-git | sed -re 's/^v(.*)$/\1/' >| VERSION; cat VERSION git diff apt-get --yes build-dep --indep-only . +DEB_BUILD_OPTIONS="parallel=$(nproc)" +export DEB_BUILD_OPTIONS debuild -us -uc --build=source,all From a022dc098da1530fcc02f8267b8cd0f6f8fd2859 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sat, 23 May 2026 23:12:51 +0800 Subject: [PATCH 06/30] docs: fix source issues the asciidoctor parser flags asciidoctor reports these as ERROR or WARNING; asciidoc-py silently tolerated them. All predate the toolchain swap. * hal/halmodule.adoc: cols spec said 5 columns, every row had 7 cells, so the trailing 1 cell hung off the end of the last row. Bump to cols="<3s,6*<". * plasma/qtplasmac.adoc 'color5' row in the styling table was missing the middle Parameter cell. Fill in 'Disabled' so the row matches. * plasma/qtplasmac.adoc QtPlasmaC state-table 'DEBUG' row was missing the Description cell; the existing prose immediately below the table already provides the wording. * gui/qtdragon.adoc Versaprobe NOTE was authored with no `====` delimiters, so asciidoctor read it as '[NOTE]' applied as an unknown list style. Wrap in delimiters. * gui/qtvcp-widgets.adoc Markdown-style ``` fenced block. po4a collapsed it into a single line during translation extraction, so every translated build saw an open ``` with no matching close and emitted "unterminated listing block". Replace with the equivalent asciidoc [source,python] / ---- block, which po4a preserves line-by-line. * lathe/images/control-point_es.svg flowRoot/flowPara element ("tan" label added by the Spanish translator). flowRoot is an Inkscape-only SVG 1.2 element that prawn-svg cannot render. Convert to a regular / at the same coordinates. * docs/po4a.cfg: add hal/halscope.adoc to the translated tree. It is included by hal/tutorial.adoc, which IS translated, so every translated build failed to resolve the include. --- docs/po4a.cfg | 1 + docs/src/gui/qtdragon.adoc | 2 ++ docs/src/gui/qtvcp-widgets.adoc | 5 +++-- docs/src/hal/halmodule.adoc | 2 +- docs/src/lathe/images/control-point_es.svg | 19 +++++++++---------- docs/src/plasma/qtplasmac.adoc | 4 ++-- 6 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/po4a.cfg b/docs/po4a.cfg index a57073004ae..807df091f26 100644 --- a/docs/po4a.cfg +++ b/docs/po4a.cfg @@ -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 diff --git a/docs/src/gui/qtdragon.adoc b/docs/src/gui/qtdragon.adoc index 6135376354b..8f42e169f20 100644 --- a/docs/src/gui/qtdragon.adoc +++ b/docs/src/gui/qtdragon.adoc @@ -1208,10 +1208,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. diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc index 1a75c744866..df0d7b73aa3 100644 --- a/docs/src/gui/qtvcp-widgets.adoc +++ b/docs/src/gui/qtvcp-widgets.adoc @@ -2722,10 +2722,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 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/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 + Date: Sat, 23 May 2026 23:13:03 +0800 Subject: [PATCH 07/30] docs: resolve inline image macros and fall back to EN tree Two limitations of the original image_resolver were causing the remaining 'image to embed not found or not readable' warnings in translated PDFs: Inline image: macros never showed up in find_by(:inline_image). Asciidoctor parses them as part of block text and never lifts them into standalone nodes. Walk each block, regex-rewrite image:PATH[ inside the source storage that the block actually keeps (lines= for paragraphs, text= for list items), and re-enter inner_documents of asciidoc-style table cells so cells with embedded images get touched too. Translated trees often reference images that exist only at the canonical English path. Add a fallback: after probing the file under docs/src//.../images/, retry with the language segment stripped (docs/src/.../images/). This is how the dblatex pipeline behaved implicitly via the image-wildcard shim. End-to-end `make -j8 pdfdocs` warning count is now 8 across all 33 PDFs, down from 40+ before. Remaining warnings are non-blocking content quirks (one unterminated listing block, three Inkscape 'flowRoot' SVG elements in es/lathe/) and worth a follow-up. --- docs/src/extensions/image_resolver.rb | 92 +++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 5 deletions(-) diff --git a/docs/src/extensions/image_resolver.rb b/docs/src/extensions/image_resolver.rb index 853bd208cfe..229b80c4a27 100644 --- a/docs/src/extensions/image_resolver.rb +++ b/docs/src/extensions/image_resolver.rb @@ -15,6 +15,14 @@ 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 = /(?/ are not always populated for every macro a + # translated file references, but the English original at + # docs/src/.../ usually exists. + def resolve_candidate(path) + 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 + 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)) + + # :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) { 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) { changed = true } + block.text = new_text if changed + end + end + end + + def rewrite_inline(text, base_dir) + 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?('{') + + candidate = resolve_candidate(File.expand_path(target, base_dir)) + 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 From 7f511e8c31fd9ae858b67294f14c4ec61776089e Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 18:27:27 +0800 Subject: [PATCH 08/30] docs: add Rouge lexers for HAL and NGC, wire highlighter into the build Bertho noted in the review of #4053 that the new build dropped syntax highlighting for HAL and NGC source blocks; rouge ships an INI lexer but has neither of the two LinuxCNC-specific languages, so blocks like [source,{hal}] and [source,{ngc}] rendered as plain text. * Two rouge lexers, ~80 lines each, ported line-for-line from the old source-highlight definitions at docs/src/source-highlight/hal.lang and ngc.lang (Michael Haberler, 2011). Same keyword coverage: halcmd commands, pin/signal names, INI substitutions and env vars for HAL; G/M/T/F/S codes, axis letters, parameters, O-words and the math/boolean built-ins for NGC. * All four asciidoctor invocations in the Submakefile (PDF, HTML, manpage HTML, ASCIIDOCTOR_HTML_RULE) gain '-r .../rouge_hal.rb -r .../rouge_ngc.rb' so the lexers are visible to rouge before the document is parsed. The manpage HTML rule also gains an explicit '-a source-highlighter=rouge' that the others already inherit from attribute defaults. * The :ngc: / :hal: / :ini: / :css: / :nml: attribute defs in the source files used asciidoc-py's '{basebackend@docbook:'':ngc}' conditional syntax (which asciidoctor does not implement) to emit the language only when targeting docbook. All toolchain backends used by this PR now want the language name unconditionally, so the attribute defs collapse to ':ngc: ngc' etc. 84 source files touched, no .adoc body changes. --- docs/src/Submakefile | 7 ++ docs/src/code/code-notes.adoc | 6 +- docs/src/code/contributing-to-linuxcnc.adoc | 6 +- docs/src/code/rs274.adoc | 6 +- docs/src/config/core-components.adoc | 6 +- docs/src/config/ini-config.adoc | 6 +- docs/src/config/ini-homing.adoc | 6 +- docs/src/config/lathe-config.adoc | 6 +- docs/src/config/moveoff.adoc | 6 +- docs/src/config/python-hal-interface.adoc | 6 +- docs/src/config/python-interface.adoc | 6 +- docs/src/config/stepper-diagnostics.adoc | 6 +- docs/src/config/stepper.adoc | 6 +- docs/src/drivers/ax5214h.adoc | 6 +- docs/src/drivers/gm.adoc | 6 +- docs/src/drivers/gs2.adoc | 6 +- docs/src/drivers/hostmot2.adoc | 6 +- docs/src/drivers/mb2hal.adoc | 6 +- docs/src/drivers/mitsub-vfd.adoc | 8 +- docs/src/drivers/motenc.adoc | 6 +- docs/src/drivers/opto22.adoc | 6 +- docs/src/drivers/pico-ppmc.adoc | 6 +- docs/src/drivers/pmx485.adoc | 6 +- docs/src/drivers/servo-to-go.adoc | 6 +- docs/src/drivers/vfs11.adoc | 6 +- docs/src/examples/gs2-example.adoc | 6 +- docs/src/examples/mpg.adoc | 6 +- docs/src/examples/pci-parallel-port.adoc | 6 +- docs/src/examples/spindle.adoc | 6 +- docs/src/extensions/rouge_hal.rb | 74 +++++++++++++ docs/src/extensions/rouge_ngc.rb | 103 ++++++++++++++++++ docs/src/gcode/coordinates.adoc | 6 +- docs/src/gcode/g-code.adoc | 6 +- docs/src/gcode/m-code.adoc | 6 +- docs/src/gcode/machining-center.adoc | 6 +- docs/src/gcode/o-code.adoc | 6 +- docs/src/gcode/overview.adoc | 6 +- docs/src/gcode/rs274ngc.adoc | 6 +- docs/src/gcode/tool-compensation.adoc | 6 +- .../getting-started/updating-linuxcnc.adoc | 6 +- docs/src/gui/axis.adoc | 6 +- docs/src/gui/filter-programs.adoc | 6 +- docs/src/gui/gladevcp-libraries.adoc | 6 +- docs/src/gui/gladevcp-panels.adoc | 6 +- docs/src/gui/gladevcp.adoc | 6 +- docs/src/gui/gmoccapy.adoc | 8 +- docs/src/gui/gscreen.adoc | 6 +- docs/src/gui/gui-dev-reference.adoc | 8 +- docs/src/gui/halui.adoc | 6 +- docs/src/gui/image-to-gcode.adoc | 6 +- docs/src/gui/mdro.adoc | 6 +- docs/src/gui/ngcgui.adoc | 6 +- docs/src/gui/panelui.adoc | 6 +- docs/src/gui/pyvcp-examples.adoc | 6 +- docs/src/gui/pyvcp.adoc | 6 +- docs/src/gui/qtdragon.adoc | 6 +- docs/src/gui/qtvcp-libraries.adoc | 6 +- docs/src/gui/qtvcp-vcp-panels.adoc | 6 +- docs/src/gui/qtvcp-widgets.adoc | 8 +- docs/src/gui/qtvcp.adoc | 8 +- docs/src/gui/tklinuxcnc.adoc | 6 +- docs/src/gui/tooledit.adoc | 6 +- docs/src/gui/touchy.adoc | 6 +- docs/src/hal/basic-hal.adoc | 6 +- docs/src/hal/comp.adoc | 6 +- docs/src/hal/hal-examples.adoc | 6 +- docs/src/hal/halshow.adoc | 6 +- docs/src/hal/haltcl.adoc | 6 +- docs/src/hal/halui-examples.adoc | 6 +- docs/src/hal/intro.adoc | 6 +- docs/src/hal/parallel-port.adoc | 6 +- docs/src/hal/tools.adoc | 6 +- docs/src/hal/twopass.adoc | 6 +- docs/src/ladder/classic-ladder.adoc | 6 +- docs/src/ladder/ladder-examples.adoc | 6 +- docs/src/lathe/lathe-user.adoc | 6 +- docs/src/motion/5-axis-kinematics.adoc | 6 +- docs/src/motion/external-offsets.adoc | 6 +- docs/src/motion/switchkins.adoc | 6 +- docs/src/plasma/plasma-cnc-primer.adoc | 6 +- docs/src/plasma/qtplasmac.adoc | 6 +- docs/src/remap/remap.adoc | 6 +- docs/src/source-highlight/hal-demo.adoc | 6 +- docs/src/source-highlight/ini-demo.adoc | 6 +- docs/src/source-highlight/ngc-demo.adoc | 6 +- docs/src/tooldatabase/tooldatabase.adoc | 6 +- docs/src/user/user-concepts.adoc | 6 +- 87 files changed, 441 insertions(+), 257 deletions(-) create mode 100644 docs/src/extensions/rouge_hal.rb create mode 100644 docs/src/extensions/rouge_ngc.rb diff --git a/docs/src/Submakefile b/docs/src/Submakefile index cda05aaf3e3..e4f617548d8 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -510,6 +510,8 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% exit 1; \ fi; \ asciidoctor \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ --doctype=manpage \ --backend=html5 \ -a mansource=LinuxCNC \ @@ -518,6 +520,7 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% -a "scriptsdir=../.." \ -a "stylesdir=../.." \ -a stylesheet=linuxcnc.css \ + -a source-highlighter=rouge \ -o $@ \ "$$F" \ ; \ @@ -619,6 +622,8 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(Q)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 \ --sourcemap \ -a xref-root=$(dir $<) \ -a "xref-exclude=^($(LANGUAGES_MATCH))/" \ @@ -728,6 +733,8 @@ define ASCIIDOCTOR_HTML_RULE $$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$(DOC_SRCDIR)/%.html: $$(DOC_SRCDIR)/%.adoc $$(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 \ -a xref-root=$2 \ -a "xref-exclude=$3" \ -a linkcss \ diff --git a/docs/src/code/code-notes.adoc b/docs/src/code/code-notes.adoc index 89b8dea799a..46e5941b17f 100644 --- a/docs/src/code/code-notes.adoc +++ b/docs/src/code/code-notes.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Intended audience diff --git a/docs/src/code/contributing-to-linuxcnc.adoc b/docs/src/code/contributing-to-linuxcnc.adoc index 9626599abab..d87f5556d5a 100644 --- a/docs/src/code/contributing-to-linuxcnc.adoc +++ b/docs/src/code/contributing-to-linuxcnc.adoc @@ -5,9 +5,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/code/rs274.adoc b/docs/src/code/rs274.adoc index 44c88bc6d15..128198b5da5 100644 --- a/docs/src/code/rs274.adoc +++ b/docs/src/code/rs274.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc The rs274 stand alone interpreter is available for use via the command line. diff --git a/docs/src/config/core-components.adoc b/docs/src/config/core-components.adoc index 2c54eebdf18..e780f19f68d 100644 --- a/docs/src/config/core-components.adoc +++ b/docs/src/config/core-components.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Core components))) See also the man pages 'motion(9)'. diff --git a/docs/src/config/ini-config.adoc b/docs/src/config/ini-config.adoc index 6a301a39cf4..2bb5bb3429b 100644 --- a/docs/src/config/ini-config.adoc +++ b/docs/src/config/ini-config.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == The INI File Components(((INI File,Components))) diff --git a/docs/src/config/ini-homing.adoc b/docs/src/config/ini-homing.adoc index cfe03d3a361..65fecdf9cbd 100644 --- a/docs/src/config/ini-homing.adoc +++ b/docs/src/config/ini-homing.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Overview diff --git a/docs/src/config/lathe-config.adoc b/docs/src/config/lathe-config.adoc index 7e12544f033..d85019bc3d0 100644 --- a/docs/src/config/lathe-config.adoc +++ b/docs/src/config/lathe-config.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Default Plane diff --git a/docs/src/config/moveoff.adoc b/docs/src/config/moveoff.adoc index 45d75365af6..097ce3fa8ef 100644 --- a/docs/src/config/moveoff.adoc +++ b/docs/src/config/moveoff.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc The moveoff HAL component is a HAL-only method for implementing offsets. See the manpage ('$ man moveoff') for the IMPORTANT limitations and warnings. diff --git a/docs/src/config/python-hal-interface.adoc b/docs/src/config/python-hal-interface.adoc index 90f6d913bd0..815932b744f 100644 --- a/docs/src/config/python-hal-interface.adoc +++ b/docs/src/config/python-hal-interface.adoc @@ -4,9 +4,9 @@ [[cha:python-hal-interface]] = The HAL Python module -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: 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..d74f3fbec59 100644 --- a/docs/src/config/python-interface.adoc +++ b/docs/src/config/python-interface.adoc @@ -4,9 +4,9 @@ [[cha:python-interface]] = The LinuxCNC Python module -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: 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..598371878b6 100644 --- a/docs/src/config/stepper-diagnostics.adoc +++ b/docs/src/config/stepper-diagnostics.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Stepper Diagnostics))) If what you get is not what you expect many times you just got some diff --git a/docs/src/config/stepper.adoc b/docs/src/config/stepper.adoc index 562af551e2d..1a2f2ad0813 100644 --- a/docs/src/config/stepper.adoc +++ b/docs/src/config/stepper.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/drivers/ax5214h.adoc b/docs/src/drivers/ax5214h.adoc index a21be849f0e..8cd58d02ecb 100644 --- a/docs/src/drivers/ax5214h.adoc +++ b/docs/src/drivers/ax5214h.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/drivers/gm.adoc b/docs/src/drivers/gm.adoc index 93d96aabc0a..98cd8cbaf5b 100644 --- a/docs/src/drivers/gm.adoc +++ b/docs/src/drivers/gm.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc General Mechatronics GM6-PCI card based motion control system diff --git a/docs/src/drivers/gs2.adoc b/docs/src/drivers/gs2.adoc index 0aadefbab66..41a0830d27c 100644 --- a/docs/src/drivers/gs2.adoc +++ b/docs/src/drivers/gs2.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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.] diff --git a/docs/src/drivers/hostmot2.adoc b/docs/src/drivers/hostmot2.adoc index cc6845f663f..9603c1eea4d 100644 --- a/docs/src/drivers/hostmot2.adoc +++ b/docs/src/drivers/hostmot2.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/drivers/mb2hal.adoc b/docs/src/drivers/mb2hal.adoc index b4fd7ffc5f3..a63e1aebda5 100644 --- a/docs/src/drivers/mb2hal.adoc +++ b/docs/src/drivers/mb2hal.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/drivers/mitsub-vfd.adoc b/docs/src/drivers/mitsub-vfd.adoc index 06b9f982319..85fccb44521 100644 --- a/docs/src/drivers/mitsub-vfd.adoc +++ b/docs/src/drivers/mitsub-vfd.adoc @@ -6,11 +6,11 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc -:hal: {basebackend@docbook:'':hal} +:hal: hal This is a non-realtime HAL program, written in Python, to control VFDs from Mitsubishi. + diff --git a/docs/src/drivers/motenc.adoc b/docs/src/drivers/motenc.adoc index 65e7e96b5f9..87c3c56b03d 100644 --- a/docs/src/drivers/motenc.adoc +++ b/docs/src/drivers/motenc.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc Vital Systems Motenc-100 and Motenc-LITE diff --git a/docs/src/drivers/opto22.adoc b/docs/src/drivers/opto22.adoc index 5bff01e9544..67385e9387f 100644 --- a/docs/src/drivers/opto22.adoc +++ b/docs/src/drivers/opto22.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc *PCI AC5 ADAPTER CARD / HAL DRIVER* diff --git a/docs/src/drivers/pico-ppmc.adoc b/docs/src/drivers/pico-ppmc.adoc index 0c72079d121..958d004c1bf 100644 --- a/docs/src/drivers/pico-ppmc.adoc +++ b/docs/src/drivers/pico-ppmc.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/drivers/pmx485.adoc b/docs/src/drivers/pmx485.adoc index 6113bc3e9a9..d1365bb754a 100644 --- a/docs/src/drivers/pmx485.adoc +++ b/docs/src/drivers/pmx485.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc This is a non-realtime HAL program, written in python, to control Hypetherm Powermax plasma cutters using the Modbus ASCII protocol over RS485. diff --git a/docs/src/drivers/servo-to-go.adoc b/docs/src/drivers/servo-to-go.adoc index 64703001874..9e02b24e87b 100644 --- a/docs/src/drivers/servo-to-go.adoc +++ b/docs/src/drivers/servo-to-go.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/drivers/vfs11.adoc b/docs/src/drivers/vfs11.adoc index 752b71c0ea1..03f076869fc 100644 --- a/docs/src/drivers/vfs11.adoc +++ b/docs/src/drivers/vfs11.adoc @@ -4,9 +4,9 @@ [[cha:vfs11-vfd]] = VFS11 VFD Driver -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc This is a non-realtime HAL program to control the S11 series of VFDs from Toshiba. diff --git a/docs/src/examples/gs2-example.adoc b/docs/src/examples/gs2-example.adoc index eb848baf5c3..cefba36369a 100644 --- a/docs/src/examples/gs2-example.adoc +++ b/docs/src/examples/gs2-example.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Example diff --git a/docs/src/examples/mpg.adoc b/docs/src/examples/mpg.adoc index bf827284a25..34ea842af52 100644 --- a/docs/src/examples/mpg.adoc +++ b/docs/src/examples/mpg.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/examples/pci-parallel-port.adoc b/docs/src/examples/pci-parallel-port.adoc index 084659633a2..6d555f7c8a2 100644 --- a/docs/src/examples/pci-parallel-port.adoc +++ b/docs/src/examples/pci-parallel-port.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/examples/spindle.adoc b/docs/src/examples/spindle.adoc index 67ff0427d8b..dba1bd14876 100644 --- a/docs/src/examples/spindle.adoc +++ b/docs/src/examples/spindle.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/extensions/rouge_hal.rb b/docs/src/extensions/rouge_hal.rb new file mode 100644 index 00000000000..32b4bb79776 --- /dev/null +++ b/docs/src/extensions/rouge_hal.rb @@ -0,0 +1,74 @@ +# 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 +# - environment variables $VAR $(VAR) +# - assignment operators = => <= +# - numbers and 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 + ].join('|').freeze + + 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 + rule %r/\[[A-Z_][A-Z0-9_]*\][A-Z_][A-Z0-9_]*/i, Name::Constant + + # Environment variables + rule %r/\$\([A-Z_][A-Z0-9_]*\)/i, Name::Variable + rule %r/\$[A-Z_][A-Z0-9_]*/i, Name::Variable + + # Pin/signal names: token with at least one dot + rule %r/[A-Za-z_][\w-]*(?:\.[\w-]+)+/, Name::Attribute + + # Numbers (signed, optional decimal, optional exponent) + rule %r/[+-]?\d+\.\d+(?:[eE][+-]?\d+)?/, Num::Float + rule %r/[+-]?\d+(?:[eE][+-]?\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_ngc.rb b/docs/src/extensions/rouge_ngc.rb new file mode 100644 index 00000000000..0ccbcc6a881 --- /dev/null +++ b/docs/src/extensions/rouge_ngc.rb @@ -0,0 +1,103 @@ +# 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 & argument letters X Y Z A B C U V W I J K P Q R L +# - numeric, named, and indexed parameters #1 #5421 # +# - 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 + + 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 + + # Parameters + 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 and argument letters followed by a value or expression + rule %r/(?i:[xyzabcuvwijkpqrle])(?=\s*[-+\[\d#])/, Name::Attribute + + # Arithmetic / brackets + rule %r{[+\-*/=]}, Operator + rule %r/[\[\]]/, Punctuation + + # Numbers + rule %r/[+-]?\d+\.\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 diff --git a/docs/src/gcode/coordinates.adoc b/docs/src/gcode/coordinates.adoc index eb81ac45b64..eed687fc179 100644 --- a/docs/src/gcode/coordinates.adoc +++ b/docs/src/gcode/coordinates.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gcode/g-code.adoc b/docs/src/gcode/g-code.adoc index c9840103486..7f2be1e2712 100644 --- a/docs/src/gcode/g-code.adoc +++ b/docs/src/gcode/g-code.adoc @@ -4,9 +4,9 @@ [[cha:g-codes]] = G-Codes -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc == Conventions diff --git a/docs/src/gcode/m-code.adoc b/docs/src/gcode/m-code.adoc index a63bf47417b..a3e3956a8c8 100644 --- a/docs/src/gcode/m-code.adoc +++ b/docs/src/gcode/m-code.adoc @@ -4,9 +4,9 @@ [[cha:m-codes]] = M-Codes -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc == M-Code Quick Reference Table diff --git a/docs/src/gcode/machining-center.adoc b/docs/src/gcode/machining-center.adoc index 5005ab9d07c..0e8b890b268 100644 --- a/docs/src/gcode/machining-center.adoc +++ b/docs/src/gcode/machining-center.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Machine Overview))) This section gives a brief description of how a CNC machine is viewed diff --git a/docs/src/gcode/o-code.adoc b/docs/src/gcode/o-code.adoc index c2a4362127d..720e8e7a878 100644 --- a/docs/src/gcode/o-code.adoc +++ b/docs/src/gcode/o-code.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Use of O-codes diff --git a/docs/src/gcode/overview.adoc b/docs/src/gcode/overview.adoc index 261aa434502..8a53deb17d1 100644 --- a/docs/src/gcode/overview.adoc +++ b/docs/src/gcode/overview.adoc @@ -5,9 +5,9 @@ [[cha:overview-of-g-code-programming]] = Overview of G-Code Programming -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc // begin a listing of INI/HAL/NGC files like so: //[source,{ini}] //[source,{hal}] diff --git a/docs/src/gcode/rs274ngc.adoc b/docs/src/gcode/rs274ngc.adoc index d67b236f3ef..452a189ae40 100644 --- a/docs/src/gcode/rs274ngc.adoc +++ b/docs/src/gcode/rs274ngc.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Changes from RS274/NGC diff --git a/docs/src/gcode/tool-compensation.adoc b/docs/src/gcode/tool-compensation.adoc index d67fdeb59b5..9c6ea9d7242 100644 --- a/docs/src/gcode/tool-compensation.adoc +++ b/docs/src/gcode/tool-compensation.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Tool Compensation))) diff --git a/docs/src/getting-started/updating-linuxcnc.adoc b/docs/src/getting-started/updating-linuxcnc.adoc index c671778b709..601eaa378db 100644 --- a/docs/src/getting-started/updating-linuxcnc.adoc +++ b/docs/src/getting-started/updating-linuxcnc.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 diff --git a/docs/src/gui/axis.adoc b/docs/src/gui/axis.adoc index cf37dcf03cd..b2322c97843 100644 --- a/docs/src/gui/axis.adoc +++ b/docs/src/gui/axis.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((AXIS GUI))) diff --git a/docs/src/gui/filter-programs.adoc b/docs/src/gui/filter-programs.adoc index c15ed1de3d9..547edd4e6f2 100644 --- a/docs/src/gui/filter-programs.adoc +++ b/docs/src/gui/filter-programs.adoc @@ -7,9 +7,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/gui/gladevcp-libraries.adoc b/docs/src/gui/gladevcp-libraries.adoc index 7e60b0102f6..d881e8ba117 100644 --- a/docs/src/gui/gladevcp-libraries.adoc +++ b/docs/src/gui/gladevcp-libraries.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/gui/gladevcp-panels.adoc b/docs/src/gui/gladevcp-panels.adoc index 9dbf3378112..dd3740f0b42 100644 --- a/docs/src/gui/gladevcp-panels.adoc +++ b/docs/src/gui/gladevcp-panels.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc GladeVCP can be used to *create control panels* that interface with _HAL_ and/or the motion controller. diff --git a/docs/src/gui/gladevcp.adoc b/docs/src/gui/gladevcp.adoc index 9ac258e0007..6e8c92bc2a0 100644 --- a/docs/src/gui/gladevcp.adoc +++ b/docs/src/gui/gladevcp.adoc @@ -10,9 +10,9 @@ // - check wiki vs docs // - check other GladeVCP docs branch against this -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc // begin a listing of INI/HAL/NGC files like so: //[source,{ini}] //[source,{hal}] diff --git a/docs/src/gui/gmoccapy.adoc b/docs/src/gui/gmoccapy.adoc index 0802a8b8be1..58eb9bec69d 100644 --- a/docs/src/gui/gmoccapy.adoc +++ b/docs/src/gui/gmoccapy.adoc @@ -7,10 +7,10 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc +:css: css == Introduction diff --git a/docs/src/gui/gscreen.adoc b/docs/src/gui/gscreen.adoc index f030dca6bee..3b9765755cd 100644 --- a/docs/src/gui/gscreen.adoc +++ b/docs/src/gui/gscreen.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/gui-dev-reference.adoc b/docs/src/gui/gui-dev-reference.adoc index 865fd5d34d6..5cc5cd9a177 100644 --- a/docs/src/gui/gui-dev-reference.adoc +++ b/docs/src/gui/gui-dev-reference.adoc @@ -6,10 +6,10 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc +:css: 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, diff --git a/docs/src/gui/halui.adoc b/docs/src/gui/halui.adoc index b94e8c0e861..dfce0356fa0 100644 --- a/docs/src/gui/halui.adoc +++ b/docs/src/gui/halui.adoc @@ -7,9 +7,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/image-to-gcode.adoc b/docs/src/gui/image-to-gcode.adoc index bd20eaac95a..877987d94a4 100644 --- a/docs/src/gui/image-to-gcode.adoc +++ b/docs/src/gui/image-to-gcode.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc image::images/image-to-gcode.png["Image to G-Code",align="center"] diff --git a/docs/src/gui/mdro.adoc b/docs/src/gui/mdro.adoc index 46515023e4b..6d9bb6c5bde 100644 --- a/docs/src/gui/mdro.adoc +++ b/docs/src/gui/mdro.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/ngcgui.adoc b/docs/src/gui/ngcgui.adoc index 9947b1ebee3..23e4a23ff3e 100644 --- a/docs/src/gui/ngcgui.adoc +++ b/docs/src/gui/ngcgui.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc .NGCGUI embedded into AXIS image::images/ngcgui.png[align="center"] diff --git a/docs/src/gui/panelui.adoc b/docs/src/gui/panelui.adoc index 9836e783384..9c4e158da6e 100644 --- a/docs/src/gui/panelui.adoc +++ b/docs/src/gui/panelui.adoc @@ -4,9 +4,9 @@ [[cha:Panelui]] = Panelui -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/pyvcp-examples.adoc b/docs/src/gui/pyvcp-examples.adoc index 32a65cfb6b9..61451ab32e9 100644 --- a/docs/src/gui/pyvcp-examples.adoc +++ b/docs/src/gui/pyvcp-examples.adoc @@ -5,9 +5,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == AXIS diff --git a/docs/src/gui/pyvcp.adoc b/docs/src/gui/pyvcp.adoc index 767eefbd289..a4f2733cbae 100644 --- a/docs/src/gui/pyvcp.adoc +++ b/docs/src/gui/pyvcp.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/qtdragon.adoc b/docs/src/gui/qtdragon.adoc index 8f42e169f20..fa51ccb0ce9 100644 --- a/docs/src/gui/qtdragon.adoc +++ b/docs/src/gui/qtdragon.adoc @@ -5,9 +5,9 @@ [[cha:qtdragon-gui]] = QtDragon GUI -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/gui/qtvcp-libraries.adoc b/docs/src/gui/qtvcp-libraries.adoc index c175c95e866..bd9d238f203 100644 --- a/docs/src/gui/qtvcp-libraries.adoc +++ b/docs/src/gui/qtvcp-libraries.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/gui/qtvcp-vcp-panels.adoc b/docs/src/gui/qtvcp-vcp-panels.adoc index e1027e4383d..58205e72d8e 100644 --- a/docs/src/gui/qtvcp-vcp-panels.adoc +++ b/docs/src/gui/qtvcp-vcp-panels.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc QtVCP can be used to *create control panels* that interface with _HAL_. diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc index df0d7b73aa3..4fb56ec3803 100644 --- a/docs/src/gui/qtvcp-widgets.adoc +++ b/docs/src/gui/qtvcp-widgets.adoc @@ -6,10 +6,10 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc +:css: css *`Qtscreen`* uses _QtVCP widgets_ for LinuxCNC integration. diff --git a/docs/src/gui/qtvcp.adoc b/docs/src/gui/qtvcp.adoc index d74d1789fa8..7477a5580de 100644 --- a/docs/src/gui/qtvcp.adoc +++ b/docs/src/gui/qtvcp.adoc @@ -6,10 +6,10 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc +:css: css QtVCP is an *infrastructure to build custom CNC screens or control panels for LinuxCNC*. diff --git a/docs/src/gui/tklinuxcnc.adoc b/docs/src/gui/tklinuxcnc.adoc index 2743e4a507f..d03aecb7632 100644 --- a/docs/src/gui/tklinuxcnc.adoc +++ b/docs/src/gui/tklinuxcnc.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc [[sec:tklinuxcnc-intro]] == Introduction diff --git a/docs/src/gui/tooledit.adoc b/docs/src/gui/tooledit.adoc index 51a6e58feeb..a442b87d580 100644 --- a/docs/src/gui/tooledit.adoc +++ b/docs/src/gui/tooledit.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Overview diff --git a/docs/src/gui/touchy.adoc b/docs/src/gui/touchy.adoc index cbf707f5165..85a08d6228c 100644 --- a/docs/src/gui/touchy.adoc +++ b/docs/src/gui/touchy.adoc @@ -4,9 +4,9 @@ [[cha:touchy-gui]] = The Touchy Graphical User Interface -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc (((touchygui))) Touchy is a user interface for LinuxCNC meant for use on machine control panels, diff --git a/docs/src/hal/basic-hal.adoc b/docs/src/hal/basic-hal.adoc index f96a7b1c3a0..90a938cadcc 100644 --- a/docs/src/hal/basic-hal.adoc +++ b/docs/src/hal/basic-hal.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((HAL Basics))) This document provides a reference to the basics of HAL. diff --git a/docs/src/hal/comp.adoc b/docs/src/hal/comp.adoc index bb917eb2379..623f7c53dc3 100644 --- a/docs/src/hal/comp.adoc +++ b/docs/src/hal/comp.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((HAL Component Generator))) diff --git a/docs/src/hal/hal-examples.adoc b/docs/src/hal/hal-examples.adoc index d908af261ba..f3a11f55cd8 100644 --- a/docs/src/hal/hal-examples.adoc +++ b/docs/src/hal/hal-examples.adoc @@ -8,9 +8,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/hal/halshow.adoc b/docs/src/hal/halshow.adoc index 6fce76ab21f..62bb62d2aea 100644 --- a/docs/src/hal/halshow.adoc +++ b/docs/src/hal/halshow.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Halshow))) The script `halshow` can help you find your way around a running HAL. diff --git a/docs/src/hal/haltcl.adoc b/docs/src/hal/haltcl.adoc index 9208f5b7d02..89361a978dc 100644 --- a/docs/src/hal/haltcl.adoc +++ b/docs/src/hal/haltcl.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/hal/halui-examples.adoc b/docs/src/hal/halui-examples.adoc index 72b72046946..32b017f519b 100644 --- a/docs/src/hal/halui-examples.adoc +++ b/docs/src/hal/halui-examples.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Halui Examples))) For any Halui examples to work you need to add the following line to the [HAL] section of the INI file. diff --git a/docs/src/hal/intro.adoc b/docs/src/hal/intro.adoc index ee9b1c611ae..a818a71ae1b 100644 --- a/docs/src/hal/intro.adoc +++ b/docs/src/hal/intro.adoc @@ -7,9 +7,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((HAL Introduction))) LinuxCNC is about interacting with hardware. But few users have the same exact hardware specifications - similar, but not the same. diff --git a/docs/src/hal/parallel-port.adoc b/docs/src/hal/parallel-port.adoc index 5439c94927a..80bf412974c 100644 --- a/docs/src/hal/parallel-port.adoc +++ b/docs/src/hal/parallel-port.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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. diff --git a/docs/src/hal/tools.adoc b/docs/src/hal/tools.adoc index bf1b4ff3db2..caba2550d1d 100644 --- a/docs/src/hal/tools.adoc +++ b/docs/src/hal/tools.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((HAL Tools))) diff --git a/docs/src/hal/twopass.adoc b/docs/src/hal/twopass.adoc index 1627a15277b..9c73c9e2a7b 100644 --- a/docs/src/hal/twopass.adoc +++ b/docs/src/hal/twopass.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == TWOPASS diff --git a/docs/src/ladder/classic-ladder.adoc b/docs/src/ladder/classic-ladder.adoc index 3501ab11739..a8818f70244 100644 --- a/docs/src/ladder/classic-ladder.adoc +++ b/docs/src/ladder/classic-ladder.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((ClassicLadder Programming,CL Programming))) diff --git a/docs/src/ladder/ladder-examples.adoc b/docs/src/ladder/ladder-examples.adoc index 2b752c74496..f8959f98f15 100644 --- a/docs/src/ladder/ladder-examples.adoc +++ b/docs/src/ladder/ladder-examples.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Wrapping Counter diff --git a/docs/src/lathe/lathe-user.adoc b/docs/src/lathe/lathe-user.adoc index 61fc08e515e..ab23a5eee32 100644 --- a/docs/src/lathe/lathe-user.adoc +++ b/docs/src/lathe/lathe-user.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Lathe User Information))) This chapter will provide information specific to lathes. diff --git a/docs/src/motion/5-axis-kinematics.adoc b/docs/src/motion/5-axis-kinematics.adoc index a30427e6682..37e3165d728 100644 --- a/docs/src/motion/5-axis-kinematics.adoc +++ b/docs/src/motion/5-axis-kinematics.adoc @@ -10,9 +10,9 @@ use image:: for equation png files -- no latexmath // 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} +:ini: ini +:hal: hal +:ngc: ngc (((5-Axis Kinematics))) diff --git a/docs/src/motion/external-offsets.adoc b/docs/src/motion/external-offsets.adoc index b304d4ebec0..4faac6e60a8 100644 --- a/docs/src/motion/external-offsets.adoc +++ b/docs/src/motion/external-offsets.adoc @@ -7,9 +7,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((externaloffsets))) diff --git a/docs/src/motion/switchkins.adoc b/docs/src/motion/switchkins.adoc index f92bf28a782..989e852a455 100644 --- a/docs/src/motion/switchkins.adoc +++ b/docs/src/motion/switchkins.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Introduction diff --git a/docs/src/plasma/plasma-cnc-primer.adoc b/docs/src/plasma/plasma-cnc-primer.adoc index 7c748ea8b5f..796f4041e07 100644 --- a/docs/src/plasma/plasma-cnc-primer.adoc +++ b/docs/src/plasma/plasma-cnc-primer.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((Plasma Cutting Primer))) diff --git a/docs/src/plasma/qtplasmac.adoc b/docs/src/plasma/qtplasmac.adoc index 29032b9c036..a82ef6b5e26 100644 --- a/docs/src/plasma/qtplasmac.adoc +++ b/docs/src/plasma/qtplasmac.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc == Preamble diff --git a/docs/src/remap/remap.adoc b/docs/src/remap/remap.adoc index c0e4972606b..e585a8c7200 100644 --- a/docs/src/remap/remap.adoc +++ b/docs/src/remap/remap.adoc @@ -4,9 +4,9 @@ [[cha:remap]] = Remap Extending G-code -:ini: {basebackend@docbook:'':ini} -:hal: {basebackend@docbook:'':hal} -:ngc: {basebackend@docbook:'':ngc} +:ini: ini +:hal: hal +:ngc: ngc == Introduction: Extending the RS274NGC Interpreter by Remapping Codes diff --git a/docs/src/source-highlight/hal-demo.adoc b/docs/src/source-highlight/hal-demo.adoc index f7975c103c0..a213dd77155 100644 --- a/docs/src/source-highlight/hal-demo.adoc +++ b/docs/src/source-highlight/hal-demo.adoc @@ -8,9 +8,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc // begin a listing of ini/hal/ngc files like so: //[source,{ini}] diff --git a/docs/src/source-highlight/ini-demo.adoc b/docs/src/source-highlight/ini-demo.adoc index ee5657716dc..cc1d3d4b0a8 100644 --- a/docs/src/source-highlight/ini-demo.adoc +++ b/docs/src/source-highlight/ini-demo.adoc @@ -10,9 +10,9 @@ Details of the filter can be found in `./doc/source-highlight-filter.txt`. // 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} +:ini: ini +:hal: hal +:ngc: ngc // Begin a listing of INI/HAL/ngc files like so: //[source,{ini}] diff --git a/docs/src/source-highlight/ngc-demo.adoc b/docs/src/source-highlight/ngc-demo.adoc index 21466d38e32..c3c6387ca11 100644 --- a/docs/src/source-highlight/ngc-demo.adoc +++ b/docs/src/source-highlight/ngc-demo.adoc @@ -8,9 +8,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc // Begin a listing of INI/HAL/NGC files like so: //[source,{ini}] diff --git a/docs/src/tooldatabase/tooldatabase.adoc b/docs/src/tooldatabase/tooldatabase.adoc index eb61b621187..de02ec86b22 100644 --- a/docs/src/tooldatabase/tooldatabase.adoc +++ b/docs/src/tooldatabase/tooldatabase.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: 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 <>. diff --git a/docs/src/user/user-concepts.adoc b/docs/src/user/user-concepts.adoc index 17388dc502a..570d0c3bcd5 100644 --- a/docs/src/user/user-concepts.adoc +++ b/docs/src/user/user-concepts.adoc @@ -6,9 +6,9 @@ // 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} +:ini: ini +:hal: hal +:ngc: ngc (((User Concepts))) This chapter covers important user concepts that should be understood before attempting to run a CNC machine with G-code. From b0a16fc0430aae677d6c3f8030e1c4c8ea3bf453 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 18:27:55 +0800 Subject: [PATCH 09/30] build: gate translated docs behind explicit configure flag, fix build-twice Bertho noted in the review of #4053 that: * a clean 'make pdfdocs' or 'make htmldocs' required a second pass to finish, because po4a generated the per-language .adoc files *during* the build but the make-time $(wildcard $(L)/*.adoc) expansion had already evaluated them as missing; * po4a should not run, and translation setup should not be invoked, on a developer build unless the developer asks for it. Address both: * configure.ac flips the default: BUILD_DOCS_TRANSLATED now requires an explicit '--enable-build-documentation-translation' (the old '--disable-build-documentation-translation' opt-out is replaced). Stale dblatex-era version probes and warnings around po4a are also removed; po4a >= 0.67 is required when the flag is on, missing or too-old po4a now errors instead of warning-and-disabling. * debian/rules.in keeps the .deb pipeline producing translations by always passing '--enable-build-documentation-translation' alongside the existing '--enable-build-documentation=pdf'. * docs/src/Submakefile: - Translated DOC_SRCS_ are now derived from the AsciiDoc_def lines in po4a.cfg instead of $(wildcard $(L)/*.adoc). The list is therefore correct on a fresh tree (po4a has not run yet) and no longer includes English-only sources like drivers/mesa_modbus.adoc that the translation pipeline does not touch. - DOC_SRCS and PDF_TARGETS only pull in the per-language lists when BUILD_DOCS_TRANSLATED=yes, so a default-configured build builds English only and never invokes po4a. - The orphaned 'xetex available?' check is dropped: prawn-svg in asciidoctor-pdf renders CJK from our TTF subset, xetex is no longer a build-time gate. - When BUILD_DOCS_TRANSLATED=yes, an empty-recipe pattern rule associates every translated .adoc with translateddocs as an order-only prerequisite, so 'make pdfdocs' (or 'make htmldocs') on a clean tree triggers po4a before depends/%.d evaluation, eliminating the two-pass requirement. --- debian/rules.in | 3 ++- docs/src/Submakefile | 47 ++++++++++++++++++++++++++++++++------------ src/configure.ac | 32 ++++++++---------------------- 3 files changed, 44 insertions(+), 38 deletions(-) diff --git a/debian/rules.in b/debian/rules.in index 9c0d295a12c..0e722a89e78 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 diff --git a/docs/src/Submakefile b/docs/src/Submakefile index e4f617548d8..0a8e05f2e5e 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -260,16 +260,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 := \ @@ -357,13 +369,9 @@ 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 - -# 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 += $(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) $(PDF_TARGETS_ZH_CN) endif info:: @@ -416,6 +424,19 @@ pdfdocs: svgs_made_from_dots $(PDF_TARGETS) htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en +# 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 + .htmldoc-stamp: copy_asciidoc_files gen_complist $(HTML_TARGETS) .images-stamp .include-stamp touch $@ diff --git a/src/configure.ac b/src/configure.ac index 93f8432b20a..fdf877b6f30 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1107,8 +1107,8 @@ 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 @@ -1124,35 +1124,19 @@ 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 AC_SUBST(BUILD_DOCS) From 5114925bf4c5b58b5fa48ed6b6c66654f40d540b Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:11:16 +0800 Subject: [PATCH 10/30] build: fix po4a fail by giving components_gen.adoc its own rule The build-twice fix in b0a16fc043 added an order-only rule so make knows how to produce per-language .adoc files (via translateddocs). That pulls documentation.pot into the dependency graph during -O manpages, and po4a then aborts because hal/components_gen.adoc does not exist yet; it was previously only generated as a side effect of gen_complist (an HTML stage with a heavy MAN_HTML_TARGETS dep). Add a minimal file rule for components_gen.adoc that depends only on manpages and gen_complist.py, and list it as a prerequisite of the .pot target. This keeps gen_complist (and its HTML-link validation) unchanged for the htmldocs path, but lets the .pot rule rebuild the generated source on its own. --- docs/src/Submakefile | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 0a8e05f2e5e..ad5aaf3305c 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -242,7 +242,18 @@ 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/), but it +# is auto-generated from the English manpages by gen_complist.py. The +# file therefore must exist before po4a is invoked, otherwise po4a aborts +# with "master file does not exist". The lighter rule below is enough +# for that: gen_complist.py reads from $(DOC_DIR)/man/, so it only needs +# manpages (the full gen_complist target also pulls in MAN_HTML_TARGETS +# for link validation, which is too heavy a dep for the .pot path). +$(DOC_SRCDIR)/hal/components_gen.adoc: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc 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 pofiles: $(DOC_DIR)/po/documentation.pot From 1c3e6d359112580320a7c264145931668389c1bf Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:11:25 +0800 Subject: [PATCH 11/30] docs: tighten Rouge HAL and NGC lexers per review Address Bertho's review feedback on the HAL / NGC rouge lexers: HAL: - INI substitutions and environment variables now use explicit [A-Za-z_]\w* ranges instead of an uppercase-looking pattern paired with the /i flag. - Integers and floats are split: floats need a decimal point or an exponent; integers are plain decimal. - Added recognition for hex (0x..), octal (0o..) and binary (0b..) literals, which halcmd accepts in setp / sets values. - Added `initf` to the command list to match the new halcmd verb introduced in the pending initf docs PR (will rebase whichever of the two PRs lands second). NGC: - Split axis letters (X Y Z A B C U V W) from parameter / call argument letters (I J K L P Q R D E). Axes keep Name::Attribute; parameters get Name::Decorator so the two read differently in the rendered output. - Integer literals no longer accept an exponent; an explicit float form `\d+[eE][+-]?\d+` is added. --- docs/src/extensions/rouge_hal.rb | 30 +++++++++++++++++++++--------- docs/src/extensions/rouge_ngc.rb | 18 ++++++++++++++---- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/src/extensions/rouge_hal.rb b/docs/src/extensions/rouge_hal.rb index 32b4bb79776..7b1a3c5693e 100644 --- a/docs/src/extensions/rouge_hal.rb +++ b/docs/src/extensions/rouge_hal.rb @@ -6,10 +6,11 @@ # Highlights: # - halcmd commands (loadrt, net, setp, addf, ...) # - pin / signal names of the form component.pin-name -# - INI substitutions of the form [SECTION]NAME +# - INI substitutions of the form [SECTION]NAME (any case) # - environment variables $VAR $(VAR) # - assignment operators = => <= -# - numbers and comments +# - numbers in decimal, hex (0x..), octal (0o..), and binary (0b..) +# - comments (# ...) # # Loaded via the asciidoctor -r flag from the docs Submakefile. @@ -33,6 +34,7 @@ class HAL < RegexLexer alias unalias list lock unlock status help echo + initf ].join('|').freeze state :root do @@ -45,19 +47,29 @@ class HAL < RegexLexer # Assignment operators rule %r/=>|<=|=/, Operator - # INI substitution: [SECTION]NAME - rule %r/\[[A-Z_][A-Z0-9_]*\][A-Z_][A-Z0-9_]*/i, Name::Constant + # 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/\[[A-Za-z_]\w*\][A-Za-z_]\w*/, Name::Constant - # Environment variables - rule %r/\$\([A-Z_][A-Z0-9_]*\)/i, Name::Variable - rule %r/\$[A-Z_][A-Z0-9_]*/i, Name::Variable + # 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 (signed, optional decimal, optional exponent) + # 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::Integer + 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 diff --git a/docs/src/extensions/rouge_ngc.rb b/docs/src/extensions/rouge_ngc.rb index 0ccbcc6a881..6bd04e560e9 100644 --- a/docs/src/extensions/rouge_ngc.rb +++ b/docs/src/extensions/rouge_ngc.rb @@ -7,7 +7,8 @@ # Highlights: # - line numbers N123 # - G / M / T / H / F / S codes -# - axis & argument letters X Y Z A B C U V W I J K P Q R L +# - 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 # # - O-word blocks with their keywords (sub, while, if, call, ...) # - math functions and boolean operators @@ -74,16 +75,25 @@ class NGC < RegexLexer # T H F S codes rule %r/(?i:[tfsh])-?\d+(?:\.\d+)?/, Keyword - # Axis letters and argument letters followed by a value or expression - rule %r/(?i:[xyzabcuvwijkpqrle])(?=\s*[-+\[\d#])/, Name::Attribute + # 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 + # 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 From 95f9d0cf07b888d57ca36c2ed6fddd2cfc05f23e Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:20:06 +0800 Subject: [PATCH 12/30] docs: render manual-pages PDF via asciidoctor-pdf Previously LinuxCNC_Manual_Pages.pdf was assembled by running groff on the troff files generated from each manpage's .adoc source, then piping through ps2pdf. That path lost syntax highlighting on code samples and was the last remnant of the troff toolchain in the docs build. Now the rule generates a small master document that includes every manpage in PDF_MAN_ORDER as a chapter (leveloffset=+1, with a hard page break between entries) and feeds it to asciidoctor-pdf. Code blocks pick up the rouge highlighting that the other PDFs already use; pagination is continuous as before. Component manpages whose .adoc is generated by halcompile (objects/man/) are looked up in parallel with the native ones in docs/src/man/. --- docs/src/Submakefile | 59 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 3 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index ad5aaf3305c..b1d3893d9de 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -482,10 +482,63 @@ 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 +# 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 @$(ECHO) Formatting manual pages as PDF - (cd $(DOC_DIR)/man; groff -t -rC1 -rD1 -Tps -man $(PDF_MAN_ORDER)) \ - | ps2pdf - $@ + @rm -f $@ $@.raw + $(Q)asciidoctor-pdf \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ + -a mansource=LinuxCNC \ + -a manmanual='LinuxCNC Documentation' \ + -a source-highlighter=rouge \ + -a "lversion=$(shell cat ../VERSION)" \ + -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ + -d book \ + -o $@.raw $< || (X=$$?; rm -f $@.raw; 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 $@ PDF_TARGETS_LinuxCNC_Getting_Started := $(DOC_DIR)/LinuxCNC_Getting_Started.pdf $(foreach L,$(LANGUAGES),$(DOC_DIR)/LinuxCNC_Getting_Started_$(L).pdf) From 0375f0adcafbe666eb5e6148650b7d4dd04b03bd Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:24:41 +0800 Subject: [PATCH 13/30] docs: drop legacy asciidoc-py source-lang attribute indirection Each .adoc that contained source blocks used to start with: // Custom lang highlight // must come after the doc title, to work around a bug in asciidoc 8.6.6 :ini: ini :hal: hal :ngc: ngc and then refer to those names as `[source,{ini}]` etc. The indirection only existed because asciidoc-py needed the docbook conditional `{basebackend@docbook:'':ini}` to pick a different value when emitting docbook; with asciidoctor the attribute is a plain constant alias. Drop the attribute block (along with the stale asciidoc 8.6.6 workaround comment) and rewrite the `{ini}`, `{hal}`, `{ngc}`, `{nml}`, `{css}` references back to the literal language name. --- docs/INSTALL.adoc | 1 - docs/help/asciidoc-markup_es.adoc | 2 - docs/help/tklinuxcnc.adoc | 10 +- docs/man/images/Images_info.adoc | 3 - docs/src/Master_Documentation.adoc | 2 - docs/src/code/building-linuxcnc.adoc | 1 - docs/src/code/code-notes.adoc | 6 - docs/src/code/contributing-to-linuxcnc.adoc | 6 - 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 | 18 +- docs/src/config/lathe-config.adoc | 12 +- docs/src/config/moveoff.adoc | 18 +- docs/src/config/python-hal-interface.adoc | 6 - docs/src/config/python-interface.adoc | 5 - docs/src/config/stepper-diagnostics.adoc | 8 +- docs/src/config/stepper.adoc | 18 +- docs/src/drivers/ax5214h.adoc | 8 +- docs/src/drivers/gm.adoc | 18 +- docs/src/drivers/gs2.adoc | 8 +- docs/src/drivers/hal_gpio.adoc | 2 - docs/src/drivers/hal_pi_gpio.adoc | 2 - docs/src/drivers/hostmot2.adoc | 17 +- docs/src/drivers/mb2hal.adoc | 10 +- docs/src/drivers/mesa_modbus.adoc | 2 - 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/shuttle.adoc | 1 - docs/src/drivers/vfs11.adoc | 10 +- docs/src/examples/gs2-example.adoc | 8 +- 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 | 18 +- docs/src/gcode/g-code.adoc | 188 ++++++++-------- docs/src/gcode/m-code.adoc | 30 ++- docs/src/gcode/machining-center.adoc | 12 +- docs/src/gcode/o-code.adoc | 47 ++-- docs/src/gcode/overview.adoc | 27 ++- docs/src/gcode/rs274ngc.adoc | 8 +- docs/src/gcode/tool-compensation.adoc | 9 +- .../getting-started/hardware-interface.adoc | 2 - .../getting-started/updating-linuxcnc.adoc | 8 - docs/src/gui/axis.adoc | 20 +- docs/src/gui/filter-programs.adoc | 12 +- docs/src/gui/gladevcp-libraries.adoc | 8 +- docs/src/gui/gladevcp-panels.adoc | 16 +- docs/src/gui/gladevcp.adoc | 21 +- docs/src/gui/gmoccapy.adoc | 69 +++--- docs/src/gui/gscreen.adoc | 10 +- 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 | 6 - docs/src/gui/ngcgui.adoc | 26 +-- docs/src/gui/panelui.adoc | 22 +- docs/src/gui/pyvcp-examples.adoc | 18 +- docs/src/gui/pyvcp.adoc | 26 +-- docs/src/gui/qtdragon.adoc | 126 ++++++----- docs/src/gui/qtvcp-code-snippets.adoc | 3 +- docs/src/gui/qtvcp-custom-widgets.adoc | 5 +- docs/src/gui/qtvcp-libraries.adoc | 14 +- docs/src/gui/qtvcp-vcp-panels.adoc | 50 ++--- docs/src/gui/qtvcp-vismach.adoc | 4 +- docs/src/gui/qtvcp-widgets.adoc | 115 +++++----- docs/src/gui/qtvcp.adoc | 25 +-- docs/src/gui/tklinuxcnc.adoc | 8 +- docs/src/gui/tooledit.adoc | 14 +- docs/src/gui/touchy.adoc | 8 +- docs/src/hal/basic-hal.adoc | 36 ++-- docs/src/hal/comp.adoc | 11 +- docs/src/hal/components.adoc | 2 - docs/src/hal/hal-examples.adoc | 20 +- docs/src/hal/halmodule.adoc | 1 - docs/src/hal/halshow.adoc | 18 +- docs/src/hal/haltcl.adoc | 22 +- docs/src/hal/halui-examples.adoc | 14 +- docs/src/hal/intro.adoc | 10 +- docs/src/hal/parallel-port.adoc | 22 +- docs/src/hal/tools.adoc | 12 +- docs/src/hal/tutorial.adoc | 1 - docs/src/hal/twopass.adoc | 24 +-- docs/src/install/latency-test.adoc | 2 - docs/src/ladder/classic-ladder.adoc | 24 +-- docs/src/ladder/ladder-examples.adoc | 14 +- docs/src/lathe/lathe-user.adoc | 10 +- docs/src/man/man1/emccalib.1.adoc | 1 - docs/src/man/man1/halstreamer.1.adoc | 2 - docs/src/man/man1/hy_gt_vfd.1.adoc | 2 - docs/src/man/man1/linuxcncrsh.1.adoc | 1 - docs/src/man/man1/mb2hal.1.adoc | 1 - docs/src/man/man1/melfagui.1.adoc | 1 - docs/src/man/man1/mesambccc.1.adoc | 2 - docs/src/man/man1/svd-ps_vfd.1.adoc | 1 - docs/src/man/man1/xhc-whb04b-6.1.adoc | 2 - docs/src/man/man3/hm2_pktuart.3.adoc | 1 - docs/src/man/man9/demux_generic.9.adoc | 1 - docs/src/man/man9/hm2_modbus.9.adoc | 1 - docs/src/man/man9/hm2_rpspi.9.adoc | 1 - docs/src/man/man9/hostmot2.9.adoc | 2 - docs/src/man/man9/kins.9.adoc | 2 - docs/src/man/man9/streamer.9.adoc | 2 - docs/src/motion/5-axis-kinematics.adoc | 16 +- docs/src/motion/external-offsets.adoc | 13 +- docs/src/motion/switchkins.adoc | 20 +- docs/src/plasma/plasma-cnc-primer.adoc | 22 +- docs/src/plasma/qtplasmac.adoc | 200 +++++++++--------- docs/src/remap/remap.adoc | 52 ++--- docs/src/source-highlight/hal-demo.adoc | 12 +- docs/src/source-highlight/ini-demo.adoc | 12 +- docs/src/source-highlight/ngc-demo.adoc | 12 +- docs/src/tooldatabase/tooldatabase.adoc | 9 +- docs/src/user/user-concepts.adoc | 8 +- 118 files changed, 736 insertions(+), 1316 deletions(-) diff --git a/docs/INSTALL.adoc b/docs/INSTALL.adoc index 578edbdc484..a4882640d3e 100644 --- a/docs/INSTALL.adoc +++ b/docs/INSTALL.adoc @@ -56,7 +56,6 @@ no `scripts/linuxcnc`, just a `scripts/linuxcnc.in`. By running `configure` will also replace some default values for your system (folders, paths, etc). - === Configure script The *`configure`* shell script attempts to guess correct values for diff --git a/docs/help/asciidoc-markup_es.adoc b/docs/help/asciidoc-markup_es.adoc index 68286887f62..c5f79cad6ba 100644 --- a/docs/help/asciidoc-markup_es.adoc +++ b/docs/help/asciidoc-markup_es.adoc @@ -55,7 +55,6 @@ https://linuxnc.org/someplace[descripcion del link] Uso: ocultar comentarios //// - = Bloque de listado para código G y salida por terminal <4 guiones comienzan un bloque + @@ -159,7 +158,6 @@ estilo de párrafo. Los estilos incluyen: NOTE TIP IMPORTANT WARNING CAUTION - = Tablas [options="header,width="80%"] diff --git a/docs/help/tklinuxcnc.adoc b/docs/help/tklinuxcnc.adoc index 13dba0d220e..a2187586acd 100644 --- a/docs/help/tklinuxcnc.adoc +++ b/docs/help/tklinuxcnc.adoc @@ -3,12 +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 *File -> Run...*:: @@ -157,7 +151,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 +160,7 @@ POSITION_FEEDBACK = ACTUAL or -[source,{ini}] +[source,ini] ---- [DISPLAY] POSITION_OFFSET = ABSOLUTE diff --git a/docs/man/images/Images_info.adoc b/docs/man/images/Images_info.adoc index 1359fdfd124..38ef1ce8c64 100644 --- a/docs/man/images/Images_info.adoc +++ b/docs/man/images/Images_info.adoc @@ -23,8 +23,6 @@ Here an example: ]} ---- - - .toggle2nist: ASCII art generated by asciiwave ---- ┐ ┏─────xxxxxxxxxxxx┐ ┏─────xxxxxxxxxxxx┐ @@ -44,7 +42,6 @@ is-on: └─────────────────┘ ---- - ## Diagrams ASCII art diagrams can be drawn e.g., with link:https://asciiflow.com/[asciiflow] diff --git a/docs/src/Master_Documentation.adoc b/docs/src/Master_Documentation.adoc index 9315491a307..d0d7c1ff70a 100644 --- a/docs/src/Master_Documentation.adoc +++ b/docs/src/Master_Documentation.adoc @@ -5,7 +5,6 @@ :revdate: 2021-10-28 = LinuxCNC V{lversion} - :leveloffset: 0 = Getting Started & Configuration @@ -25,7 +24,6 @@ include::getting-started/updating-linuxcnc.adoc[] include::common/linux-faq.adoc[] - :leveloffset: 1 = General User Information diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc index e14139853d6..1bfe6c792be 100644 --- a/docs/src/code/building-linuxcnc.adoc +++ b/docs/src/code/building-linuxcnc.adoc @@ -541,7 +541,6 @@ Virtual Environment, and set up the linuxcnc environment: (venv) ~ $ ~/src/linuxcnc $ scripts/linuxcnc ----- - == Options for checking out the git repo The <> instructions at the top of this diff --git a/docs/src/code/code-notes.adoc b/docs/src/code/code-notes.adoc index 46e5941b17f..2cdd130ca50 100644 --- a/docs/src/code/code-notes.adoc +++ b/docs/src/code/code-notes.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Intended audience This document is a collection of notes about the internals of LinuxCNC. It diff --git a/docs/src/code/contributing-to-linuxcnc.adoc b/docs/src/code/contributing-to-linuxcnc.adoc index d87f5556d5a..35dc0684185 100644 --- a/docs/src/code/contributing-to-linuxcnc.adoc +++ b/docs/src/code/contributing-to-linuxcnc.adoc @@ -3,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction This document contains information for developers about LinuxCNC diff --git a/docs/src/code/rs274.adoc b/docs/src/code/rs274.adoc index 128198b5da5..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: ini -:hal: hal -:ngc: 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 e780f19f68d..70e0aa309e4 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: ini -:hal: hal -:ngc: 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 2bb5bb3429b..e06497d266e 100644 --- a/docs/src/config/ini-config.adoc +++ b/docs/src/config/ini-config.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == The INI File Components(((INI File,Components))) A typical INI file follows a rather simple layout that includes; @@ -27,7 +21,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 +30,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 +40,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 +87,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 +98,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 +131,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,7 +196,7 @@ 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 @@ -213,7 +207,7 @@ 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 +218,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 +234,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 +250,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 +265,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 +492,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 +509,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 +519,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 +741,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 +800,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 ---- @@ -981,7 +975,6 @@ LinuxCNC will not know your joint travel limits when using `NO_FORCE_HOMING = 1` * `NO_PROBE_JOG_ERROR = 0` - Allow to bypass probe tripped check when you jog manually. * `NO_PROBE_HOME_ERROR = 0` - Allow to bypass probe tripped check when homing is in progress. - [[sub:ini:sec:kins]] === [KINS] Section(((INI File,Sections,KINS Section))) @@ -1025,7 +1018,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 ---- @@ -1036,7 +1029,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,ini] ---- axis..eoffset-enable axis..eoffset-count diff --git a/docs/src/config/ini-homing.adoc b/docs/src/config/ini-homing.adoc index 65fecdf9cbd..72d7752aa36 100644 --- a/docs/src/config/ini-homing.adoc +++ b/docs/src/config/ini-homing.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Overview Homing sets the zero origin of the G53 machine coordinates. @@ -274,7 +268,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 +277,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 +286,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 +295,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 +304,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 +354,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 d85019bc3d0..db493fa0822 100644 --- a/docs/src/config/lathe-config.adoc +++ b/docs/src/config/lathe-config.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Default Plane When LinuxCNC's interpreter was first written, it was designed for mills. @@ -17,7 +11,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,7 +30,7 @@ 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 @@ -64,7 +58,7 @@ COORDINATES = X 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 diff --git a/docs/src/config/moveoff.adoc b/docs/src/config/moveoff.adoc index 097ce3fa8ef..daf08fbd6bc 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: ini -:hal: hal -:ngc: 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,7 +121,7 @@ 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 @@ -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,7 +213,7 @@ 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 @@ -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 815932b744f..b9d09b0b963 100644 --- a/docs/src/config/python-hal-interface.adoc +++ b/docs/src/config/python-hal-interface.adoc @@ -4,17 +4,11 @@ [[cha:python-hal-interface]] = The HAL Python module -:ini: ini -:hal: hal -:ngc: ngc - This documentation describes the `hal` python module, which provides a Python API for creating and accessing HAL pins and signals. - == Basic usage - [source,python] ---- #!/usr/bin/env python3 diff --git a/docs/src/config/python-interface.adoc b/docs/src/config/python-interface.adoc index d74f3fbec59..4aacf2a71c1 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: ini -:hal: hal -:ngc: ngc - This documentation describes the `linuxcnc` python module, which provides a Python API for talking to LinuxCNC. @@ -406,7 +402,6 @@ print(s.toolinfo(toolno)) ': 0, 'xoffset': 0.0, 'yoffset': 0.0, 'zoffset': 0.18, 'aoffset': 0.0, 'boffset': 0.0, 'coffset': 0.0, 'uoffset': 0.0, 'voffset': 0.0, 'woffset': 0.0, 'comment': 'Tool_18 28Jan23:18.53.25'} ---- - *velocity*:: '(returns float)' - This property is defined, but it does not have a useful interpretation. diff --git a/docs/src/config/stepper-diagnostics.adoc b/docs/src/config/stepper-diagnostics.adoc index 598371878b6..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: ini -:hal: hal -:ngc: 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 1a2f2ad0813..b69a022b34a 100644 --- a/docs/src/config/stepper.adoc +++ b/docs/src/config/stepper.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction (((Stepper Configuration))) @@ -66,7 +60,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 +162,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 +170,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 +185,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 +194,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 +216,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 8cd58d02ecb..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: ini -:hal: hal -:ngc: 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 98cd8cbaf5b..0e5c6387a7c 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: ini -:hal: hal -:ngc: 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 ---- @@ -51,7 +45,6 @@ The following connectors can be found on the GM6-PCI card: .GM6-PCI card connectors and LEDs(((pci-card connectors))) image::images/GM_PCIpinout.png["GM6-PCI card connectors and LEDs",align="center",scaledwidth="70%"] - == I/O connectors .Pin numbering of GPIO connectors(((pin-numbering-gpio))) @@ -148,7 +141,6 @@ have to be connected as the following block diagram shows: .Servo axis interfaces(((axis-interface))) image::images/GM_AxisInterface.png["Servo axis interfaces",align="center",scaledwidth="100%"] - === Encoder The GM6-PCI motion control card has six encoder modules. @@ -229,7 +221,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 +232,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 +302,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 +319,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 41a0830d27c..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: ini -:hal: hal -:ngc: 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/hal_gpio.adoc b/docs/src/drivers/hal_gpio.adoc index 374802f36fc..7c0b900a030 100644 --- a/docs/src/drivers/hal_gpio.adoc +++ b/docs/src/drivers/hal_gpio.adoc @@ -82,12 +82,10 @@ The version of libgpiod-dev installed can be determined by the command `gpioinfo * hal_gpio.NAME-in-not - HAL_OUT An inverted version of the above, for convenience * hal_gpio.NAME-out - HAL_IN use this pin to transfer a HAL bit value to a physical output - == Parameters * hal_gpio.reset_ns - HAL_RW - "setp" this parameter to control the pulse length of pins added to the "reset" list. The value will be limited between 0 and thread-period / 4. - == Functions * 'hal_gpio.read' - Add this to the base thread to update the HAL pin values to match the physical input values. diff --git a/docs/src/drivers/hal_pi_gpio.adoc b/docs/src/drivers/hal_pi_gpio.adoc index 4ee08571f4f..7a64ffc8d1a 100644 --- a/docs/src/drivers/hal_pi_gpio.adoc +++ b/docs/src/drivers/hal_pi_gpio.adoc @@ -81,7 +81,6 @@ For unknown reasons the driver also creates HAL _pins_ to indicate timing: * hal_pi_gpio.read.time * hal_pi_gpio.write.time - == Functions * `hal_pi_gpio.read` - Add this to the base thread to update the HAL pin values to match the physical input values. @@ -89,7 +88,6 @@ For unknown reasons the driver also creates HAL _pins_ to indicate timing: Typically the 'read' function will be early in the call list, before any encoder counters and the 'write' function will be later in the call list, after stepgen.make-pulses. - == Pin Numbering The GPIO connector and the pinout has been consistent since around 2015. diff --git a/docs/src/drivers/hostmot2.adoc b/docs/src/drivers/hostmot2.adoc index 9603c1eea4d..c0b750740cd 100644 --- a/docs/src/drivers/hostmot2.adoc +++ b/docs/src/drivers/hostmot2.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction HostMot2 is an FPGA configuration developed by Mesa Electronics for @@ -66,7 +60,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 +72,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 +174,7 @@ your configuration. An example of a 5I20 configuration: -[source,{ini}] +[source,ini] ---- [HOSTMOT2] DRIVER=hm2_pci @@ -349,7 +343,6 @@ So far, all firmware is available in all gate sizes.) |SVST8_8IM2 | 8 (+IM) | 8 | 8 | 0 |=== - 4I65 (3-port PC/104) Default Configurations (The 4I65 has 200k gates.) [width="90%",options="header"] @@ -718,7 +711,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 +721,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 a63e1aebda5..b63aa96bb81 100644 --- a/docs/src/drivers/mb2hal.adoc +++ b/docs/src/drivers/mb2hal.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction MB2HAL is a generic non-realtime HAL component to communicate with one or more Modbus devices. @@ -42,7 +36,6 @@ Set `HAL_MODULE_NAME=mymodule` (default `HAL_MODULE_NAME=mb2hal`) .. Default component name: `loadusr -W mb2hal config=config_file.ini` .. Custom component name: `loadusr -Wn mymodule mb2hal config=config_file.ini` - == Options === Init Section @@ -67,7 +60,6 @@ It affects ALL transactions. Use "0.0" for normal activity. m|TOTAL_TRANSACTIONS | Integer | Yes | The number of total Modbus transactions. There is no maximum. |=== - === Transaction Sections One transaction section is required per transaction, starting at `[TRANSACTION_00]` and counting up sequentially. @@ -150,7 +142,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/mesa_modbus.adoc b/docs/src/drivers/mesa_modbus.adoc index 10073ccaa3e..9a8747538a7 100644 --- a/docs/src/drivers/mesa_modbus.adoc +++ b/docs/src/drivers/mesa_modbus.adoc @@ -122,7 +122,6 @@ multiplied by the "scale" pin value and presented as a floating point value on a HAL pin with the suffix "scaled". For example mymodule.0.counts-0-scaled. - In addition to the pins configured in the definition file, each module will create the following pins for each instance of the driver: @@ -178,7 +177,6 @@ All modules created by the framework require a hostmot2 pktuart instance to be given to the "ports" modparam on the "loadrt" file. See the example in the [Quick Start] section. - == Configuration File == A Mesa_Modbus configuration file is actually a C header file and must diff --git a/docs/src/drivers/mitsub-vfd.adoc b/docs/src/drivers/mitsub-vfd.adoc index 85fccb44521..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: ini -:hal: hal -:ngc: ngc - -:hal: 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 87c3c56b03d..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: ini -:hal: hal -:ngc: 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 67385e9387f..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: ini -:hal: hal -:ngc: 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 958d004c1bf..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: ini -:hal: hal -:ngc: 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 d1365bb754a..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: ini -:hal: hal -:ngc: 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 9e02b24e87b..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: ini -:hal: hal -:ngc: 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/shuttle.adoc b/docs/src/drivers/shuttle.adoc index 138cae8f524..ec47c111211 100644 --- a/docs/src/drivers/shuttle.adoc +++ b/docs/src/drivers/shuttle.adoc @@ -33,7 +33,6 @@ Any user interaction with the Shuttle device will generate an event, informing t So if you (for example) push one of the buttons at startup, the jog-wheel will work fine and notice the first click. ==== - == Setup The shuttle driver needs read permission to the /dev/hidraw* diff --git a/docs/src/drivers/vfs11.adoc b/docs/src/drivers/vfs11.adoc index 03f076869fc..2ae383dd72b 100644 --- a/docs/src/drivers/vfs11.adoc +++ b/docs/src/drivers/vfs11.adoc @@ -4,10 +4,6 @@ [[cha:vfs11-vfd]] = VFS11 VFD Driver -:ini: ini -:hal: hal -:ngc: 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,7 +138,7 @@ 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 @@ -208,7 +204,7 @@ POLLCYCLES=10 == HAL example -[source,{hal}] +[source,hal] --------------------------------------------------------------------- # # example usage of the VF-S11 VFD driver diff --git a/docs/src/examples/gs2-example.adoc b/docs/src/examples/gs2-example.adoc index cefba36369a..81af5712e25 100644 --- a/docs/src/examples/gs2-example.adoc +++ b/docs/src/examples/gs2-example.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Example This example shows the connections needed to use an Automation Direct GS2 VFD to drive a spindle. @@ -21,7 +15,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 34ea842af52..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: ini -:hal: hal -:ngc: 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 6d555f7c8a2..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: ini -:hal: hal -:ngc: 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 dba1bd14876..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: ini -:hal: hal -:ngc: 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 eed687fc179..a150bcd3aa9 100644 --- a/docs/src/gcode/coordinates.adoc +++ b/docs/src/gcode/coordinates.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction (((Coordinate Systems))) @@ -44,7 +38,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 +119,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 +143,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 +400,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 +413,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 +423,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 7f2be1e2712..f3c57974e41 100644 --- a/docs/src/gcode/g-code.adoc +++ b/docs/src/gcode/g-code.adoc @@ -4,10 +4,6 @@ [[cha:g-codes]] = G-Codes -:ini: ini -:hal: hal -:ngc: ngc - == Conventions Conventions used in this section @@ -121,7 +117,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 +137,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,7 +173,7 @@ It is an error if: [[gcode:g1]] == G1 Linear Move(((G1 Linear Move))) -[source,{ngc}] +[source,ngc] ------------------- G1 axes ------------------- @@ -189,7 +185,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 +213,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 +318,7 @@ For more information on 'Absolute Arc Distance Mode see the <> section. .XY-plane (G17) -[source,{ngc}] +[source,ngc] ---- G2 or G3 ---- @@ -333,7 +329,7 @@ G2 or G3 * 'P' - number of turns .XZ-plane (G18) -[source,{ngc}] +[source,ngc] ---- G2 or G3 ---- @@ -344,7 +340,7 @@ G2 or G3 * 'P' - number of turns .YZ-plane (G19) -[source,{ngc}] +[source,ngc] ---- G2 or G3 ---- @@ -388,7 +384,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 +400,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 +414,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 +424,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 +458,7 @@ It is an error if: === Radius Format Arcs -[source,{ngc}] +[source,ngc] ---- G2 or G3 axes R- ---- @@ -497,7 +493,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 +507,7 @@ otherwise it is a helical arc. [[gcode:g4]] == G4 Dwell(((G4 Dwell))) -[source,{ngc}] +[source,ngc] ---- G4 P- ---- @@ -524,7 +520,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 +532,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 +555,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 +566,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 +582,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 +598,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 +614,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 +637,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 +665,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 +678,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 +691,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 +710,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 +728,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 +747,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 +810,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 +821,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 +835,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 +854,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 +875,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 +911,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 +923,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 +987,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 +1026,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 +1038,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 +1091,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 +1115,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 +1159,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 +1181,7 @@ It is an error if: [[gcode:g38]] == G38._n_ Straight Probe(((G38.n Probe))) -[source,{ngc}] +[source,ngc] ---- G38.n axes ---- @@ -1258,7 +1254,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 +1291,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 +1310,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 +1365,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 +1388,7 @@ It is an error if: [[gcode:g43]] == G43 Tool Length Offset(((G43 Tool Length Offset))) -[source,{ngc}] +[source,ngc] ---- G43 ---- @@ -1423,7 +1419,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 +1435,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 +1445,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 +1465,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 +1477,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 +1487,7 @@ M2 (end program) ---- .G43.2 axes Example -[source,{ngc}] +[source,ngc] ---- G90 (set absolute mode) T1 M6 (load tool 1) @@ -1528,7 +1524,7 @@ used. [[gcode:g52]] == G52 Local Coordinate System Offset(((Local Offsets))) -[source,{ngc}] +[source,ngc] ---- G52 axes ---- @@ -1539,7 +1535,7 @@ For more information about `G92` and `G52` and how they interact see <> ---- @@ -1657,7 +1653,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 +1661,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 +1670,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 +1681,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 +1692,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 +1740,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 +1805,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 +1837,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 +1873,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,7 +1977,7 @@ 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 @@ -2122,7 +2118,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 +2143,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 +2176,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 +2187,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 +2204,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 +2237,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 +2257,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 +2284,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 +2326,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 +2345,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 +2359,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 +2373,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 +2392,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 +2403,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 +2435,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 +2472,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 +2491,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 +2527,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 +2553,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 +2580,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 +2689,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 +2714,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 +2742,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 a3e3956a8c8..bdbd026647d 100644 --- a/docs/src/gcode/m-code.adoc +++ b/docs/src/gcode/m-code.adoc @@ -4,10 +4,6 @@ [[cha:m-codes]] = M-Codes -:ini: ini -:hal: hal -:ngc: ngc - == M-Code Quick Reference Table [width="60%",options="header",cols="2^,5<"] @@ -111,7 +107,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 @@ -122,14 +118,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 ---- @@ -214,7 +210,7 @@ state. (((M19 Orient Spindle))) -[source,{ngc}] +[source,ngc] ---- M19 R- Q- [P-] [$-] ---- @@ -388,7 +384,7 @@ connected in your HAL file to outputs. == M66 Wait on Input (((M66 Wait on Input))) -[source,{ngc}] +[source,ngc] ---- M66 P- | E- ---- @@ -410,7 +406,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) ---- @@ -440,7 +436,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- ---- @@ -467,7 +463,7 @@ connected in your HAL file to outputs. == M68 Analog Output, Immediate (((M68 Analog Output))) -[source,{ngc}] +[source,ngc] ---- M68 E- Q- ---- @@ -576,7 +572,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>) @@ -629,7 +625,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>) @@ -680,7 +676,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) ; @@ -703,7 +699,7 @@ O endsub == M100-M199 User Defined Commands (((M100-M199 User Defined Commands))) -[source,{ngc}] +[source,ngc] ---- M1-- ---- @@ -768,7 +764,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 0e8b890b268..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: ini -:hal: hal -:ngc: 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 720e8e7a878..b417b3f77ae 100644 --- a/docs/src/gcode/o-code.adoc +++ b/docs/src/gcode/o-code.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Use of O-codes O-codes provide for flow control in NC programs. @@ -41,7 +35,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 +51,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) @@ -89,7 +83,6 @@ The behavior is undefined if: * Other words are used on a line with an o-word. * Comments are used on a line with an o-word. - [[ocode:subroutines]] == Subroutines(((Subroutines))) @@ -98,7 +91,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 +109,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 +135,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 +156,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 +170,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 +205,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 +266,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 +305,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 +320,7 @@ M2 (end program) ---- .Do While Example -[source,{ngc}] +[source,ngc] ---- #1 = 0 (assign parameter #1 the value of 0) o100 do @@ -367,7 +360,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 +369,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 +387,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 +410,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 +427,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 +454,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 +469,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 +489,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 8a53deb17d1..6eb8cb029b6 100644 --- a/docs/src/gcode/overview.adoc +++ b/docs/src/gcode/overview.adoc @@ -5,13 +5,10 @@ [[cha:overview-of-g-code-programming]] = Overview of G-Code Programming -:ini: ini -:hal: hal -:ngc: ngc // begin a listing of INI/HAL/NGC files like so: -//[source,{ini}] -//[source,{hal}] -//[source,{ngc}] +//[source,ini] +//[source,hal] +//[source,ngc] == Overview @@ -620,7 +617,7 @@ 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 @@ -633,7 +630,7 @@ 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>) @@ -659,7 +656,7 @@ contain lowercase characters can not be accessed from G-code. Example: -[source,{ngc}] +[source,ngc] --------------------------------------------------------------------- (debug, #<_hal[motion-controller.time]>) --------------------------------------------------------------------- @@ -669,7 +666,7 @@ 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]>) @@ -786,7 +783,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>]] @@ -892,7 +889,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 @@ -912,7 +909,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 @@ -1023,7 +1020,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) @@ -1249,7 +1246,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 452a189ae40..e179ab4aef7 100644 --- a/docs/src/gcode/rs274ngc.adoc +++ b/docs/src/gcode/rs274ngc.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Changes from RS274/NGC .Differences that change the meaning of RS274/NGC programs @@ -52,7 +46,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 9c6ea9d7242..3efb1a14b9a 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: ini -:hal: hal -:ngc: ngc - (((Tool Compensation))) [[sec:touch-off]] @@ -213,7 +207,7 @@ Information about configuring a LinuxCNC tool changer is in the <>. .Example of User Message Configuration -[source,{ini}] +[source,ini] ---- MESSAGE_TEXT = This is a info-message test MESSAGE_TYPE = status @@ -432,7 +423,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 @@ -465,7 +456,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 +467,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 +483,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 +498,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 +522,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 +766,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 +835,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 +850,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 +896,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 +922,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 +985,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 +1001,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 +1014,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 +1025,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 +1053,7 @@ to the directory specified as `SUBROUTINE_PATH`, see < G38.2 Z-4 @@ -1074,7 +1065,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,14 +1073,14 @@ 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 @@ -1706,7 +1697,7 @@ Change that entry to MAX_VELOCITY = xxx. If you use a macro without movement, like this one: -[source,{ngc}] +[source,ngc] --------- o sub @@ -1725,7 +1716,7 @@ 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 diff --git a/docs/src/gui/gscreen.adoc b/docs/src/gui/gscreen.adoc index 3b9765755cd..a3be66e08a4 100644 --- a/docs/src/gui/gscreen.adoc +++ b/docs/src/gui/gscreen.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction Gscreen is an infrastructure to display a custom screen to control LinuxCNC. @@ -410,7 +404,7 @@ interact with it. Under the [DISPLAY] heading: -[source,{ini}] +[source,ini] ---- DISPLAY = gscreen -c tester options: @@ -449,7 +443,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 5cc5cd9a177..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: ini -:hal: hal -:ngc: ngc -:css: 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 dfce0356fa0..f6c5f808871 100644 --- a/docs/src/gui/halui.adoc +++ b/docs/src/gui/halui.adoc @@ -5,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction Halui is a HAL based user interface for LinuxCNC, it connects HAL pins to @@ -20,7 +14,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 +23,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,7 +35,7 @@ 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 @@ -57,12 +51,11 @@ to a maximum of 64 commands. These pins can be connected like any HAL pins. A common method is to use buttons provided by virtual control panels like shown in the example <>. - [[code:Example-HAL-file-connections]] .Example for MDI_COMMAND connections ==== .HAL file -[source,{hal}] +[source,hal] ---- net quill-up halui.mdi-command-00 <= pyvcp.quillup net reference-pos halui.mdi-command-01 <= pyvcp.referencepos diff --git a/docs/src/gui/image-to-gcode.adoc b/docs/src/gui/image-to-gcode.adoc index 877987d94a4..607252b2b7c 100644 --- a/docs/src/gui/image-to-gcode.adoc +++ b/docs/src/gui/image-to-gcode.adoc @@ -4,12 +4,6 @@ [[cha:image-to-g-code]] = Image to G-Code -// Custom lang highlight -// must come after the doc title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - image::images/image-to-gcode.png["Image to G-Code",align="center"] == What is a depth map? @@ -23,7 +17,7 @@ Add the following lines to the '[FILTER]' section of your INI file to make AXIS automatically invoke image-to-gcode when you open a PNG, GIF, or JPEG image: -[source,{ini}] +[source,ini] ---- PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image png = image-to-gcode diff --git a/docs/src/gui/mdro.adoc b/docs/src/gui/mdro.adoc index 6d9bb6c5bde..7864ea1f13d 100644 --- a/docs/src/gui/mdro.adoc +++ b/docs/src/gui/mdro.adoc @@ -4,12 +4,6 @@ [[cha:mdro-gui]] = MDRO GUI -// Custom lang highlight -// must come after the doc title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - == Introduction (((mdro GUI))) diff --git a/docs/src/gui/ngcgui.adoc b/docs/src/gui/ngcgui.adoc index 23e4a23ff3e..00707c126aa 100644 --- a/docs/src/gui/ngcgui.adoc +++ b/docs/src/gui/ngcgui.adoc @@ -4,12 +4,6 @@ [[cha:ngcgui]] = NGCGUI -// Custom lang highlight -// must come after the doc title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - .NGCGUI embedded into AXIS image::images/ngcgui.png[align="center"] @@ -167,7 +161,7 @@ for NGCGUI use symbolic links to non-user-writable LinuxCNC libraries for: These libraries are located by INI file items that specify the search paths used by LinuxCNC (and NGCGUI): -[source,{ini}] +[source,ini] ---- [RS274NGC] SUBROUTINE_PATH = ../../nc_files/ngcgui_lib:../../nc_files/gcmc_lib:../../nc_files/ngcgui_lib/utilitysubs @@ -202,7 +196,7 @@ For instance, a user might create a NGCGUI-compatible subfile named: To use files in new directories, the INI file must be edited to include the new subfiles and to augment the search path(s). For this example: -[source,{ini}] +[source,ini] ---- [RS274NGC] ... @@ -404,7 +398,7 @@ the directory containing the LinuxCNC INI file. Additional directories can be prepended to the gcmc search order with the GCMC_INCLUDE_PATH item. .Sample AXIS-GUI-based INI -[source,{ini}] +[source,ini] ---- [RS274NGC] ... @@ -484,14 +478,14 @@ Note: Optional, specifies filename for preamble used for ttt created subfiles NGCGUI uses the LinuxCNC search path to find files. The search path begins with the standard directory specified by: -[source,{ini}] +[source,ini] ---- [DISPLAY]PROGRAM_PREFIX = directory_name ---- followed by multiple directories specified by: -[source,{ini}] +[source,ini] ---- [RS274NGC]SUBROUTINE_PATH = directory1_name:directory1_name:directory3_name ... ---- @@ -525,7 +519,7 @@ Multiple directories can be specified with [RS274NGC]SUBROUTINE_PATH by separati The following example illustrates the format for multiple directories and shows the use of relative and absolute paths. .Multiple Directories Example: -[source,{ini}] +[source,ini] ---- [RS274NGC]SUBROUTINE_PATH = ../../nc_files/ngcgui_lib:../../nc_files/ngcgui_lib/utilitysubs:/tmp/tmpngc ---- @@ -544,7 +538,7 @@ You can use this directory but it is better practice to create dedicated directo In the following example, files in /home/myname/linuxcnc/mysubs will be found before files in ../../nc_files/ngcgui_lib. .Adding User Directory Example: -[source,{ini}] +[source,ini] ---- [RS274NGC]SUBROUTINE_PATH = /home/myname/linuxcnc/mysubs:../../nc_files/ngcgui_lib:../../nc_files/ngcgui_lib/utilitysubs` ---- @@ -758,7 +752,7 @@ Its value begins with a value of 0 and is incremented for each added feature. A special 'info' comment can be included anywhere in an NGCGUI-compatible subfile. The format is: -[source,{ngc}] +[source,ngc] ---- (info: info_text) ---- @@ -767,7 +761,7 @@ The info_text is displayed near the top of the NGCGUI tab page in AXIS. Files not intended for use as subfiles can include a special comment so that NGCGUI will reject them automatically with a relevant message. -[source,{ngc}] +[source,ngc] ---- (not_a_subfile) ---- @@ -873,7 +867,7 @@ include("ensure_mode.gcmc") and provide a proper path for gcmc include_files in the INI file, for example: -[source,{ini}] +[source,ini] ---- [DISPLAY] GCMC_INCLUDE_PATH = ../../nc_files/gcmc_lib diff --git a/docs/src/gui/panelui.adoc b/docs/src/gui/panelui.adoc index 9c4e158da6e..4a19a5e5527 100644 --- a/docs/src/gui/panelui.adoc +++ b/docs/src/gui/panelui.adoc @@ -4,10 +4,6 @@ [[cha:Panelui]] = Panelui -:ini: ini -:hal: hal -:ngc: ngc - == Introduction (((Panelui))) @@ -24,7 +20,7 @@ While actual input buttons are required to be momentary, Panelui will use this i The command used to load panelui (with optional -d debug switch): -[source,{hal}] +[source,hal] ---- loadusr -W panelui -d ---- @@ -34,7 +30,7 @@ the config folder or user folder. One can validate the INI file with this command: -[source,{hal}] +[source,hal] ---- loadusr pyui ---- @@ -44,7 +40,7 @@ It will print errors to the terminal if found. A typical HAL file will have these commands added: -[source,{hal}] +[source,hal] ---- # commands needed for panelui loading # @@ -93,7 +89,7 @@ addf sampler.0 servo-thread * FALSE_FUNCTION= sets the ZMQ message function and arguments to be called when the button is FALSE. .*HAL Prefix* -[source,{ini}] +[source,ini] ---- [HAL_PREFIX] NAME= Yourname @@ -102,7 +98,7 @@ addf sampler.0 servo-thread This allows one to change the prefix of the HAL pins from 'panelui' to an arbitrary name. .*ZMQ Messaging Setup* -[source,{ini}] +[source,ini] ---- [ZMQ_SETUP] TOPIC = 'QTVCP' @@ -118,7 +114,7 @@ Radiobutons allow only one button in the group to be active at a time. Each group has its own output pin, separate from each button in the group. Radio button definitions start with the text 'RADIO_BUTTON' inside single brackets. -[source,{ini}] +[source,ini] ---- [RADIO_BUTTONS] # The double bracket section(s) define the group(s) of radio buttons. @@ -173,7 +169,7 @@ Radio button definitions start with the text 'RADIO_BUTTON' inside single bracke Togglebuttons only change state on each press of the button. Toggle button definitions start with the text 'TOGGLE_BUTTON' inside single brackets. -[source,{ini}] +[source,ini] ---- [TOGGLE_BUTTONS] # Each button name inside double brackets, must be unique and is case sensitive. @@ -198,7 +194,7 @@ Toggle button definitions start with the text 'TOGGLE_BUTTON' inside single brac Momentary buttons are true when pressed and false when released. Momentary button definitions start with the text 'MOMENTARY_BUTTON' inside single brackets. -[source,{ini}] +[source,ini] ---- [MOMENTARY_BUTTONS] # Each button name inside double brackets, must be unique and is case sensitive. @@ -348,7 +344,7 @@ There are a number of internal commands you may use. Panelui can send ZMQ based messages on button presses. + In this way panelui can interact will other programs such as QtVCP screens. + -[source,{ini}] +[source,ini] ---- [TOGGLE_BUTTONS] [[zmq_test]] diff --git a/docs/src/gui/pyvcp-examples.adoc b/docs/src/gui/pyvcp-examples.adoc index 61451ab32e9..c3da3925bcd 100644 --- a/docs/src/gui/pyvcp-examples.adoc +++ b/docs/src/gui/pyvcp-examples.adoc @@ -3,12 +3,6 @@ = PyVCP Examples -// Custom lang highlight -// must come after the doc title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - == AXIS To create a PyVCP panel to use with the AXIS interface that is @@ -174,7 +168,7 @@ image::images/xyz_buttons.png["Jog Buttons Image"] To make the connections needed open up your custom_postgui.hal file and add the following. -[source,{hal}] +[source,hal] ---- # connect the X PyVCP buttons net my-jogxminus halui.axis.x.minus <= pyvcp.x-minus @@ -446,7 +440,7 @@ image::images/gs2_panel.png["GS2 Panel"] To make it work we add the following code to the custom_postgui.hal file. -[source,{hal}] +[source,hal] ---- # display the rpm based on freq * rpm per hz loadrt mult2 @@ -494,7 +488,7 @@ In your configuration directory create the XML file. In this example it's named Open your INI file with a text editor and in the [DISPLAY] section add the following line. This is what loads the PyVCP panel. -[source,{ini}] +[source,ini] ---- PYVCP = rth.xml ---- @@ -502,7 +496,7 @@ PYVCP = rth.xml If you don't have a [HALUI] section in the INI file create it and add the following MDI command. -[source,{ini}] +[source,ini] ---- MDI_COMMAND = G53 G0 X0 Y0 Z0 ---- @@ -515,7 +509,7 @@ Information about <> 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 +517,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 a4f2733cbae..13a51d93817 100644 --- a/docs/src/gui/pyvcp.adoc +++ b/docs/src/gui/pyvcp.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction PyVCP, **Py**thon **V**irtual **C**ontrol **P**anel, is designed to give the @@ -66,7 +60,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 +86,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 +119,7 @@ and set the maximum value of the bar to 5000 (see < pyvcp.spindle-speed ---- @@ -171,7 +165,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 +195,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 +222,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 fa51ccb0ce9..b8ca2a25852 100644 --- a/docs/src/gui/qtdragon.adoc +++ b/docs/src/gui/qtdragon.adoc @@ -5,10 +5,6 @@ [[cha:qtdragon-gui]] = QtDragon GUI -:ini: ini -:hal: hal -:ngc: ngc - == Introduction (((QtDragon))) @@ -75,7 +71,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 +85,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 +97,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 +109,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 +121,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 +136,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 +150,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 +160,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 +179,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 +191,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 +228,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 +241,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 +256,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 +267,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 +298,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 +316,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 +337,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 +350,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 +360,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 +385,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 +407,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 @@ -426,7 +422,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 @@ -440,7 +436,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 @@ -464,7 +460,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 @@ -543,7 +539,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 @@ -552,14 +548,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 ---- @@ -568,7 +564,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 @@ -580,7 +576,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 ---- @@ -590,28 +586,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 @@ -623,7 +619,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 @@ -631,7 +627,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 @@ -642,7 +638,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 @@ -655,7 +651,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 ---- @@ -664,20 +660,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 @@ -696,7 +692,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 @@ -735,7 +731,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 @@ -745,7 +741,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 @@ -811,7 +807,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 ######################################################################## @@ -985,7 +981,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 ---- @@ -1032,7 +1028,6 @@ In the lib folder copy 'touchoff_subprogram.py' + If these files are found they will be used instead of the originals. + You can modify the files to change behaviour. + - [[sub:touch-plate]] == Touch plate @@ -1240,7 +1235,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 @@ -1256,7 +1251,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] @@ -1298,7 +1293,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 @@ -1315,7 +1310,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 @@ -1329,7 +1324,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 @@ -1342,7 +1337,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 <= ---- @@ -1620,7 +1615,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 { @@ -1632,7 +1627,7 @@ StatusLabel#status_rpm { To change the DRO display font and display format: -[source,{ini}] +[source,ini] ---- DROLabel { font: 25pt "Lato Heavy"; @@ -1652,7 +1647,7 @@ DROLabel { Change the axis select button's click menu items: -[source,{ini}] +[source,ini] ---- AxisToolButton { /* Adjust all the menu options */ @@ -1667,7 +1662,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"; @@ -1677,7 +1672,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"; @@ -1695,7 +1690,7 @@ OriginOffsetView { To stop the blur effect with dialogs: -[source,{ini}] +[source,ini] ---- #screen_options { qproperty-focusBlur_option: false; @@ -1703,7 +1698,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 */ @@ -1716,7 +1711,7 @@ To change status highlight/selection colors: Change the G-code text display colors/fonts: -[source,{ini}] +[source,ini] ---- EditorBase{ background:black; @@ -1745,7 +1740,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; @@ -1755,7 +1750,6 @@ To have the manual spindle buttons also incrementally increase/decrease speed: } ---- - === Qt Designer and Python code All aspects of the GUI are fully customization through Qt Designer and/or Python code. + diff --git a/docs/src/gui/qtvcp-code-snippets.adoc b/docs/src/gui/qtvcp-code-snippets.adoc index 38bf68a9b40..773682c78b9 100644 --- a/docs/src/gui/qtvcp-code-snippets.adoc +++ b/docs/src/gui/qtvcp-code-snippets.adoc @@ -946,7 +946,6 @@ The users can recall any recorded messages. There are several options: - *`STATUS.TEMPORARY_MESSAGE`*:: Show the message for a short time only. *`STATUS.OPERATOR_ERROR`*:: *`STATUS.OPERATOR_TEXT`*:: @@ -1065,7 +1064,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..218ad42e484 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"; @@ -837,7 +837,6 @@ class ActionButtonPlugin(QPyDesignerCustomWidgetPlugin): def includeFile(self): return "qtvcp.widgets.action_button" - class ActionButtonDialog(QtWidgets.QDialog): def __init__(self, widget, parent = None): diff --git a/docs/src/gui/qtvcp-libraries.adoc b/docs/src/gui/qtvcp-libraries.adoc index bd9d238f203..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: ini -:hal: hal -:ngc: 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 58205e72d8e..e79fcdb665d 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: ini -:hal: hal -:ngc: 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 ---- @@ -296,7 +290,6 @@ Options: .QtVCP `tool_dialog` - Manual Tool Change Dialog image::images/qtvcp_toolChange.png["QtVCP tool_dialog - Manual Tool Change Dialog",align="center"] - [[sub:qtvcp:panels:vismach]] == `vismach` 3D Simulation Panels These panels are prebuilt simulation of common machine types. @@ -307,7 +300,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 +314,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 +326,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 +338,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 +350,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 +362,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 ---- @@ -377,7 +370,6 @@ loadusr qtvcp vismach_fanuc_200f .QtVCP `vismach_fanuc_200f` - 6 Joint Robotic Arm image::images/qtvismach_fanuc_200f.png["QtVCP vismach_fanuc_200f - 6 Joint Robotic Arm",align="left"] - [[sec:qtvcp:panels:custom]] == Custom Virtual Control Panels @@ -391,7 +383,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 +418,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 +451,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 +460,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..34fceb35eea 100644 --- a/docs/src/gui/qtvcp-vismach.adoc +++ b/docs/src/gui/qtvcp-vismach.adoc @@ -99,7 +99,6 @@ The same is applicable for any design of machine: look at the machine arm example and you will see that it starts with the tip and adds to the larger part of the arm, then it finally groups with the base. - [[sec:qtvcp:vismach:start]] == Start the script @@ -253,7 +252,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" ---- @@ -525,7 +524,6 @@ Usually this file is imported by QtVCP and the `window()` object is instantiated `_rotation_vectors_` or `_lat, lon_`;; Can be used to set the original viewpoint. It is advisable to do as the default initial viewpoint is rather unhelpful from immediately overhead. - == Tips Create an axes origin marker to be able to see parts relative to it, for construction purposes. diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc index 4fb56ec3803..e220c7897b2 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: ini -:hal: hal -:ngc: ngc -:css: css - *`Qtscreen`* uses _QtVCP widgets_ for LinuxCNC integration. *Widget* is the general name for the _UI objects_ such as buttons and @@ -174,7 +167,6 @@ Disabled widgets typically have a different color and do not respond to actions. It is based on PyQt's `QGridLayout`. - === 'HalBar' - HAL Bar Level Indicator .QtVCP `HalBar`: Panel demonstrating the HAL Bar Level Indicator @@ -212,7 +204,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 +289,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 +408,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 +456,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 +639,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 @@ -699,7 +691,6 @@ If it is not as you like, modify its existing position and re-record. [[sub:qtvcp:widgets:axistoolbutton]] === `AxisToolButton` - Select and Set Axis Widget - //TODO AxisToolButton widget capture/example This allows one to *select and set an axis*. @@ -741,7 +732,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 +824,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 +852,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 +890,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 +902,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 +934,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 +1007,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 +1022,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 +1033,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 +1044,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 +1055,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 +1066,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 +1077,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 +1088,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 +1099,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 +1110,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 +1121,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 +1132,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 +1143,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 +1154,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 +1165,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 +1176,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 +1188,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 +1225,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 +1315,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 +1326,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 +1343,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 +1373,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 +1391,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 +1427,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 +1569,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 +1617,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 +1634,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 +1712,7 @@ self.w.originoffsetview.setProperty('metric_template','%10.3f') ---- * Or (if appropriate) in stylesheets + -[source,{css}] +[source,css] ---- OriginOffsetView{ qproperty-styleColorHighlist: lightblue; @@ -2100,7 +2091,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 +2245,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 +2317,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 +2456,7 @@ self.w.tooloffsetview.setProperty('metric_template','%10.3f') and in style sheets: -[source,{css}] +[source,css] ---- ToolOffsetView{ qproperty-styleColorHighlist: lightblue; @@ -3000,7 +2991,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; @@ -3073,7 +3064,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; @@ -3083,7 +3074,7 @@ Indicated_PushButton{ Or for a particular button: -[source,{css}] +[source,css] ---- Indicated_PushButton #button_estop{ qproperty-on_color: black; @@ -3129,7 +3120,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; @@ -3144,7 +3135,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; @@ -3184,7 +3175,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"; @@ -3269,7 +3260,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 @@ -3278,7 +3269,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. @@ -3313,7 +3304,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 7477a5580de..fc0af0752a3 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: ini -:hal: hal -:ngc: ngc -:css: 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/ @@ -374,7 +367,6 @@ self.on_keycall_F11_super = self.on_keycall_F11 # to point to our new function (of the same name) defined in this file. self.on_keycall_F11 = types.MethodType(on_keycall_F11, self) - # add a new pin to the screen: # pin callback to print the state @@ -449,14 +441,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 +465,7 @@ halrun -I -f my_panel.hal ---- .Example HAL file loading a QtVCP panel -[source,{hal}] +[source,hal] ---- # load realtime components loadrt threads @@ -486,7 +478,6 @@ loadusr -Wn my_panel qtvcp my_panel.ui # <1> # add components to thread addf classicladder.0.refresh thread1 - # connect pins net bit-input1 test_panel.checkbox_1 classicladder.0.in-00 net bit-hide test_panel.checkbox_4 classicladder.0.hide_gui @@ -686,7 +677,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 d03aecb7632..62a5bb28383 100644 --- a/docs/src/gui/tklinuxcnc.adoc +++ b/docs/src/gui/tklinuxcnc.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - [[sec:tklinuxcnc-intro]] == Introduction @@ -28,7 +22,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 a442b87d580..e58273e063f 100644 --- a/docs/src/gui/tooledit.adoc +++ b/docs/src/gui/tooledit.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Overview [NOTE] @@ -60,14 +54,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 +104,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 +115,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 85a08d6228c..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: ini -:hal: hal -:ngc: 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 90a938cadcc..5872d01ab7c 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: ini -:hal: hal -:ngc: 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 @@ -120,7 +114,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 @@ -140,7 +134,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 @@ -164,7 +158,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 @@ -173,7 +167,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 @@ -195,7 +189,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 @@ -208,7 +202,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 @@ -230,7 +224,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 @@ -247,7 +241,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 @@ -261,7 +255,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 @@ -275,7 +269,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 @@ -514,7 +508,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 @@ -544,7 +538,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,...] ---- @@ -554,7 +548,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 623f7c53dc3..487abfb5ac9 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: ini -:hal: hal -:ngc: ngc - (((HAL Component Generator))) == Introduction @@ -57,7 +51,6 @@ sudo apt install linuxcnc-uspace-dev Another method is using the Synaptic package manager, from the Applications menu, to install the `linuxcnc-dev` or `linuxcnc-uspace-dev` packages. - == Compiling === Inside the source tree @@ -498,7 +491,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 +698,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/components.adoc b/docs/src/hal/components.adoc index 77805fc768d..f4c01f17366 100644 --- a/docs/src/hal/components.adoc +++ b/docs/src/hal/components.adoc @@ -27,7 +27,6 @@ then try to explicitly specify the section, as in `man _section-no_ axis`, with See also the 'Man Pages' section of the link:../index.html[docs main page] or the link:../man/[directory listing]. To search in the man pages, use the UNIX tool `apropos`. - === User Interfaces (non-realtime) ==== Machine Control @@ -164,7 +163,6 @@ To search in the man pages, use the UNIX tool `apropos`. | link:../man/man1/stepconf.1.html[stepconf] |Configuration wizard for parallel-port based machines || | link:../man/man1/update_ini.1.html[update_ini] |Converts 2.7 format INI files to 2.8 format || - | link:../man/man1/debuglevel.1.html[debuglevel] |Sets the debug level for the non-realtime part of LinuxCNC || | link:../man/man1/emccalib.1.html[emccalib] |Adjust ini tuning variables on the fly with save option || | link:../man/man1/hal_input.1.html[hal_input] |Control HAL pins with any Linux input device, including USB HID devices || diff --git a/docs/src/hal/hal-examples.adoc b/docs/src/hal/hal-examples.adoc index f3a11f55cd8..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: ini -:hal: hal -:ngc: 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 7dfd229334b..3d19d77520a 100644 --- a/docs/src/hal/halmodule.adoc +++ b/docs/src/hal/halmodule.adoc @@ -165,7 +165,6 @@ writing files) must be done to complete the shutdown process. See <> for an overview of available functions. - == Constants Use these to specify details rather then the value they hold. diff --git a/docs/src/hal/halshow.adoc b/docs/src/hal/halshow.adoc index 62bb62d2aea..53d5e30456e 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: ini -:hal: hal -:ngc: ngc - (((Halshow))) The script `halshow` can help you find your way around a running HAL. It displays chosen HAL values and updates them continuously. @@ -53,7 +47,6 @@ $ halshow --fformat "%.5f" ./my.halshow For more information regarding the format, please refer to https://www.tcl.tk/man/tcl/TclCmd/format.html[the Tcl format man page]. - [[cap:halshow-layout]] .Halshow Layout image::images/halshow-layout.png["Halshow Layout",align="center"] @@ -92,7 +85,6 @@ Under _Tree View_ you will find: _Expand All_, _Collapse All_; _Expand Pins_, _Expand Parameters_, _Expand Signals_; and _Reload tree view_. _Reload tree view_ is useful when new components are loaded during runtime and should be displayed. - === HAL Show Area [[fig:halshow-show-tab]] @@ -228,14 +220,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 +264,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 +274,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 +311,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 89361a978dc..2b4c6197e96 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: ini -:hal: hal -:ngc: 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,7 +62,7 @@ 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 @@ -80,7 +74,7 @@ ITEM2 = value_2 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 32b017f519b..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: ini -:hal: hal -:ngc: 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 a818a71ae1b..ed2150fde8a 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: ini -:hal: hal -:ngc: 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. @@ -34,7 +28,6 @@ An Internet search, for example, found an astronomical application to control te Motors move the telescope into the right position, and it needs to know how to map motor activity with the effect of that positioning with the real world. Such a synchronisation of motor positions with real-world positions is reminiscent of what CNC machines need to do, or space craft. - Any machine controller needs to know: * about its internal state and how this maps to the environment (machine coordinates, state of switches/regulators), @@ -54,7 +47,6 @@ The HAL layer consists of parts (referred to as "components") that . adjust the planning for the next moves to complete a G-code instruction. - as non-realtime "user-space" components that run a "main loop" just like any other software, and may be interrupted or delayed when the rest of the system is busy or overloaded. - Taken together, HAL allows . to program for a machine that the programmer does not know directly, @@ -184,7 +176,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 80bf412974c..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: ini -:hal: hal -:ngc: 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 caba2550d1d..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: ini -:hal: hal -:ngc: 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/tutorial.adoc b/docs/src/hal/tutorial.adoc index cacd61d7c55..f9b0970d246 100644 --- a/docs/src/hal/tutorial.adoc +++ b/docs/src/hal/tutorial.adoc @@ -730,7 +730,6 @@ generator is cranking out step pulses, varying from 10 kHz forward to see how to bring those internal signals out to run motors in the real world, but first we want to look at them and see what is happening. - [[sec:tutorial-halmeter]] == Halmeter diff --git a/docs/src/hal/twopass.adoc b/docs/src/hal/twopass.adoc index 9c73c9e2a7b..1ea2eb513a6 100644 --- a/docs/src/hal/twopass.adoc +++ b/docs/src/hal/twopass.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == TWOPASS This section describes an option to have multiple load-commands for multiple instances of the same component at different positions in the file or among different files. @@ -21,16 +15,15 @@ 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 ---- - 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 +32,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 +41,7 @@ TWOPASS = anystring With TWOPASS enabled, you can have multiple specifications like: -[source,{hal}] +[source,hal] ---- loadrt and2 names=aa ... @@ -64,7 +57,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 +86,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 +106,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,7 +129,7 @@ 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 @@ -189,7 +182,6 @@ as that would eliminate the benefits of TWOPASS processing. The LinuxCNC commands that create signals (`net`) and commands that establish execution order (`addf`) should not be placed in excluded files. This is especially true for addf commands since their ordering may be important. - == Examples Examples of TWOPASS usage for a simulator are included in the directories: diff --git a/docs/src/install/latency-test.adoc b/docs/src/install/latency-test.adoc index e0f23e39cee..0c401ea399d 100644 --- a/docs/src/install/latency-test.adoc +++ b/docs/src/install/latency-test.adoc @@ -33,7 +33,6 @@ However, software step pulses also have some disadvantages: - jitter in the generated pulses - loads the CPU - [[sec:latency-tests]] == Latency Tests @@ -45,7 +44,6 @@ Running these tests will help determine if a computers is suitable for driving a [NOTE] Do not run LinuxCNC or StepConf while the latency test is running. - [[sec:latency-test]] === Latency Test diff --git a/docs/src/ladder/classic-ladder.adoc b/docs/src/ladder/classic-ladder.adoc index a8818f70244..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: ini -:hal: hal -:ngc: 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 f8959f98f15..45094109c47 100644 --- a/docs/src/ladder/ladder-examples.adoc +++ b/docs/src/ladder/ladder-examples.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Wrapping Counter To have a counter that 'wraps around' you have to use the preset pin @@ -52,7 +46,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 +55,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 +72,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 +90,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/lathe-user.adoc b/docs/src/lathe/lathe-user.adoc index ab23a5eee32..54c7727c000 100644 --- a/docs/src/lathe/lathe-user.adoc +++ b/docs/src/lathe/lathe-user.adoc @@ -4,12 +4,6 @@ [[cha:lathe-user-information]] = Lathe User Information -// Custom lang highlight -// must come after the doc title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - (((Lathe User Information))) This chapter will provide information specific to lathes. @@ -22,7 +16,7 @@ See the <> 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/man1/emccalib.1.adoc b/docs/src/man/man1/emccalib.1.adoc index 861d03a0f7d..bd0d3c9cfbc 100644 --- a/docs/src/man/man1/emccalib.1.adoc +++ b/docs/src/man/man1/emccalib.1.adoc @@ -8,7 +8,6 @@ emccalib - Adjust ini tuning variables on the fly with save option *emccalib.tcl* [_options_] - == DESCRIPTION The Calibration assistant. This tool Reads the HAL file and for every diff --git a/docs/src/man/man1/halstreamer.1.adoc b/docs/src/man/man1/halstreamer.1.adoc index f9fecf9a47f..d0edc9d3350 100644 --- a/docs/src/man/man1/halstreamer.1.adoc +++ b/docs/src/man/man1/halstreamer.1.adoc @@ -4,12 +4,10 @@ halstreamer - stream file data into HAL in real-time - == SYNOPSIS *halstreamer* [_options_] - == DESCRIPTION The HAL component *streamer*(9) and the program *halstreamer* are used together to stream data from a file into the HAL in real-time. diff --git a/docs/src/man/man1/hy_gt_vfd.1.adoc b/docs/src/man/man1/hy_gt_vfd.1.adoc index 2e69031d7af..5d90b3b951a 100644 --- a/docs/src/man/man1/hy_gt_vfd.1.adoc +++ b/docs/src/man/man1/hy_gt_vfd.1.adoc @@ -1,11 +1,9 @@ = hy_gt_vfd(1) - == NAME hy_gt_vfd - HAL non-realtime component for Huanyang GT-series VFDs - == SYNOPSIS *hy_gt_vfd* [_OPTIONS_] diff --git a/docs/src/man/man1/linuxcncrsh.1.adoc b/docs/src/man/man1/linuxcncrsh.1.adoc index 424c956579f..fbf092d310e 100644 --- a/docs/src/man/man1/linuxcncrsh.1.adoc +++ b/docs/src/man/man1/linuxcncrsh.1.adoc @@ -688,7 +688,6 @@ Subcommands for 'GET' and 'SET' are: With get, the current 'WAIT_MODE' setting is returned. With set, set the 'WAIT_MODE' setting to the specified value. - == EXAMPLE SESSION This section shows an example session to the local machine (*localhost*). diff --git a/docs/src/man/man1/mb2hal.1.adoc b/docs/src/man/man1/mb2hal.1.adoc index 669e32d4b70..1f638324324 100644 --- a/docs/src/man/man1/mb2hal.1.adoc +++ b/docs/src/man/man1/mb2hal.1.adoc @@ -75,7 +75,6 @@ See https://linuxcnc.org/docs/html/drivers/mb2hal.html[] for more information. *mb2hal.m.num_errors* u32 in:: Error counter - m = HAL_TX_NAME or transaction number if not set + n = element number (NELEMENTS) diff --git a/docs/src/man/man1/melfagui.1.adoc b/docs/src/man/man1/melfagui.1.adoc index 08c8b82c363..50b7a653c87 100644 --- a/docs/src/man/man1/melfagui.1.adoc +++ b/docs/src/man/man1/melfagui.1.adoc @@ -8,7 +8,6 @@ melfagui - Vismach Virtual Machine GUI *melfagui* is one of the sample *Vismach* GUIs for LinuxCNC, simulating a Mitsubishi serial manipulator. - == SEE ALSO *linuxcnc(1)* diff --git a/docs/src/man/man1/mesambccc.1.adoc b/docs/src/man/man1/mesambccc.1.adoc index cafddf82b11..73cc727bd56 100644 --- a/docs/src/man/man1/mesambccc.1.adoc +++ b/docs/src/man/man1/mesambccc.1.adoc @@ -145,7 +145,6 @@ the 'clamp' attribute is set in the '': (`S_ABCDEFGH`...`S_HGFEDCBA`) ** unsigned integer [0..18446744073709551615] (`U_ABCDEFGH`...`U_HGFEDCBA`) - === The main enclosing tag '' contains the communication parameters and other setup values as attributes: @@ -344,7 +343,6 @@ Recognized '/' attributes when sending Modbus commands: may be expected within the timeout period but not after the timeout expires. This may be required for flaky devices. Default false. - ==== Delay instruction Recognized '/' attributes in delay commands: diff --git a/docs/src/man/man1/svd-ps_vfd.1.adoc b/docs/src/man/man1/svd-ps_vfd.1.adoc index b28b15d25fc..e3ae5a7ba2c 100644 --- a/docs/src/man/man1/svd-ps_vfd.1.adoc +++ b/docs/src/man/man1/svd-ps_vfd.1.adoc @@ -4,7 +4,6 @@ svd-ps_vfd - HAL non-realtime component for SVD-P(S) VFDs - == SYNOPSIS *svd-ps_vfd* [_OPTIONS_] diff --git a/docs/src/man/man1/xhc-whb04b-6.1.adoc b/docs/src/man/man1/xhc-whb04b-6.1.adoc index e2beade376f..edeba9d6001 100644 --- a/docs/src/man/man1/xhc-whb04b-6.1.adoc +++ b/docs/src/man/man1/xhc-whb04b-6.1.adoc @@ -459,7 +459,6 @@ net pdnt.axis.x.jog-vel-mode whb.axis.x.jog-vel-mode net pdnt.axis.y.jog-vel-mode whb.axis.y.jog-vel-mode axis.y.jog-vel-mode net pdnt.axis.z.jog-vel-mode whb.axis.z.jog-vel-mode axis.z.jog-vel-mode - # macro buttons to MDI commands net pdnt.macro-1 whb.button.macro-1 halui.mdi-command-01 # use MDI command from main.ini net pdnt.macro-2 whb.button.macro-2 halui.mdi-command-02 # use MDI command from main.ini @@ -479,7 +478,6 @@ net pdnt.macro.11 whb.button.macro-11 net pdnt.macro.12 whb.button.macro-12 halui.mdi-command-12 # use MDI command from main.ini net pdnt.macro.13 whb.button.macro-13 halui.mdi-command-13 # use MDI command from main.ini - # flood and mist toggle signals net pdnt.flood.is-on whb.halui.flood.is-on halui.flood.is-on #return signal is on or off net pdnt.flood.off whb.halui.flood.off halui.flood.off #reserved whb.button.macro-15 diff --git a/docs/src/man/man3/hm2_pktuart.3.adoc b/docs/src/man/man3/hm2_pktuart.3.adoc index 489628c0a96..a3626a09f6c 100644 --- a/docs/src/man/man3/hm2_pktuart.3.adoc +++ b/docs/src/man/man3/hm2_pktuart.3.adoc @@ -235,7 +235,6 @@ int process(void *arg, long period) { } ---- - == PINS The functions / hostmot2 component do not create any HAL pins. diff --git a/docs/src/man/man9/demux_generic.9.adoc b/docs/src/man/man9/demux_generic.9.adoc index 01d75542fe8..086d3e64be3 100644 --- a/docs/src/man/man9/demux_generic.9.adoc +++ b/docs/src/man/man9/demux_generic.9.adoc @@ -13,7 +13,6 @@ Types: **b** = bit, **f** = float, **s** = signed integer, **u** = unsigned inte Example: **loadrt demux_generic config="**bb8,fu12**"** - == FUNCTIONS **demux-gen.**_NN_ Depending on the data types can run in either a floating point or non-floating point thread. diff --git a/docs/src/man/man9/hm2_modbus.9.adoc b/docs/src/man/man9/hm2_modbus.9.adoc index c602e639408..1cde71ecbee 100644 --- a/docs/src/man/man9/hm2_modbus.9.adoc +++ b/docs/src/man/man9/hm2_modbus.9.adoc @@ -31,7 +31,6 @@ PktUART ports. process-wide and all modules within the process will spit out messages at the requested level. This may cause quite some clutter in your terminal. - == DESCRIPTION The *hm2_modbus* driver implements the Modbus protocol and maps HAL pins to diff --git a/docs/src/man/man9/hm2_rpspi.9.adoc b/docs/src/man/man9/hm2_rpspi.9.adoc index 91938e2aea4..2ada991e9b7 100644 --- a/docs/src/man/man9/hm2_rpspi.9.adoc +++ b/docs/src/man/man9/hm2_rpspi.9.adoc @@ -6,7 +6,6 @@ hm2_rpspi - This driver has been superseded by the hm2_spix driver. LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware. - == SYNOPSIS *loadrt hm2_rpspi* diff --git a/docs/src/man/man9/hostmot2.9.adoc b/docs/src/man/man9/hostmot2.9.adoc index 743b01162a9..e2da9902819 100644 --- a/docs/src/man/man9/hostmot2.9.adoc +++ b/docs/src/man/man9/hostmot2.9.adoc @@ -81,10 +81,8 @@ The comma character (,) separates members of the config array from each other. For example, if your control computer has one 5I20 and one 5I23 you might load the hm2_pci driver with a HAL command (in halcmd) something like this: - *loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,firmware=hm2/5i23/SVSS8_8.BIT sserial_port_0=0000 num_encoders=4"* - Note: This assumes that the hm2_pci driver detects the 5I20 first and the 5I23 second. If the detection order does not match the order of the config strings, the hostmot2 driver will refuse to load the firmware and diff --git a/docs/src/man/man9/kins.9.adoc b/docs/src/man/man9/kins.9.adoc index c6fc0ff36f0..0235bbf9fca 100644 --- a/docs/src/man/man9/kins.9.adoc +++ b/docs/src/man/man9/kins.9.adoc @@ -69,7 +69,6 @@ Example: loadrt *trivkins coordinates=xz*:: Example: loadrt *trivkins coordinates=xyzy*:: Assigns: x==joint0, y0==joint1, z==joint2, y1==joint3: - The default kinematics type is *KINEMATICS_IDENTITY*. GUIs may provide special features for configurations using this default kinematics type. For instance, the AXIS GUI automatically handles joint and world mode @@ -77,7 +76,6 @@ operations so that the distinctions between joints and axes are not visible to the operator. This is feasible since there is an exact correspondence between a joint number and its matching axis letter. - The kinematics type can be set with the *kinstype=* parameter::: kinstype=**1** for KINEMATICS_IDENTITY (default if kinstype= omitted):: + diff --git a/docs/src/man/man9/streamer.9.adoc b/docs/src/man/man9/streamer.9.adoc index a05257da4f1..5316bb9fd85 100644 --- a/docs/src/man/man9/streamer.9.adoc +++ b/docs/src/man/man9/streamer.9.adoc @@ -71,11 +71,9 @@ One function is created per FIFO, numbered from zero. halstreamer(1), sampler(9), halsampler(1) - == BUGS Should an enable HAL pin be added, to allow streaming to be turned on and off? - == AUTHOR Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other members of the LinuxCNC development team. diff --git a/docs/src/motion/5-axis-kinematics.adoc b/docs/src/motion/5-axis-kinematics.adoc index 37e3165d728..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: ini -:hal: hal -:ngc: 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 4faac6e60a8..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: ini -:hal: hal -:ngc: 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 989e852a455..d0bd12d01a0 100644 --- a/docs/src/motion/switchkins.adoc +++ b/docs/src/motion/switchkins.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Introduction A number of kinematics modules support the switching of @@ -54,7 +48,7 @@ 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 @@ -68,7 +62,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 +135,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 +145,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 +194,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 +217,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 +227,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 796f4041e07..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: ini -:hal: hal -:ngc: 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 a82ef6b5e26..e901faa39e5 100644 --- a/docs/src/plasma/qtplasmac.adoc +++ b/docs/src/plasma/qtplasmac.adoc @@ -4,12 +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: ini -:hal: hal -:ngc: ngc - == Preamble Except where noted, this guide assumes the user is using the latest version of QtPlasmaC. @@ -373,7 +367,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 +536,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 +549,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 +567,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 +585,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 +597,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 +606,7 @@ DISPLAY = qtvcp -f qtplasmac This variable is mandatory. -[source,{ini}] +[source,ini] ---- SPINDLES = 3 ---- @@ -621,7 +615,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 +626,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 +637,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 @@ -701,7 +695,6 @@ Some functions/features are only used for particular modes and are not displayed |C |This button clears the live plot. |=== - .*MACHINE* representation [cols="4,16",options="header"] //[grid=none,frame=ends] @@ -932,7 +925,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 +943,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 +1132,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 ---- @@ -1212,7 +1205,6 @@ The text may be edited at any time and will be loaded ready for use if the *SAVE To return the *EXIT WARNING MESSAGE* text to the last saved value press the *RELOAD* button. - .*UTILITIES* Some standard LinuxCNC utilities are provided as an aid in the diagnosis of issues that may arise: @@ -1286,13 +1278,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 +1327,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 +1386,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 +1416,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 +1449,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 +1531,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 +1617,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 +1627,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 +1677,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 +1724,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 +1745,14 @@ This is also a requirement for <_.prefs file: -[source,{ini}] +[source,ini] ---- X axis = n.n Y axis = n.n @@ -1995,7 +1987,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 +2029,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 +2087,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 +2145,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 +2434,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 +2481,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 +2682,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 +2855,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 +3036,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 ---- @@ -3138,7 +3130,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 +3211,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 +3220,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 +3262,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 +3273,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 +3283,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 +3298,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 +3308,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 +3318,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 +3339,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 +3352,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 +3433,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 +3461,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 +3511,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 +3525,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 +3533,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 +3556,7 @@ as will pressing 'Esc' if keyboard shortcuts are enabled in the <> feature. -[source,{ini}] +[source,ini] ---- n Code = single-cut ---- @@ -3610,28 +3602,28 @@ The following GUI buttons and Keyboard Shortcuts (if enabled in the <>. -[source,{ini}] +[source,ini] ---- n Code = manual-cut ---- @@ -3655,7 +3647,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 +3658,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 +3669,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 +3679,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 +3733,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 +3835,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 +3868,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 +3885,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 +3905,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 +3920,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 +3940,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 +3950,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 ---- @@ -4040,7 +4032,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 +4087,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 +4132,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 +4163,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 +4665,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 +4680,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 e585a8c7200..6adfb29c7a1 100644 --- a/docs/src/remap/remap.adoc +++ b/docs/src/remap/remap.adoc @@ -4,10 +4,6 @@ [[cha:remap]] = Remap Extending G-code -:ini: ini -:hal: hal -:ngc: ngc - == Introduction: Extending the RS274NGC Interpreter by Remapping Codes === A Definition: Remapping Codes @@ -56,7 +52,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 +128,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 +214,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 +384,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 +409,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 +563,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 +730,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 +784,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 +829,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 +854,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 +896,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 +943,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 +958,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 +966,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 +1017,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 +1070,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 +1079,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 +1144,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 +1427,7 @@ def retrieve_param(self, **words): return INTERP_OK ---- -[source,{ngc}] +[source,ngc] ---- o sub (debug, call_level=#<_call_level> myname=#) @@ -1558,7 +1554,7 @@ def _pi(self): return 3.1415926535 ---- -[source,{ngc}] +[source,ngc] ---- # = [2 * # * #<_pi>] ---- @@ -1648,7 +1644,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 +2033,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 +2052,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 @@ -2170,7 +2166,6 @@ All the interpreter does is evaluate the toolnumber parameter, looks up its corr remembers it in the `selected_pocket` variable for later, and queues a canon command (SELECT_TOOL). See 'Interp::convert_tool_select' in 'src/emc/rs274/interp_execute.cc'. - .Task action on SELECT_TOOL When `task` gets around to handle a SELECT_TOOL, it sends a EMC_TOOL_PREPARE message to the `iocontrol` process, which handles most tool-related actions in LinuxCNC. @@ -2252,7 +2247,6 @@ If zero, this means 'unload tool', else 'set current tool number to Q'. .Building the replacement for `M61` An example Python redefinition for `M61` can be found in the `set_tool_number` function in `nc_files/remap_lib/python-stdglue/stdglue.py`. - == Status . The RELOAD_ON_CHANGE feature is fairly broken. Restart after changing a Python file. diff --git a/docs/src/source-highlight/hal-demo.adoc b/docs/src/source-highlight/hal-demo.adoc index a213dd77155..e5ceea71fc5 100644 --- a/docs/src/source-highlight/hal-demo.adoc +++ b/docs/src/source-highlight/hal-demo.adoc @@ -8,18 +8,14 @@ // HTML works fine // these attributes must come after the document title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - // begin a listing of ini/hal/ngc files like so: -//[source,{ini}] -//[source,{hal}] -//[source,{ngc}] +//[source,ini] +//[source,hal] +//[source,ngc] Details of the filter can be found in `./doc/source-highlight-filter.txt`. -[source,{hal}] +[source,hal] --------------------------------------------------------------------- # note this is for highlighting demo only - there aint any use to it diff --git a/docs/src/source-highlight/ini-demo.adoc b/docs/src/source-highlight/ini-demo.adoc index cc1d3d4b0a8..04a78f20b0e 100644 --- a/docs/src/source-highlight/ini-demo.adoc +++ b/docs/src/source-highlight/ini-demo.adoc @@ -10,16 +10,12 @@ Details of the filter can be found in `./doc/source-highlight-filter.txt`. // HTML works fine. // these attributes must come after the document title, to work around a bug in asciidoc 8.6.6 -:ini: ini -:hal: hal -:ngc: ngc - // Begin a listing of INI/HAL/ngc files like so: -//[source,{ini}] -//[source,{hal}] -//[source,{ngc}] +//[source,ini] +//[source,hal] +//[source,ngc] -[source,{ini}] +[source,ini] --------------------------------------------------------------------- # EMC controller parameters for a simulated machine. diff --git a/docs/src/source-highlight/ngc-demo.adoc b/docs/src/source-highlight/ngc-demo.adoc index c3c6387ca11..a48103d5aed 100644 --- a/docs/src/source-highlight/ngc-demo.adoc +++ b/docs/src/source-highlight/ngc-demo.adoc @@ -8,18 +8,14 @@ // HTML works fine. // These attributes must come after the document title, to work around a bug in asciidoc 8.6.6. -:ini: ini -:hal: hal -:ngc: ngc - // Begin a listing of INI/HAL/NGC files like so: -//[source,{ini}] -//[source,{hal}] -//[source,{ngc}] +//[source,ini] +//[source,hal] +//[source,ngc] Details of the filter can be found in `./doc/source-highlight-filter.txt`. -[source,{ngc}] +[source,ngc] --------------------------------------------------------------------- ; G-code highlighting stresstest - useless otherwise ; diff --git a/docs/src/tooldatabase/tooldatabase.adoc b/docs/src/tooldatabase/tooldatabase.adoc index de02ec86b22..d2ff3bb6fae 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: ini -:hal: hal -:ngc: 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] @@ -122,7 +116,6 @@ The updated list of tools will be used on subsequent get commands or load_tool_t [NOTE] Removal of a tool number should only be done if the tool number is not currently loaded in spindle. - ==== Debug Environmental Variables Exporting the environmental variable DB_SHOW enables LinuxCNC prints (to stdout) that show tool data retrieved from the *db_program* at startup and at subsequent reloading of tool data. diff --git a/docs/src/user/user-concepts.adoc b/docs/src/user/user-concepts.adoc index 570d0c3bcd5..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: ini -:hal: hal -:ngc: 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) ---- From f314b5c68edb3d130eed0dbd5e0afdf33619e1d4 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:31:51 +0800 Subject: [PATCH 14/30] build: fail configure when an explicitly enabled docs dep is missing hansu pointed out on #4053 that ./configure --with-realtime=uspace --enable-build-documentation=pdf,html happily succeeds with only WARN-level diagnostics when asciidoctor / asciidoctor-pdf / rsvg-convert are absent, silently flipping BUILD_DOCS back to "no". Running 'make pdfdocs' afterwards produces no docs and no clear hint that the configure step had stripped the docs targets. Convert all of those AC_MSG_WARN+disable paths to AC_MSG_ERROR with an 'apt-get install ...' hint. Same treatment for ghostscript (the PDF post-process), librsvg2-bin (SVG -> PDF/PNG) and w3c-linkchecker for the HTML side. Also add an AC_MSG_ERROR for the NotoSerifCJK font when PDF docs are enabled. The Submakefile depends on the .ttc unconditionally (the CJK glyph fallback is wired into every PDF, not only the translated ones), so missing fonts-noto-cjk used to surface as a cryptic 'No rule to make target NotoSerifCJK-Regular.ttc' at build time. --- src/configure.ac | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/src/configure.ac b/src/configure.ac index fdf877b6f30..1052e1e87af 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1061,28 +1061,28 @@ AC_ARG_ENABLE(build-documentation, AC_MSG_RESULT([no]) ]) -# Programs required for building all documentation +# Programs required for building all documentation. When the user +# explicitly asks for docs (--enable-build-documentation=...), missing +# tools are a hard error: continuing with BUILD_DOCS silently flipped +# back to "no" gives a confusing experience where 'make' succeeds and +# produces no docs. if ( test "$BUILD_DOCS" = "yes" ) ; then AC_PATH_PROG(ASCIIDOCTOR,asciidoctor,"none") if ( test "none" = "$ASCIIDOCTOR" ) ; then - AC_MSG_WARN([no asciidoctor, documentation cannot be built]) - BUILD_DOCS=no + AC_MSG_ERROR([no asciidoctor, cannot build documentation +install with "sudo apt-get install asciidoctor"]) fi - 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]) - BUILD_DOCS=no - fi + AC_PATH_PROG(GS,gs,"none") + if ( test "none" = "$GS" ) ; then + AC_MSG_ERROR([no gs, cannot build documentation +install with "sudo apt-get install ghostscript"]) fi - if ( test "$BUILD_DOCS" = "yes" ) ; then - AC_PATH_PROG(RSVG_CONVERT,rsvg-convert,"none") - if ( test "none" = "$RSVG_CONVERT" ) ; then - AC_MSG_WARN([no rsvg-convert, documentation cannot be built]) - BUILD_DOCS=no - fi + AC_PATH_PROG(RSVG_CONVERT,rsvg-convert,"none") + if ( test "none" = "$RSVG_CONVERT" ) ; then + AC_MSG_ERROR([no rsvg-convert, cannot build documentation +install with "sudo apt-get install librsvg2-bin"]) fi fi @@ -1090,8 +1090,17 @@ fi if ( test "$BUILD_DOCS_PDF" = "yes" ) ; then AC_PATH_PROG(ASCIIDOCTOR_PDF,asciidoctor-pdf,"none") if ( test "none" = "$ASCIIDOCTOR_PDF" ) ; then - AC_MSG_WARN([no asciidoctor-pdf, PDF documentation cannot be built]) - BUILD_DOCS=no + AC_MSG_ERROR([no asciidoctor-pdf, cannot build PDF documentation +install with "sudo apt-get install asciidoctor-pdf" (Debian sid/trixie) +or "sudo apt-get install ruby-asciidoctor-pdf" (Debian bookworm)]) + fi + + # NotoSerifCJK is the fallback font for CJK glyphs in translated + # PDFs. Required only when both PDF and translations are enabled. + NOTOCJK_FONT=/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc + if ( test ! -r "$NOTOCJK_FONT" ) ; then + AC_MSG_ERROR([NotoSerifCJK font ($NOTOCJK_FONT) not found, cannot build PDF documentation +install with "sudo apt-get install fonts-noto-cjk"]) fi fi @@ -1099,9 +1108,8 @@ fi 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_ERROR([no checklink, cannot build HTML documentation install with "sudo apt-get install w3c-linkchecker"]) - BUILD_DOCS=no fi fi From f12a44c21e7667fc36ce86b7384a3d6b8b300f64 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:35:54 +0800 Subject: [PATCH 15/30] build: probe NotoSerifCJK path portably, drop hardcoded /usr/share Bertho noted on #4053 that hardcoding the .ttc paths under /usr/share/fonts/opentype/noto/ pins the build to Debian / Ubuntu and will break Arch, Fedora, openSUSE, etc. Move the discovery into configure.ac. It first asks fontconfig (`fc-match --format='%{file}' 'Noto Serif CJK SC:style=...'`) and falls back to the package paths that the major distributions actually use (Debian, Arch noto-fonts-cjk, Fedora google-noto-cjk-fonts). The probe rejects anything that is not a .ttc, because otf2ttf.py needs the TrueType Collection to pick index 2 (SC) out of it. If nothing matches, configure errors with a per-distro install hint, and the user can override with ./configure NOTOCJK_REGULAR_TTC=/path/to/Regular.ttc \ NOTOCJK_BOLD_TTC=/path/to/Bold.ttc The resolved paths flow through Makefile.inc as NOTOCJK_REGULAR_TTC and NOTOCJK_BOLD_TTC; docs/src/Submakefile now references the substituted variables instead of the literal /usr/share path. --- docs/src/Submakefile | 12 +++++---- src/Makefile.inc.in | 2 ++ src/configure.ac | 58 +++++++++++++++++++++++++++++++++++++++----- 3 files changed, 61 insertions(+), 11 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index b1d3893d9de..27315c61565 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -680,23 +680,25 @@ $(DOC_DIR)/html/index.html: $(DOC_SRCDIR)/index.tmpl objects/index.incl $(DOC_SR # its own anchor index (Master_*.adoc under DOC_SRCDIR for English, # DOC_SRCDIR//Master_*.adoc for translations). DOC_FONT_DIR = $(DOC_SRCDIR)/.fonts -NOTOCJK_TTC = /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ - /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc +# 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 # Build a TrueType (glyf-based) copy of the Simplified Chinese cut of the -# Noto Serif CJK font. Debian ships Noto Serif CJK only as a CFF/OTF +# 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. -$(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf: /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc $(DOC_SRCDIR)/otf2ttf.py +$(DOC_FONT_DIR)/NotoSerifCJKsc-Regular.ttf: $(NOTOCJK_REGULAR_TTC) $(DOC_SRCDIR)/otf2ttf.py @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) $< $@.tmp && mv $@.tmp $@ -$(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc $(DOC_SRCDIR)/otf2ttf.py +$(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: $(NOTOCJK_BOLD_TTC) $(DOC_SRCDIR)/otf2ttf.py @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) $< $@.tmp && mv $@.tmp $@ diff --git a/src/Makefile.inc.in b/src/Makefile.inc.in index b21efaf58b9..848adcbd285 100644 --- a/src/Makefile.inc.in +++ b/src/Makefile.inc.in @@ -127,6 +127,8 @@ 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@ diff --git a/src/configure.ac b/src/configure.ac index 1052e1e87af..ec0d415deef 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1095,13 +1095,59 @@ install with "sudo apt-get install asciidoctor-pdf" (Debian sid/trixie) or "sudo apt-get install ruby-asciidoctor-pdf" (Debian bookworm)]) fi - # NotoSerifCJK is the fallback font for CJK glyphs in translated - # PDFs. Required only when both PDF and translations are enabled. - NOTOCJK_FONT=/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc - if ( test ! -r "$NOTOCJK_FONT" ) ; then - AC_MSG_ERROR([NotoSerifCJK font ($NOTOCJK_FONT) not found, cannot build PDF documentation -install with "sudo apt-get install fonts-noto-cjk"]) + # 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; fall back to the package paths shipped by the major + # distributions if fc-match is not available or did not return a + # .ttc. + AC_MSG_CHECKING([for NotoSerifCJK Regular .ttc]) + NOTOCJK_REGULAR_TTC="" + for f in \ + "`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Regular' 2>/dev/null`" \ + /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ + /usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc \ + /usr/share/fonts/google-noto-cjk-fonts/NotoSerifCJK-Regular.ttc \ + /usr/share/fonts/google-noto-cjk/NotoSerifCJK-Regular.ttc ; do + case "$f" in + *.ttc) test -r "$f" && NOTOCJK_REGULAR_TTC="$f" && break ;; + esac + done + if test -z "$NOTOCJK_REGULAR_TTC" ; then + AC_MSG_RESULT([no]) + AC_MSG_ERROR([NotoSerifCJK Regular TrueType Collection not found, cannot build PDF documentation +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. +If the .ttc is in a non-standard location, point us at it with + ./configure NOTOCJK_REGULAR_TTC=/path/to/NotoSerifCJK-Regular.ttc \ + NOTOCJK_BOLD_TTC=/path/to/NotoSerifCJK-Bold.ttc]) + fi + AC_MSG_RESULT([$NOTOCJK_REGULAR_TTC]) + + AC_MSG_CHECKING([for NotoSerifCJK Bold .ttc]) + NOTOCJK_BOLD_TTC="" + for f in \ + "`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Bold' 2>/dev/null`" \ + /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc \ + /usr/share/fonts/noto-cjk/NotoSerifCJK-Bold.ttc \ + /usr/share/fonts/google-noto-cjk-fonts/NotoSerifCJK-Bold.ttc \ + /usr/share/fonts/google-noto-cjk/NotoSerifCJK-Bold.ttc ; do + case "$f" in + *.ttc) test -r "$f" && NOTOCJK_BOLD_TTC="$f" && break ;; + esac + done + if test -z "$NOTOCJK_BOLD_TTC" ; then + AC_MSG_RESULT([no]) + AC_MSG_ERROR([NotoSerifCJK Bold TrueType Collection not found, cannot build PDF documentation +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.]) fi + AC_MSG_RESULT([$NOTOCJK_BOLD_TTC]) + AC_SUBST(NOTOCJK_REGULAR_TTC) + AC_SUBST(NOTOCJK_BOLD_TTC) fi # Programs required only for building the HTML documentation From b765cf3263a49f81447d07b180e6156bc4b2d422 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:45:58 +0800 Subject: [PATCH 16/30] build: wire CJK_TTFS into manpage PDF rule CI sid run for 95f9d0c errored with No such file or directory - NotoSerifCJKsc-Regular.ttf not found in /__w/linuxcnc/linuxcnc/docs/src or GEM_FONTS_DIR make[2]: *** [Submakefile:520: LinuxCNC_Manual_Pages.pdf] Error 1 The shared pdf-theme.yml lists NotoSerifCJKsc-Regular / Bold as the CJK fallback, so every asciidoctor-pdf invocation that uses the theme needs pdf-fontsdir to point at $(DOC_FONT_DIR) and CJK_TTFS as a prerequisite to force the .ttf conversion ahead of time. The new manpage PDF rule did neither. Move the rule down to sit next to the other PDF rules (after the CJK font setup so it can reference CJK_TTFS / DOC_FONT_DIR without forward refs), add CJK_TTFS to its prerequisites, and pass the pdf-fontsdir attribute through to asciidoctor-pdf. --- docs/src/Submakefile | 119 ++++++++++++++++++++++--------------------- 1 file changed, 62 insertions(+), 57 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 27315c61565..71c3d7873d9 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -482,63 +482,9 @@ 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)) -# 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 - @$(ECHO) Formatting manual pages as PDF - @rm -f $@ $@.raw - $(Q)asciidoctor-pdf \ - -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ - -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ - -a mansource=LinuxCNC \ - -a manmanual='LinuxCNC Documentation' \ - -a source-highlighter=rouge \ - -a "lversion=$(shell cat ../VERSION)" \ - -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ - -d book \ - -o $@.raw $< || (X=$$?; rm -f $@.raw; 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 $@ +# 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. PDF_TARGETS_LinuxCNC_Getting_Started := $(DOC_DIR)/LinuxCNC_Getting_Started.pdf $(foreach L,$(LANGUAGES),$(DOC_DIR)/LinuxCNC_Getting_Started_$(L).pdf) @@ -734,6 +680,65 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp || (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 $(CJK_TTFS) + @$(ECHO) Formatting manual pages as PDF + @rm -f $@ $@.raw + $(Q)asciidoctor-pdf \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ + -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ + -a mansource=LinuxCNC \ + -a manmanual='LinuxCNC Documentation' \ + -a source-highlighter=rouge \ + -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; 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 $(ECHO) Depending $< @mkdir -p $(dir $@) From 3c30d24bd5f7ffae4326a3e884d80b061ade4ce3 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 19:51:30 +0800 Subject: [PATCH 17/30] build: revert configure docs-deps to warn-and-disable Bertho reported on #4053 that building an arch-only Debian package (debuild --build=any) now errors at configure time with checking whether to build documentation... PDF requested checking for gs... none configure: error: no gs, cannot build documentation The root cause is f314b5c. debian/rules.in passes --enable-build-documentation=pdf unconditionally, but --build=any deliberately skips Build-Depends-Indep (the docs toolchain lives there), so the configure-time docs probes never had gs / asciidoctor / rsvg-convert available on that path. The previous WARN-and-disable behaviour quietly turned BUILD_DOCS off and the arch-only build completed; the new hard error breaks it. Restore WARN+disable for asciidoctor / gs / rsvg-convert / asciidoctor-pdf / checklink, but keep the new hard error for the NotoSerifCJK font. The font check was the actual hansu complaint: missing fonts-noto-cjk used to surface as a cryptic "No rule to make target NotoSerifCJK-Regular.ttc" deep in the make log, and a clear configure error there is worth the strictness. Skipping that check when BUILD_DOCS_PDF is already off keeps it out of the arch-only path. --- src/configure.ac | 50 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/src/configure.ac b/src/configure.ac index ec0d415deef..8929b9f498f 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1061,28 +1061,43 @@ AC_ARG_ENABLE(build-documentation, AC_MSG_RESULT([no]) ]) -# Programs required for building all documentation. When the user -# explicitly asks for docs (--enable-build-documentation=...), missing -# tools are a hard error: continuing with BUILD_DOCS silently flipped -# back to "no" gives a confusing experience where 'make' succeeds and -# produces no docs. +# Programs required for building all documentation. Missing tools +# warn and disable docs rather than erroring: debian/rules unconditionally +# passes --enable-build-documentation, and an arch-only build (debuild +# --build=any) deliberately skips the Build-Depends-Indep that supply +# these tools, so a hard error here would break that path. The make +# rules themselves error clearly if you ask for `pdfdocs`/`htmldocs` +# when BUILD_DOCS=no. if ( test "$BUILD_DOCS" = "yes" ) ; then AC_PATH_PROG(ASCIIDOCTOR,asciidoctor,"none") if ( test "none" = "$ASCIIDOCTOR" ) ; then - AC_MSG_ERROR([no asciidoctor, cannot build documentation + 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 - AC_PATH_PROG(GS,gs,"none") - if ( test "none" = "$GS" ) ; then - AC_MSG_ERROR([no gs, cannot build documentation + 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 install with "sudo apt-get install ghostscript"]) + BUILD_DOCS=no + BUILD_DOCS_PDF=no + BUILD_DOCS_HTML=no + fi fi - AC_PATH_PROG(RSVG_CONVERT,rsvg-convert,"none") - if ( test "none" = "$RSVG_CONVERT" ) ; then - AC_MSG_ERROR([no rsvg-convert, cannot build documentation + if ( test "$BUILD_DOCS" = "yes" ) ; then + 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 fi @@ -1090,9 +1105,10 @@ fi if ( test "$BUILD_DOCS_PDF" = "yes" ) ; then AC_PATH_PROG(ASCIIDOCTOR_PDF,asciidoctor-pdf,"none") if ( test "none" = "$ASCIIDOCTOR_PDF" ) ; then - AC_MSG_ERROR([no asciidoctor-pdf, cannot build PDF documentation + AC_MSG_WARN([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)]) + BUILD_DOCS_PDF=no fi # NotoSerifCJK is the fallback font that asciidoctor-pdf reaches @@ -1101,7 +1117,10 @@ or "sudo apt-get install ruby-asciidoctor-pdf" (Debian bookworm)]) # otf2ttf.py picks index 2 (SC) out of it. Probe via fontconfig # first; fall back to the package paths shipped by the major # distributions if fc-match is not available or did not return a - # .ttc. + # .ttc. Kept as a hard error (rather than warn-and-disable like + # the tool checks above) because a missing font otherwise surfaces + # as the cryptic "No rule to make target NotoSerifCJK-Regular.ttc" + # deep in the make output -- the original hansu complaint on #4053. AC_MSG_CHECKING([for NotoSerifCJK Regular .ttc]) NOTOCJK_REGULAR_TTC="" for f in \ @@ -1154,8 +1173,9 @@ fi if ( test "$BUILD_DOCS_HTML" = "yes" ) ; then AC_PATH_PROG(CHECKLINK,checklink,"none") if ( test "none" = "$CHECKLINK" ) ; then - AC_MSG_ERROR([no checklink, cannot build HTML documentation + AC_MSG_WARN([no checklink, HTML documentation cannot be built install with "sudo apt-get install w3c-linkchecker"]) + BUILD_DOCS_HTML=no fi fi From 459bc2d98d3def67828527a25ef95e29985b409b Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 20:00:36 +0800 Subject: [PATCH 18/30] docs: special-case LinuxCNC #<_ini[...]NAME> and #<_hal[...]> in NGC Bertho noted on #4053 that the LinuxCNC system parameters #<_ini[SECTION]NAME> (read a value from the INI file) and #<_hal[pin.or.signal]> (read a HAL pin / signal) are dialect-specific enough that they deserve to stand out from the rest of variable expansion in code samples, rather than being lumped under the generic #<...> named-parameter rule. Add two dedicated rules ahead of the generic one and tokenise the sub-parts separately so the section / pin name reads differently: #<_ini[SECTION]NAME> ^ ^ ^ ^ ^ | | | | Name::Variable | | | Name::Constant | | Name::Constant + Punctuation brackets | Name::Builtin Name::Variable #<_hal[pin.or.signal]> ^ ^ ^ ^ | | | Name::Variable | | Name::Attribute (same token as a HAL pin elsewhere) | Name::Builtin Name::Variable Generic # and #100 fall through to the existing rules. --- docs/src/extensions/rouge_ngc.rb | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/src/extensions/rouge_ngc.rb b/docs/src/extensions/rouge_ngc.rb index 6bd04e560e9..539b70697b8 100644 --- a/docs/src/extensions/rouge_ngc.rb +++ b/docs/src/extensions/rouge_ngc.rb @@ -10,6 +10,7 @@ # - 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, ...) @@ -56,7 +57,23 @@ class NGC < RegexLexer rule %r/\([dD][eE][bB][uU][gG],/, Comment::Special, :debug_comment rule %r/\([^)]*\)/, Comment::Multiline - # Parameters + # 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)(\[)([^\]]+)(\])([^>]*)(>)/i do + groups Name::Variable, Name::Builtin, Punctuation, + Name::Constant, Punctuation, Name::Constant, Name::Variable + end + rule %r/(#<)(_hal)(\[)([^\]]+)(\])(>)/i do + groups Name::Variable, Name::Builtin, Punctuation, + Name::Attribute, Punctuation, Name::Variable + end + + # Parameters (named / numbered, generic) rule %r/#<[^>]+>/, Name::Variable rule %r/#\d+/, Name::Variable From 2c5075c67a4e9c38d93c30b9c6e722df641e97a8 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 20:13:59 +0800 Subject: [PATCH 19/30] docs: auto-substitute foo_en.ext -> foo_.ext in image resolver Bertho proposed on #4053 a uniform naming convention for translated images: the default is img_en.ext (English), translated variants live alongside it as img_de.ext, img_fr.ext, ... in the same source directory. The author writes img_en.ext in the .adoc; the build silently picks the localised file when it exists. The source tree already follows the convention partially (see docs/src/gcode/images/comp-path_fr.svg next to comp-path_en.svg). What was missing is the lookup. Extend the asciidoctor image resolver: - infer the document language from the .adoc's path (docs/src//... -> , otherwise 'en') - if the macro target ends with _en. and the document language is not en, try the _. variant first; fall back to the original target if the translation does not exist - applied to both block (image::) and inline (image:) macros - PDF backend still rewrites to absolute paths; HTML now also receives the relative-target rewrite when a translated variant is picked, so .html-images-stamp copies the right file English-only docs and macros without an _en suffix are untouched. --- docs/src/extensions/image_resolver.rb | 77 ++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 14 deletions(-) diff --git a/docs/src/extensions/image_resolver.rb b/docs/src/extensions/image_resolver.rb index 229b80c4a27..badcf7b9cf3 100644 --- a/docs/src/extensions/image_resolver.rb +++ b/docs/src/extensions/image_resolver.rb @@ -1,10 +1,17 @@ # docs/src/extensions/image_resolver.rb # # Asciidoctor treeprocessor that resolves image targets the way the -# asciidoc-py + docs/src/image-wildcard pair did: +# 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. @@ -25,12 +32,9 @@ class ImageResolver < Asciidoctor::Extensions::Treeprocessor LANG_RE = %r{/src/(de|es|fr|nb|ru|uk|zh_CN)/} def process(document) - # For HTML output the relative target is correct as-is — asciidoctor - # writes it straight into and a sibling copy of the - # image tree makes it resolve at deploy time. Only PDF embedding - # needs absolute paths so prawn-svg / image reading can find the - # file at convert time. - return document unless document.backend == 'pdf' + # PDF embedding needs absolute paths so prawn-svg / image reading + # can find the file at convert time; HTML only needs the relative + # rewrite when the lang-suffix swap picks a translated variant. walk(document) document end @@ -65,14 +69,45 @@ def rewrite(node) src = node.file || node.document.attr('docfile') return unless src base_dir = File.dirname(File.expand_path(src)) + lang = doc_language(src) + pdf = node.document.backend == 'pdf' + + # Try a language-specific variant of the filename first. + if lang != 'en' + swapped = swap_lang(target, lang) + if swapped != target + abs = resolve_candidate(File.expand_path(swapped, base_dir)) + if abs + node.set_attr('target', pdf ? abs : swapped) + apply_default_width(node) if pdf + return + end + end + end - candidate = resolve_candidate(File.expand_path(target, base_dir)) - return unless candidate - - node.set_attr('target', candidate) + # No translated variant available (or English doc); the original + # target stays for HTML, only PDF needs the absolute rewrite. + return unless pdf + abs = resolve_candidate(File.expand_path(target, base_dir)) + return unless abs + node.set_attr('target', abs) apply_default_width(node) end + # Returns the document language inferred from the source file path + # (one of LANG_RE's capture groups), or 'en' for the canonical tree. + def doc_language(src) + m = LANG_RE.match(src.to_s) + m ? m[1] : 'en' + end + + # Rewrite an `*_en.` 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 @@ -93,11 +128,13 @@ def resolve_candidate(path) def rewrite_inline_in_block(block) base_dir = File.dirname(File.expand_path(block.file)) + lang = doc_language(block.file) + 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) { changed = true } } + new_lines = block.lines.map { |ln| rewrite_inline(ln, base_dir, lang, pdf) { changed = true } } block.lines = new_lines if changed end @@ -106,19 +143,31 @@ def rewrite_inline_in_block(block) old = block.instance_variable_get(:@text) if old.is_a?(String) && !old.empty? changed = false - new_text = rewrite_inline(old, base_dir) { changed = true } + new_text = rewrite_inline(old, base_dir, lang, pdf) { changed = true } block.text = new_text if changed end end end - def rewrite_inline(text, base_dir) + def rewrite_inline(text, base_dir, lang, 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)) + 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)) if candidate yield if block_given? From dbc79d14f8bc05484bc7c8d5766d988e7e786488 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 22:31:30 +0800 Subject: [PATCH 20/30] docs: address hansu/bertho review, fix CI hangs and HTML styling HTML styling: restore body margin (5% with 768px breakpoint), sans-serif headings, blueish tint on h3+ headings, toctitle and dt color #527bbd, drop full-line click target on TOC items per user feedback. -a compat-mode added to all asciidoctor invocations so 12k legacy 'word' single-quoted emphasis renders italic instead of literal. CI hardening: timeout 900s wrapper on manpage PDF book invocation so future asciidoctor-pdf hangs fail fast with a clear message rather than holding a runner. concurrency cancel-in-progress on pull_request events so successive pushes to the same PR don't stack runs. Submakefile .so dep generator now handles both 'manN/file.N' and bare 'file.N' .so directives (was doubling section prefix). Source fixes for asciidoctor strict parsing: lut5.comp header cell '2+^h|Weight' spanned 2 of 6 cols (header summed to 7); hm2_rpspi.9.adoc final row missing third cell; hm2_7i43.9.adoc synopsis embedded quote in confused prawn HTML parser, wrap in pass:[]. --- .github/workflows/ci.yml | 4 ++++ docs/html/linuxcnc.css | 21 ++++++++++++++++++--- docs/src/Submakefile | 13 ++++++++++--- docs/src/man/man9/hm2_7i43.9.adoc | 2 +- docs/src/man/man9/hm2_rpspi.9.adoc | 2 +- src/hal/components/lut5.comp | 2 +- 6 files changed, 35 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4fa3e19d305..1e1d696901f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,6 +13,10 @@ on: permissions: contents: read # to fetch code (actions/checkout) +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + env: DEBIAN_FRONTEND: noninteractive 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/Submakefile b/docs/src/Submakefile index 71c3d7873d9..8645e61ccbc 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -545,6 +545,7 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ --doctype=manpage \ --backend=html5 \ + -a compat-mode \ -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ -a linkcss \ @@ -658,6 +659,7 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ --sourcemap \ + -a compat-mode \ -a xref-root=$(dir $<) \ -a "xref-exclude=^($(LANGUAGES_MATCH))/" \ -a "scriptdir=$(DOC_SRCDIR)/" \ @@ -715,9 +717,10 @@ objects/LinuxCNC_Manual_Pages.adoc: objects/var-PDF_MAN_ORDER $(MAN_SRCS) $(DOC_ $(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(CJK_TTFS) @$(ECHO) Formatting manual pages as PDF @rm -f $@ $@.raw - $(Q)asciidoctor-pdf \ + $(Q)timeout 900 asciidoctor-pdf \ -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ + -a compat-mode \ -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ -a source-highlighter=rouge \ @@ -725,7 +728,9 @@ $(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(CJK_T -a "lversion=$(shell cat ../VERSION)" \ -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ -d book \ - -o $@.raw $< || (X=$$?; rm -f $@.raw; exit $$X) + -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 \ @@ -827,6 +832,7 @@ $$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$ $$(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 \ + -a compat-mode \ -a xref-root=$2 \ -a "xref-exclude=$3" \ -a linkcss \ @@ -922,7 +928,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/$(*D)/%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 $@ @@ -966,6 +972,7 @@ $(DOC_DIR)/man/%: $(DOC_DIR)/src/man/%.adoc $(Q)asciidoctor --doctype=manpage \ --backend=manpage \ --destination-dir="$(dir $@)" \ + -a compat-mode \ -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ $< 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 2ada991e9b7..43b25a67c2b 100644 --- a/docs/src/man/man9/hm2_rpspi.9.adoc +++ b/docs/src/man/man9/hm2_rpspi.9.adoc @@ -142,7 +142,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/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 ed929e81add508f9e6c942db6d3a0ad071e50e04 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Sun, 24 May 2026 23:15:11 +0800 Subject: [PATCH 21/30] docs: wrap main PDF rule in timeout 900 to bound asciidoctor-pdf hangs trixie/bookworm package-indep hung 37 min on Build step despite the manpage PDF timeout added in dbc79d14f8. Hang is in main PDF rule (Master_*.pdf via asciidoctor-pdf), not the manpage book. Same 15 min cap and exit-code-124 message as the manpage rule, so any future asciidoctor-pdf hang fails fast with clear cause. --- docs/src/Submakefile | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 8645e61ccbc..2aff511e508 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -653,7 +653,7 @@ $(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: $(NOTOCJK_BOLD_TTC) $(DOC_SRCDIR)/otf2t $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(CJK_TTFS) $(ECHO) Building $@ @rm -f $@ $@.raw - $(Q)asciidoctor-pdf \ + $(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 \ @@ -668,7 +668,9 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -a toc -a numbered \ -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ -d book \ - -o $@.raw $< || (X=$$?; rm -f $@.raw; exit $$X) + -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 \ From 0ab4f194cbdf863e6a97771680c2c0edf69fb179 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 07:53:25 +0800 Subject: [PATCH 22/30] ci: skip dh_auto_test on indep build, hangs trixie/bookworm PDF builds finish at 15:37, then dh_auto_test enters at 15:37:31 and produces zero output for 2h25m before manual cancel. sid passes the same step in seconds. Indep package is doc-only with no real test targets, so dh_auto_test would no-op anyway, but trixie/bookworm make+asciidoctor seem to enter an autorestart loop on the 'Makefile: $(MAN_DEPS)' rule. Add nocheck to DEB_BUILD_OPTIONS to bypass entirely. --- .github/scripts/build-package-indep.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/scripts/build-package-indep.sh b/.github/scripts/build-package-indep.sh index 9bb6b0642f3..6f448357fa7 100755 --- a/.github/scripts/build-package-indep.sh +++ b/.github/scripts/build-package-indep.sh @@ -8,6 +8,6 @@ debian/update-dch-from-git scripts/get-version-from-git | sed -re 's/^v(.*)$/\1/' >| VERSION; cat VERSION git diff apt-get --yes build-dep --indep-only . -DEB_BUILD_OPTIONS="parallel=$(nproc)" +DEB_BUILD_OPTIONS="parallel=$(nproc) nocheck" export DEB_BUILD_OPTIONS debuild -us -uc --build=source,all From 385c57eec5ece6e7c2c564a6ff2e290857edf09b Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 08:32:33 +0800 Subject: [PATCH 23/30] docs: make manpages prereq of components_gen.adoc order-only Captured 36-min trixie hang log shows the loop: gen_complist regenerates components_gen.adoc -> .pot rebuilds -> po4a updates translated .adoc -> their .d files stale -> Makefile autorestart -> back to start. gen_complist re-fires each cycle because manpages mtime always advances. Order-only | manpages keeps the 'manpages must exist first' guarantee but drops the mtime-driven retrigger that was driving the loop on trixie/bookworm. sid converged fast enough that it escaped before timeout, trixie/bookworm did not. --- docs/src/Submakefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 2aff511e508..0d5b06c191e 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -250,7 +250,7 @@ endif # for that: gen_complist.py reads from $(DOC_DIR)/man/, so it only needs # manpages (the full gen_complist target also pulls in MAN_HTML_TARGETS # for link validation, which is too heavy a dep for the .pot path). -$(DOC_SRCDIR)/hal/components_gen.adoc: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc manpages +$(DOC_SRCDIR)/hal/components_gen.adoc: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc | 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 From d1ea806a38e720fc4eddbb367dc3ee904d4eaad5 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 11:54:55 +0800 Subject: [PATCH 24/30] docs: address bertho 2026-05-25 review Five items from BsAtHome review on PR #4053: 1. docs/src/source-highlight: removed. source-highlight tool retired by this PR; demo .adoc / .lang / .conf files have no remaining consumers. po4a.cfg loses the three [type: AsciiDoc_def] entries that pointed at them. Submakefile loses LOC_HL_DIR / LOC_LANG_MAP (defined but unused after the build rules moved to rouge). 2. configure.ac NotoSerifCJK probe: drop the /usr/share/fonts/.../ fallback list, trust fc-match alone. fontconfig already covers user-installed ~/.fonts when fc-cache has been run, and silently falling back to a Debian-only path on other distros was the portability concern bertho flagged. Error message names fc-match explicitly and mentions ~/.fonts + fc-cache so the user knows where to put a custom .ttc. 3. pdf-theme.yml DejaVu Sans Mono: drop absolute /usr/share/fonts/truetype/ paths. fonts now resolved at build time via fc-match into DOC_FONT_DIR (the same dir where the CJK fallback ttf already lives), exposed to asciidoctor-pdf through pdf-fontsdir. pdf-theme.yml stays path-free, theme file is portable across distros without further patching. 4. image_resolver.rb locale handling: the regex that detected the doc language from /src// now consumes a doc-languages attribute passed by Submakefile ($(LANGUAGES) from po4a.cfg), not a hardcoded alternation. Codes are matched literally as they appear on disk (zh_CN, sv, etc.). Adding a new locale only requires the po4a.cfg po4a_langs line; the resolver picks it up automatically. 5. blank lines before headers: restore the second blank line that commit 0375f0a collapsed when removing the legacy `:ini: ini` attribute blocks. The line was load-bearing for visual section separation in the source even though asciidoctor ignores it during parse. Affects 63 files, +212 / -60 lines, no rendered-output change. Drive-by: hardware-interface.adoc had three level-0 (=) headings. Asciidoctor only allows one per document; two repunctuated to == so the full pdfdocs+htmldocs build stays clean. --- docs/INSTALL.adoc | 1 + docs/help/asciidoc-markup_es.adoc | 2 + docs/man/images/Images_info.adoc | 4 +- docs/po4a.cfg | 3 - docs/src/Master_Documentation.adoc | 9 + docs/src/Submakefile | 37 ++- docs/src/code/building-linuxcnc.adoc | 1 + docs/src/config/ini-config.adoc | 1 + docs/src/config/python-hal-interface.adoc | 5 + docs/src/config/python-interface.adoc | 3 + docs/src/drivers/gm.adoc | 2 + docs/src/drivers/hal_gpio.adoc | 2 + docs/src/drivers/hal_pi_gpio.adoc | 2 + docs/src/drivers/hostmot2.adoc | 1 + docs/src/drivers/mb2hal.adoc | 2 + docs/src/drivers/mesa_modbus.adoc | 2 + docs/src/drivers/shuttle.adoc | 1 + docs/src/extensions/image_resolver.rb | 54 ++-- docs/src/gcode/o-code.adoc | 1 + docs/src/gcode/tool-compensation.adoc | 1 + .../getting-started/hardware-interface.adoc | 7 +- .../getting-started/updating-linuxcnc.adoc | 2 + docs/src/gui/axis.adoc | 2 + docs/src/gui/gladevcp-panels.adoc | 3 + docs/src/gui/gladevcp.adoc | 3 + docs/src/gui/gmoccapy.adoc | 20 ++ docs/src/gui/halui.adoc | 1 + docs/src/gui/qtdragon.adoc | 2 + docs/src/gui/qtvcp-code-snippets.adoc | 1 + docs/src/gui/qtvcp-custom-widgets.adoc | 1 + docs/src/gui/qtvcp-vcp-panels.adoc | 2 + docs/src/gui/qtvcp-vismach.adoc | 2 + docs/src/gui/qtvcp-widgets.adoc | 2 + docs/src/gui/qtvcp.adoc | 2 + docs/src/hal/comp.adoc | 1 + docs/src/hal/components.adoc | 2 + docs/src/hal/halmodule.adoc | 1 + docs/src/hal/halshow.adoc | 2 + docs/src/hal/intro.adoc | 2 + docs/src/hal/tutorial.adoc | 1 + docs/src/hal/twopass.adoc | 2 + docs/src/install/latency-test.adoc | 2 + docs/src/man/man1/emccalib.1.adoc | 1 + docs/src/man/man1/halstreamer.1.adoc | 2 + docs/src/man/man1/hy_gt_vfd.1.adoc | 2 + docs/src/man/man1/linuxcncrsh.1.adoc | 1 + docs/src/man/man1/mb2hal.1.adoc | 1 + docs/src/man/man1/melfagui.1.adoc | 1 + docs/src/man/man1/mesambccc.1.adoc | 2 + docs/src/man/man1/svd-ps_vfd.1.adoc | 1 + docs/src/man/man1/xhc-whb04b-6.1.adoc | 2 + docs/src/man/man3/hm2_pktuart.3.adoc | 1 + docs/src/man/man9/demux_generic.9.adoc | 1 + docs/src/man/man9/hm2_modbus.9.adoc | 1 + docs/src/man/man9/hm2_rpspi.9.adoc | 1 + docs/src/man/man9/hostmot2.9.adoc | 2 + docs/src/man/man9/kins.9.adoc | 2 + docs/src/man/man9/streamer.9.adoc | 2 + docs/src/pdf-theme.yml | 8 +- docs/src/plasma/qtplasmac.adoc | 2 + docs/src/remap/remap.adoc | 2 + 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 | 43 ---- docs/src/source-highlight/hal-test.hal | 23 -- docs/src/source-highlight/hal.lang | 28 --- docs/src/source-highlight/ini-demo.adoc | 230 ------------------ docs/src/source-highlight/ini-test.ini | 195 --------------- docs/src/source-highlight/ini.lang | 15 -- docs/src/source-highlight/ngc-demo.adoc | 114 --------- docs/src/source-highlight/ngc-test.ngc | 94 ------- docs/src/source-highlight/ngc.lang | 99 -------- docs/src/tooldatabase/tooldatabase.adoc | 1 + src/configure.ac | 39 ++- 75 files changed, 212 insertions(+), 1158 deletions(-) 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 diff --git a/docs/INSTALL.adoc b/docs/INSTALL.adoc index a4882640d3e..578edbdc484 100644 --- a/docs/INSTALL.adoc +++ b/docs/INSTALL.adoc @@ -56,6 +56,7 @@ no `scripts/linuxcnc`, just a `scripts/linuxcnc.in`. By running `configure` will also replace some default values for your system (folders, paths, etc). + === Configure script The *`configure`* shell script attempts to guess correct values for diff --git a/docs/help/asciidoc-markup_es.adoc b/docs/help/asciidoc-markup_es.adoc index c5f79cad6ba..68286887f62 100644 --- a/docs/help/asciidoc-markup_es.adoc +++ b/docs/help/asciidoc-markup_es.adoc @@ -55,6 +55,7 @@ https://linuxnc.org/someplace[descripcion del link] Uso: ocultar comentarios //// + = Bloque de listado para código G y salida por terminal <4 guiones comienzan un bloque + @@ -158,6 +159,7 @@ estilo de párrafo. Los estilos incluyen: NOTE TIP IMPORTANT WARNING CAUTION + = Tablas [options="header,width="80%"] diff --git a/docs/man/images/Images_info.adoc b/docs/man/images/Images_info.adoc index 38ef1ce8c64..c7c464c8aa9 100644 --- a/docs/man/images/Images_info.adoc +++ b/docs/man/images/Images_info.adoc @@ -23,6 +23,7 @@ Here an example: ]} ---- + .toggle2nist: ASCII art generated by asciiwave ---- ┐ ┏─────xxxxxxxxxxxx┐ ┏─────xxxxxxxxxxxx┐ @@ -42,6 +43,7 @@ is-on: └─────────────────┘ ---- + ## Diagrams ASCII art diagrams can be drawn e.g., with link:https://asciiflow.com/[asciiflow] @@ -54,4 +56,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/po4a.cfg b/docs/po4a.cfg index 807df091f26..7550a595cac 100644 --- a/docs/po4a.cfg +++ b/docs/po4a.cfg @@ -361,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/Master_Documentation.adoc b/docs/src/Master_Documentation.adoc index d0d7c1ff70a..5e658eff994 100644 --- a/docs/src/Master_Documentation.adoc +++ b/docs/src/Master_Documentation.adoc @@ -5,9 +5,11 @@ :revdate: 2021-10-28 = LinuxCNC V{lversion} + :leveloffset: 0 = Getting Started & Configuration + :leveloffset: 1 = Getting Started with LinuxCNC @@ -24,6 +26,7 @@ include::getting-started/updating-linuxcnc.adoc[] include::common/linux-faq.adoc[] + :leveloffset: 1 = General User Information @@ -76,6 +79,7 @@ include::config/stepper-diagnostics.adoc[] include::gui/filter-programs.adoc[] + :leveloffset: 1 = HAL (Hardware Abstraction Layer) @@ -203,6 +207,7 @@ include::tooldatabase/tooldatabase.adoc[] :leveloffset: 0 = Usage + :leveloffset: 1 = User Interfaces @@ -300,19 +305,23 @@ include::gui/vismach.adoc[] :leveloffset: 0 = Glossary, Copyright & History + :leveloffset: 1 = Overleaf include::common/overleaf.adoc[] + :leveloffset: 1 include::common/glossary.adoc[] + :leveloffset: 1 = Copyright :leveloffset: 2 include::common/gpld-copyright.adoc[] + :leveloffset: 1 = LinuxCNC History diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 0d5b06c191e..e21172a2997 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -32,9 +32,6 @@ 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 - # The following line determines for the Makefile what languages should be addressed. # Edit the file po4a.cfg in this source tree to adjust. LANGUAGES := $(strip $(shell sed -e's/#.*//' < $(DOC_DIR)/po4a.cfg | grep '^\[po4a_langs\]' | cut -d" " -f2-)) @@ -633,6 +630,15 @@ DOC_FONT_DIR = $(DOC_SRCDIR)/.fonts # 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 @@ -650,7 +656,27 @@ $(DOC_FONT_DIR)/NotoSerifCJKsc-Bold.ttf: $(NOTOCJK_BOLD_TTC) $(DOC_SRCDIR)/otf2t $(ECHO) "Converting CJK font to TTF: $(notdir $@)" $(Q)python3 $(DOC_SRCDIR)/otf2ttf.py --ttc-index 2 --text-from $(DOC_SRCDIR) $< $@.tmp && mv $@.tmp $@ -$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(CJK_TTFS) +# 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 $@ + +$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(DOC_FONTS) $(ECHO) Building $@ @rm -f $@ $@.raw $(Q)timeout 900 asciidoctor-pdf \ @@ -660,6 +686,7 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -r $(realpath $(DOC_SRCDIR))/extensions/rouge_ngc.rb \ --sourcemap \ -a compat-mode \ + -a "doc-languages=$(LANGUAGES)" \ -a xref-root=$(dir $<) \ -a "xref-exclude=^($(LANGUAGES_MATCH))/" \ -a "scriptdir=$(DOC_SRCDIR)/" \ @@ -716,7 +743,7 @@ objects/LinuxCNC_Manual_Pages.adoc: objects/var-PDF_MAN_ORDER $(MAN_SRCS) $(DOC_ } > $@.tmp $(Q)mv -f $@.tmp $@ -$(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(CJK_TTFS) +$(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 \ diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc index 1bfe6c792be..e14139853d6 100644 --- a/docs/src/code/building-linuxcnc.adoc +++ b/docs/src/code/building-linuxcnc.adoc @@ -541,6 +541,7 @@ Virtual Environment, and set up the linuxcnc environment: (venv) ~ $ ~/src/linuxcnc $ scripts/linuxcnc ----- + == Options for checking out the git repo The <> instructions at the top of this diff --git a/docs/src/config/ini-config.adoc b/docs/src/config/ini-config.adoc index e06497d266e..537b715dd72 100644 --- a/docs/src/config/ini-config.adoc +++ b/docs/src/config/ini-config.adoc @@ -975,6 +975,7 @@ LinuxCNC will not know your joint travel limits when using `NO_FORCE_HOMING = 1` * `NO_PROBE_JOG_ERROR = 0` - Allow to bypass probe tripped check when you jog manually. * `NO_PROBE_HOME_ERROR = 0` - Allow to bypass probe tripped check when homing is in progress. + [[sub:ini:sec:kins]] === [KINS] Section(((INI File,Sections,KINS Section))) diff --git a/docs/src/config/python-hal-interface.adoc b/docs/src/config/python-hal-interface.adoc index b9d09b0b963..14ec33aa991 100644 --- a/docs/src/config/python-hal-interface.adoc +++ b/docs/src/config/python-hal-interface.adoc @@ -7,8 +7,10 @@ This documentation describes the `hal` python module, which provides a Python API for creating and accessing HAL pins and signals. + == Basic usage + [source,python] ---- #!/usr/bin/env python3 @@ -103,6 +105,7 @@ value = hal.get_value("iocontrol.0.emc-enable-in") *get_info_pins()* :: Returns a list of dicts of all system pins. + [source,python] ---- listOfDicts = hal.get_info_pins() @@ -115,6 +118,7 @@ pinDirection1 = listOfDicts[0].get('DIRECTION') *get_info_signals()* :: Returns a list of dicts of all system signals. + [source,python] ---- listOfDicts = hal.get_info_signals() @@ -126,6 +130,7 @@ driverPin1 = listOfDicts[0].get('DRIVER') *get_info_params()* :: Returns a list of dicts of all system parameters. + [source,python] ---- listOfDicts = hal.get_info_params() diff --git a/docs/src/config/python-interface.adoc b/docs/src/config/python-interface.adoc index 4aacf2a71c1..17b55d9a11b 100644 --- a/docs/src/config/python-interface.adoc +++ b/docs/src/config/python-interface.adoc @@ -402,6 +402,7 @@ print(s.toolinfo(toolno)) ': 0, 'xoffset': 0.0, 'yoffset': 0.0, 'zoffset': 0.18, 'aoffset': 0.0, 'boffset': 0.0, 'coffset': 0.0, 'uoffset': 0.0, 'voffset': 0.0, 'woffset': 0.0, 'comment': 'Tool_18 28Jan23:18.53.25'} ---- + *velocity*:: '(returns float)' - This property is defined, but it does not have a useful interpretation. @@ -421,6 +422,7 @@ these items (such as backlash) are not the properties of an axis. *min_position_limit*:: '(returns float)' - minimum limit (soft limit) for axis motion, in machine units.configuration parameter, reflects `[JOINT___n__]MIN_LIMIT`. + *velocity*:: '(returns float)' - current velocity. @@ -507,6 +509,7 @@ For each joint, the following dictionary keys are available: (joint units are the same as machine units, unless set otherwise by the configuration parameter `[JOINT___n__]UNITS`) + *velocity*:: '(returns float)' - current velocity. diff --git a/docs/src/drivers/gm.adoc b/docs/src/drivers/gm.adoc index 0e5c6387a7c..a2ffc520185 100644 --- a/docs/src/drivers/gm.adoc +++ b/docs/src/drivers/gm.adoc @@ -45,6 +45,7 @@ The following connectors can be found on the GM6-PCI card: .GM6-PCI card connectors and LEDs(((pci-card connectors))) image::images/GM_PCIpinout.png["GM6-PCI card connectors and LEDs",align="center",scaledwidth="70%"] + == I/O connectors .Pin numbering of GPIO connectors(((pin-numbering-gpio))) @@ -141,6 +142,7 @@ have to be connected as the following block diagram shows: .Servo axis interfaces(((axis-interface))) image::images/GM_AxisInterface.png["Servo axis interfaces",align="center",scaledwidth="100%"] + === Encoder The GM6-PCI motion control card has six encoder modules. diff --git a/docs/src/drivers/hal_gpio.adoc b/docs/src/drivers/hal_gpio.adoc index 7c0b900a030..374802f36fc 100644 --- a/docs/src/drivers/hal_gpio.adoc +++ b/docs/src/drivers/hal_gpio.adoc @@ -82,10 +82,12 @@ The version of libgpiod-dev installed can be determined by the command `gpioinfo * hal_gpio.NAME-in-not - HAL_OUT An inverted version of the above, for convenience * hal_gpio.NAME-out - HAL_IN use this pin to transfer a HAL bit value to a physical output + == Parameters * hal_gpio.reset_ns - HAL_RW - "setp" this parameter to control the pulse length of pins added to the "reset" list. The value will be limited between 0 and thread-period / 4. + == Functions * 'hal_gpio.read' - Add this to the base thread to update the HAL pin values to match the physical input values. diff --git a/docs/src/drivers/hal_pi_gpio.adoc b/docs/src/drivers/hal_pi_gpio.adoc index 7a64ffc8d1a..4ee08571f4f 100644 --- a/docs/src/drivers/hal_pi_gpio.adoc +++ b/docs/src/drivers/hal_pi_gpio.adoc @@ -81,6 +81,7 @@ For unknown reasons the driver also creates HAL _pins_ to indicate timing: * hal_pi_gpio.read.time * hal_pi_gpio.write.time + == Functions * `hal_pi_gpio.read` - Add this to the base thread to update the HAL pin values to match the physical input values. @@ -88,6 +89,7 @@ For unknown reasons the driver also creates HAL _pins_ to indicate timing: Typically the 'read' function will be early in the call list, before any encoder counters and the 'write' function will be later in the call list, after stepgen.make-pulses. + == Pin Numbering The GPIO connector and the pinout has been consistent since around 2015. diff --git a/docs/src/drivers/hostmot2.adoc b/docs/src/drivers/hostmot2.adoc index c0b750740cd..396c8224e9b 100644 --- a/docs/src/drivers/hostmot2.adoc +++ b/docs/src/drivers/hostmot2.adoc @@ -343,6 +343,7 @@ So far, all firmware is available in all gate sizes.) |SVST8_8IM2 | 8 (+IM) | 8 | 8 | 0 |=== + 4I65 (3-port PC/104) Default Configurations (The 4I65 has 200k gates.) [width="90%",options="header"] diff --git a/docs/src/drivers/mb2hal.adoc b/docs/src/drivers/mb2hal.adoc index b63aa96bb81..2363cfc1487 100644 --- a/docs/src/drivers/mb2hal.adoc +++ b/docs/src/drivers/mb2hal.adoc @@ -36,6 +36,7 @@ Set `HAL_MODULE_NAME=mymodule` (default `HAL_MODULE_NAME=mb2hal`) .. Default component name: `loadusr -W mb2hal config=config_file.ini` .. Custom component name: `loadusr -Wn mymodule mb2hal config=config_file.ini` + == Options === Init Section @@ -60,6 +61,7 @@ It affects ALL transactions. Use "0.0" for normal activity. m|TOTAL_TRANSACTIONS | Integer | Yes | The number of total Modbus transactions. There is no maximum. |=== + === Transaction Sections One transaction section is required per transaction, starting at `[TRANSACTION_00]` and counting up sequentially. diff --git a/docs/src/drivers/mesa_modbus.adoc b/docs/src/drivers/mesa_modbus.adoc index 9a8747538a7..10073ccaa3e 100644 --- a/docs/src/drivers/mesa_modbus.adoc +++ b/docs/src/drivers/mesa_modbus.adoc @@ -122,6 +122,7 @@ multiplied by the "scale" pin value and presented as a floating point value on a HAL pin with the suffix "scaled". For example mymodule.0.counts-0-scaled. + In addition to the pins configured in the definition file, each module will create the following pins for each instance of the driver: @@ -177,6 +178,7 @@ All modules created by the framework require a hostmot2 pktuart instance to be given to the "ports" modparam on the "loadrt" file. See the example in the [Quick Start] section. + == Configuration File == A Mesa_Modbus configuration file is actually a C header file and must diff --git a/docs/src/drivers/shuttle.adoc b/docs/src/drivers/shuttle.adoc index ec47c111211..138cae8f524 100644 --- a/docs/src/drivers/shuttle.adoc +++ b/docs/src/drivers/shuttle.adoc @@ -33,6 +33,7 @@ Any user interaction with the Shuttle device will generate an event, informing t So if you (for example) push one of the buttons at startup, the jog-wheel will work fine and notice the first click. ==== + == Setup The shuttle driver needs read permission to the /dev/hidraw* diff --git a/docs/src/extensions/image_resolver.rb b/docs/src/extensions/image_resolver.rb index badcf7b9cf3..1470e5803c0 100644 --- a/docs/src/extensions/image_resolver.rb +++ b/docs/src/extensions/image_resolver.rb @@ -28,8 +28,27 @@ class ImageResolver < Asciidoctor::Extensions::Treeprocessor INLINE_IMAGE_RE = /(?/ tree. + DEFAULT_LANGS = %w[ar de es fr nb ru sv ta tr uk zh_CN].freeze + + # Per-document regex cache keyed by the language list string. The + # treeprocessor itself is frozen by Asciidoctor after registration, + # so we cannot store state on the instance directly; use a thread- + # local map instead (safe because asciidoctor invocations are + # single-threaded per process). + def lang_re_for(document) + attr = document.attr('doc-languages') + key = attr && !attr.empty? ? attr : DEFAULT_LANGS.join(' ') + cache = (Thread.current[:lcnc_lang_re_cache] ||= {}) + cache[key] ||= begin + langs = key.split(/\s+/) + %r{/src/(#{langs.sort_by { |l| -l.length }.map { |l| Regexp.escape(l) }.join('|')})/} + end + end def process(document) # PDF embedding needs absolute paths so prawn-svg / image reading @@ -69,14 +88,15 @@ def rewrite(node) src = node.file || node.document.attr('docfile') return unless src base_dir = File.dirname(File.expand_path(src)) - lang = doc_language(src) + lang_re = lang_re_for(node.document) + lang = (m = lang_re.match(src.to_s)) ? m[1] : 'en' pdf = node.document.backend == 'pdf' # Try a language-specific variant of the filename first. if lang != 'en' swapped = swap_lang(target, lang) if swapped != target - abs = resolve_candidate(File.expand_path(swapped, base_dir)) + abs = resolve_candidate(File.expand_path(swapped, base_dir), lang_re) if abs node.set_attr('target', pdf ? abs : swapped) apply_default_width(node) if pdf @@ -88,19 +108,12 @@ def rewrite(node) # No translated variant available (or English doc); the original # target stays for HTML, only PDF needs the absolute rewrite. return unless pdf - abs = resolve_candidate(File.expand_path(target, base_dir)) + abs = resolve_candidate(File.expand_path(target, base_dir), lang_re) return unless abs node.set_attr('target', abs) apply_default_width(node) end - # Returns the document language inferred from the source file path - # (one of LANG_RE's capture groups), or 'en' for the canonical tree. - def doc_language(src) - m = LANG_RE.match(src.to_s) - m ? m[1] : 'en' - end - # Rewrite an `*_en.` filename to `*_.`. The check # is anchored to the basename so paths that happen to contain `_en` # earlier are not touched. @@ -113,7 +126,7 @@ def swap_lang(target, lang) # 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) + def resolve_candidate(path, lang_re) probe = ->(p) { return p if File.file?(p) r = resolve_extension(p) @@ -122,19 +135,20 @@ def resolve_candidate(path) } r = probe.call(path) return r if r - fallback = path.sub(LANG_RE, '/src/') + 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 = doc_language(block.file) + lang_re = lang_re_for(block.document) + lang = (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, pdf) { changed = true } } + new_lines = block.lines.map { |ln| rewrite_inline(ln, base_dir, lang, lang_re, pdf) { changed = true } } block.lines = new_lines if changed end @@ -143,13 +157,13 @@ def rewrite_inline_in_block(block) old = block.instance_variable_get(:@text) if old.is_a?(String) && !old.empty? changed = false - new_text = rewrite_inline(old, base_dir, lang, pdf) { changed = true } + 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, pdf) + 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) @@ -159,7 +173,7 @@ def rewrite_inline(text, base_dir, lang, pdf) if lang != 'en' swapped = swap_lang(target, lang) if swapped != target - abs = resolve_candidate(File.expand_path(swapped, base_dir)) + abs = resolve_candidate(File.expand_path(swapped, base_dir), lang_re) if abs yield if block_given? next "image:#{pdf ? abs : swapped}[" @@ -168,7 +182,7 @@ def rewrite_inline(text, base_dir, lang, pdf) end next full unless pdf - candidate = resolve_candidate(File.expand_path(target, base_dir)) + candidate = resolve_candidate(File.expand_path(target, base_dir), lang_re) if candidate yield if block_given? "image:#{candidate}[" diff --git a/docs/src/gcode/o-code.adoc b/docs/src/gcode/o-code.adoc index b417b3f77ae..8e6e278ef3b 100644 --- a/docs/src/gcode/o-code.adoc +++ b/docs/src/gcode/o-code.adoc @@ -83,6 +83,7 @@ The behavior is undefined if: * Other words are used on a line with an o-word. * Comments are used on a line with an o-word. + [[ocode:subroutines]] == Subroutines(((Subroutines))) diff --git a/docs/src/gcode/tool-compensation.adoc b/docs/src/gcode/tool-compensation.adoc index 3efb1a14b9a..1a64946d36a 100644 --- a/docs/src/gcode/tool-compensation.adoc +++ b/docs/src/gcode/tool-compensation.adoc @@ -232,6 +232,7 @@ With this type of tool changer the tool will always be in a different pocket aft When a tool is changed LinuxCNC rewrites the pocket number to keep track of where the tools are. T can be any number but P must be a number that makes sense for the machine. + == Tool Length Compensation (((Tool Length Compensation))) diff --git a/docs/src/getting-started/hardware-interface.adoc b/docs/src/getting-started/hardware-interface.adoc index 2872495450f..017e0ca6249 100644 --- a/docs/src/getting-started/hardware-interface.adoc +++ b/docs/src/getting-started/hardware-interface.adoc @@ -4,14 +4,14 @@ [[cha:hardware-interface]] = Hardware Interface(((Hardware Interface))) -= Hardware to run the LinuxCNC software +== Hardware to run the LinuxCNC software A computer is required to run LinuxCNC itself. See <> 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: @@ -43,6 +43,7 @@ __Disadvantages:__ - Limited inputs/outputs - Some PCI/PCIe parallel port cards do not work well or do not properly support the EPP mode (EPP mode is required for parallel port interface to Mesa / PICO cards). + == Parallel Port FPGA Communication Realtime (time critical) tasks such as step generation are done in hardware (not on the computer) @@ -54,6 +55,7 @@ Website: https://mesanet.com/ Store: https://store.mesanet.com/ === Pico Systems via Parallel Port https://pico-systems.com/univstep.html + == Ethernet === Mesa Ethernet Mesa cards with a Field-programmable gate array (FPGA), interfaced to LinuxCNC computer via Ethernet. Time critical (realtime) tasks are performed on the FPGA card. @@ -132,6 +134,7 @@ SPI = Serial Peripheral Interface. SPI interfaces can be found on single board c === Remora SPI Realtime requirements are offloaded onto a controller board. https://remora-docs.readthedocs.io + === LinuxCNC-RIO RealtimeIO for LinuxCNC based on an FPGA diff --git a/docs/src/getting-started/updating-linuxcnc.adoc b/docs/src/getting-started/updating-linuxcnc.adoc index 6f61277ae8c..006f8f233ea 100644 --- a/docs/src/getting-started/updating-linuxcnc.adoc +++ b/docs/src/getting-started/updating-linuxcnc.adoc @@ -161,6 +161,7 @@ package manager with this command: sudo dpkg -i linuxcnc_2.9.8.deb ---- + == Updating Configuration Files for 2.9 === Stricter handling of pluggable interpreters @@ -180,6 +181,7 @@ LinuxCNC to refuse to start up. Fix this condition by deleting the `[TASK]INTERPRETER` setting from your INI file, so that LinuxCNC will use the default G-code interpreter. + === Canterp If you just run regular G-code and you don't use the `canterp` pluggable diff --git a/docs/src/gui/axis.adoc b/docs/src/gui/axis.adoc index e9e846de302..81c50d8e6d5 100644 --- a/docs/src/gui/axis.adoc +++ b/docs/src/gui/axis.adoc @@ -518,12 +518,14 @@ By pressing the 'Tool Touch Off' button the tool length and offsets of the currently loaded tool will be changed so that the current tool tip position matches the entered coordinate. + .Tool Touch Off Window image::images/tooltouchoff.png["Tool Touch Off Window",align="center"] See also the 'Tool touch off to workpiece' and 'Tool touch off to fixture' options in the Machine menu. + .Override Limits By pressing Override Limits, the machine will temporarily be allowed to jog off of a physical limit switch. This check box is only available diff --git a/docs/src/gui/gladevcp-panels.adoc b/docs/src/gui/gladevcp-panels.adoc index 18e117dd3b2..9ed777dc48b 100644 --- a/docs/src/gui/gladevcp-panels.adoc +++ b/docs/src/gui/gladevcp-panels.adoc @@ -13,9 +13,11 @@ There are several *builtin panels* available. In a terminal type `gladevcp` to see a list. + === GTK Verser Probe A GTK based version of the third party Verser probe. + image::images/gtk_verser_probe.png["GTK Verser Probe",align="center"] This is a version from 2015 by Serguei Glavatski which has **less functionality** than the current, but it **takes up less space on the screen** (no DRO e.g.). @@ -50,6 +52,7 @@ SUBROUTINE_PATH = ./macros:/usr/share/linuxcnc/nc_files/gtk_probe/ # SUBROUTINE_PATH = ./macros:~/linuxcnc/nc_files/probe/gtk_probe/ ---- + **Example using dbounce with a Mesa card (HAL file):** [source,hal] diff --git a/docs/src/gui/gladevcp.adoc b/docs/src/gui/gladevcp.adoc index c6959ce7b69..23e9be0df93 100644 --- a/docs/src/gui/gladevcp.adoc +++ b/docs/src/gui/gladevcp.adoc @@ -2277,6 +2277,7 @@ More information can be found here: <>. @@ -309,6 +314,7 @@ All you have to take care of, is that you include for every tab or side panel th ** *box_dro_side* (will introduce your glade file right of the DRO *(8)*) ** *ntb_setup* (as tab on the setup page *(9)*) + [NOTE] See also the included sample INI files to see the differences. @@ -345,6 +351,7 @@ will hide the chosen box. .Embedded tab locations image::images/gmoccapy_embedded_tabs_small.png[align="left",link="images/gmoccapy_embedded_tabs.png"] + [NOTE] If you make any HAL connections to your custom glade panel, you need to do that in the HAL file specified in the EMBED_TAB_COMMAND line, otherwise you may get an error that the HAL pin does not exist -- this is because of race conditions loading the HAL files. @@ -401,6 +408,7 @@ MESSAGE_TYPE = okdialog MESSAGE_PINNAME = okdialog ---- + [NOTE] Currently the formatting doesn't work. @@ -518,6 +526,7 @@ If `LOG_FILE` is not set, logging happens to `$HOME/.log`. GMOCCAPY exports several HAL pins to be able to react to hardware devices. The goal is to get a GUI that may be operated in a tool shop, completely/mostly without mouse or keyboard. + [NOTE] ==== You will have to do all connections to GMOCCAPY pins in your postgui.hal file. @@ -539,6 +548,7 @@ The screen has two main button lists, one on the right side an one on the bottom The right handed buttons will not change during operation, but the bottom button list will change very often. The buttons are count from up to down and from left to right beginning with 0. + [NOTE] The pin names have changed in GMOCCAPY 2 to order them in a better way. @@ -636,6 +646,7 @@ image:images/gmoccapy_sim_hardware_button_mid.png[align="left",link="images/gmoc All sliders from GMOCCAPY can be connected to hardware encoders or hardware potentiometers. + [NOTE] For GMOCCAPY 3 some HAL pin names have changed when new controls have been implemented. Max velocity does not exist any more, it was replaced by rapid override due to the demand of many users. @@ -725,6 +736,7 @@ value to set = 45 % + All axes given in the INI file have a jog-plus and a jog-minus pin, so hardware momentary switches can be used to jog the axes. + [NOTE] Naming of these HAL pins have changed in GMOCCAPY 2. @@ -904,6 +916,7 @@ net tool-prep-number gmoccapy.toolchange-number <= iocontrol.0.tool-prep-number net tool-prep-loop iocontrol.0.tool-prepare <= iocontrol.0.tool-prepared ---- + [NOTE] Please take care, that this connections have to be done in the postgui HAL file. @@ -917,6 +930,7 @@ image::images/gmoccapy_tool_info.png["Tool information",align="left"] - *gmoccapy.tooloffset-x* _(float IN)_ - *gmoccapy.tooloffset-z* _(float IN)_ + [NOTE] The tooloffset-x line is not needed on a mill, and will not be displayed on a mill with trivial kinematics. @@ -961,6 +975,7 @@ image::images/sketch_auto_tool_measurement.png[align="left"] With the first given tool change the tool will be measured and the offset will be set automatically to fit the block height. The advantage of the GMOCCAPY way is, that you do not need a reference tool. + [NOTE] ==== Your program must contain a tool change at the beginning! @@ -1142,6 +1157,7 @@ This settings will have influence on the jog velocities. * _Turtle jog factor_ - Sets the scale to apply for turtle jog mode (button pressed, showing the turtle). If you set a factor of 20, the turtle max. jog velocity will be 1/20 of the max. velocity of the machine. + [NOTE] This button can be controlled using the <>. @@ -1160,6 +1176,7 @@ The foreground color of the DRO can be selected with: * _Homed Color_ = green * _Unhomed Color_ = red + [NOTE] You can change through the DRO modes (absolute, relative, distance to go) by clicking the number on the DRO! If you click on the left side letter of the DRO a popup window will allow you to set the value of the axes, @@ -1268,9 +1285,11 @@ The default setting is: * _Show keyboard on EDIT_ = True * _Show keyboard on load file_ = False + [NOTE] If this section is not sensitive, you have not installed a virtual keyboard, supported ones are _onboard_ and _matchbox-keyboard_. + [NOTE] ==== If the keyboard layout is not correct, i.e. clicking Y gives Z, than the layout has not been set properly, related to your locale settings. @@ -1440,6 +1459,7 @@ image::images/gmoccapy_settings_advanced.png["Advanced settings",align="left"] Please check <> + [NOTE] If this part is not sensitive, you do not have a valid INI file configuration to use tool measurement. diff --git a/docs/src/gui/halui.adoc b/docs/src/gui/halui.adoc index f6c5f808871..9899e5fb414 100644 --- a/docs/src/gui/halui.adoc +++ b/docs/src/gui/halui.adoc @@ -51,6 +51,7 @@ to a maximum of 64 commands. These pins can be connected like any HAL pins. A common method is to use buttons provided by virtual control panels like shown in the example <>. + [[code:Example-HAL-file-connections]] .Example for MDI_COMMAND connections ==== diff --git a/docs/src/gui/qtdragon.adoc b/docs/src/gui/qtdragon.adoc index b8ca2a25852..3b0db38d7a7 100644 --- a/docs/src/gui/qtdragon.adoc +++ b/docs/src/gui/qtdragon.adoc @@ -1028,6 +1028,7 @@ In the lib folder copy 'touchoff_subprogram.py' + If these files are found they will be used instead of the originals. + You can modify the files to change behaviour. + + [[sub:touch-plate]] == Touch plate @@ -1750,6 +1751,7 @@ To have the manual spindle buttons also incrementally increase/decrease speed: } ---- + === Qt Designer and Python code All aspects of the GUI are fully customization through Qt Designer and/or Python code. + diff --git a/docs/src/gui/qtvcp-code-snippets.adoc b/docs/src/gui/qtvcp-code-snippets.adoc index 773682c78b9..814d71e0627 100644 --- a/docs/src/gui/qtvcp-code-snippets.adoc +++ b/docs/src/gui/qtvcp-code-snippets.adoc @@ -946,6 +946,7 @@ The users can recall any recorded messages. There are several options: + *`STATUS.TEMPORARY_MESSAGE`*:: Show the message for a short time only. *`STATUS.OPERATOR_ERROR`*:: *`STATUS.OPERATOR_TEXT`*:: diff --git a/docs/src/gui/qtvcp-custom-widgets.adoc b/docs/src/gui/qtvcp-custom-widgets.adoc index 218ad42e484..4b2520a3e66 100644 --- a/docs/src/gui/qtvcp-custom-widgets.adoc +++ b/docs/src/gui/qtvcp-custom-widgets.adoc @@ -837,6 +837,7 @@ class ActionButtonPlugin(QPyDesignerCustomWidgetPlugin): def includeFile(self): return "qtvcp.widgets.action_button" + class ActionButtonDialog(QtWidgets.QDialog): def __init__(self, widget, parent = None): diff --git a/docs/src/gui/qtvcp-vcp-panels.adoc b/docs/src/gui/qtvcp-vcp-panels.adoc index e79fcdb665d..1f1795cd084 100644 --- a/docs/src/gui/qtvcp-vcp-panels.adoc +++ b/docs/src/gui/qtvcp-vcp-panels.adoc @@ -290,6 +290,7 @@ Options: .QtVCP `tool_dialog` - Manual Tool Change Dialog image::images/qtvcp_toolChange.png["QtVCP tool_dialog - Manual Tool Change Dialog",align="center"] + [[sub:qtvcp:panels:vismach]] == `vismach` 3D Simulation Panels These panels are prebuilt simulation of common machine types. @@ -370,6 +371,7 @@ loadusr qtvcp vismach_fanuc_200f .QtVCP `vismach_fanuc_200f` - 6 Joint Robotic Arm image::images/qtvismach_fanuc_200f.png["QtVCP vismach_fanuc_200f - 6 Joint Robotic Arm",align="left"] + [[sec:qtvcp:panels:custom]] == Custom Virtual Control Panels diff --git a/docs/src/gui/qtvcp-vismach.adoc b/docs/src/gui/qtvcp-vismach.adoc index 34fceb35eea..472cbc817db 100644 --- a/docs/src/gui/qtvcp-vismach.adoc +++ b/docs/src/gui/qtvcp-vismach.adoc @@ -99,6 +99,7 @@ The same is applicable for any design of machine: look at the machine arm example and you will see that it starts with the tip and adds to the larger part of the arm, then it finally groups with the base. + [[sec:qtvcp:vismach:start]] == Start the script @@ -524,6 +525,7 @@ Usually this file is imported by QtVCP and the `window()` object is instantiated `_rotation_vectors_` or `_lat, lon_`;; Can be used to set the original viewpoint. It is advisable to do as the default initial viewpoint is rather unhelpful from immediately overhead. + == Tips Create an axes origin marker to be able to see parts relative to it, for construction purposes. diff --git a/docs/src/gui/qtvcp-widgets.adoc b/docs/src/gui/qtvcp-widgets.adoc index e220c7897b2..7a77946e41d 100644 --- a/docs/src/gui/qtvcp-widgets.adoc +++ b/docs/src/gui/qtvcp-widgets.adoc @@ -167,6 +167,7 @@ Disabled widgets typically have a different color and do not respond to actions. It is based on PyQt's `QGridLayout`. + === 'HalBar' - HAL Bar Level Indicator .QtVCP `HalBar`: Panel demonstrating the HAL Bar Level Indicator @@ -691,6 +692,7 @@ If it is not as you like, modify its existing position and re-record. [[sub:qtvcp:widgets:axistoolbutton]] === `AxisToolButton` - Select and Set Axis Widget + //TODO AxisToolButton widget capture/example This allows one to *select and set an axis*. diff --git a/docs/src/gui/qtvcp.adoc b/docs/src/gui/qtvcp.adoc index fc0af0752a3..62c3f3c1031 100644 --- a/docs/src/gui/qtvcp.adoc +++ b/docs/src/gui/qtvcp.adoc @@ -367,6 +367,7 @@ self.on_keycall_F11_super = self.on_keycall_F11 # to point to our new function (of the same name) defined in this file. self.on_keycall_F11 = types.MethodType(on_keycall_F11, self) + # add a new pin to the screen: # pin callback to print the state @@ -478,6 +479,7 @@ loadusr -Wn my_panel qtvcp my_panel.ui # <1> # add components to thread addf classicladder.0.refresh thread1 + # connect pins net bit-input1 test_panel.checkbox_1 classicladder.0.in-00 net bit-hide test_panel.checkbox_4 classicladder.0.hide_gui diff --git a/docs/src/hal/comp.adoc b/docs/src/hal/comp.adoc index 487abfb5ac9..d382a70f475 100644 --- a/docs/src/hal/comp.adoc +++ b/docs/src/hal/comp.adoc @@ -51,6 +51,7 @@ sudo apt install linuxcnc-uspace-dev Another method is using the Synaptic package manager, from the Applications menu, to install the `linuxcnc-dev` or `linuxcnc-uspace-dev` packages. + == Compiling === Inside the source tree diff --git a/docs/src/hal/components.adoc b/docs/src/hal/components.adoc index f4c01f17366..77805fc768d 100644 --- a/docs/src/hal/components.adoc +++ b/docs/src/hal/components.adoc @@ -27,6 +27,7 @@ then try to explicitly specify the section, as in `man _section-no_ axis`, with See also the 'Man Pages' section of the link:../index.html[docs main page] or the link:../man/[directory listing]. To search in the man pages, use the UNIX tool `apropos`. + === User Interfaces (non-realtime) ==== Machine Control @@ -163,6 +164,7 @@ To search in the man pages, use the UNIX tool `apropos`. | link:../man/man1/stepconf.1.html[stepconf] |Configuration wizard for parallel-port based machines || | link:../man/man1/update_ini.1.html[update_ini] |Converts 2.7 format INI files to 2.8 format || + | link:../man/man1/debuglevel.1.html[debuglevel] |Sets the debug level for the non-realtime part of LinuxCNC || | link:../man/man1/emccalib.1.html[emccalib] |Adjust ini tuning variables on the fly with save option || | link:../man/man1/hal_input.1.html[hal_input] |Control HAL pins with any Linux input device, including USB HID devices || diff --git a/docs/src/hal/halmodule.adoc b/docs/src/hal/halmodule.adoc index 3d19d77520a..7dfd229334b 100644 --- a/docs/src/hal/halmodule.adoc +++ b/docs/src/hal/halmodule.adoc @@ -165,6 +165,7 @@ writing files) must be done to complete the shutdown process. See <> for an overview of available functions. + == Constants Use these to specify details rather then the value they hold. diff --git a/docs/src/hal/halshow.adoc b/docs/src/hal/halshow.adoc index 53d5e30456e..4e534084642 100644 --- a/docs/src/hal/halshow.adoc +++ b/docs/src/hal/halshow.adoc @@ -47,6 +47,7 @@ $ halshow --fformat "%.5f" ./my.halshow For more information regarding the format, please refer to https://www.tcl.tk/man/tcl/TclCmd/format.html[the Tcl format man page]. + [[cap:halshow-layout]] .Halshow Layout image::images/halshow-layout.png["Halshow Layout",align="center"] @@ -85,6 +86,7 @@ Under _Tree View_ you will find: _Expand All_, _Collapse All_; _Expand Pins_, _Expand Parameters_, _Expand Signals_; and _Reload tree view_. _Reload tree view_ is useful when new components are loaded during runtime and should be displayed. + === HAL Show Area [[fig:halshow-show-tab]] diff --git a/docs/src/hal/intro.adoc b/docs/src/hal/intro.adoc index ed2150fde8a..7e611c72e9b 100644 --- a/docs/src/hal/intro.adoc +++ b/docs/src/hal/intro.adoc @@ -28,6 +28,7 @@ An Internet search, for example, found an astronomical application to control te Motors move the telescope into the right position, and it needs to know how to map motor activity with the effect of that positioning with the real world. Such a synchronisation of motor positions with real-world positions is reminiscent of what CNC machines need to do, or space craft. + Any machine controller needs to know: * about its internal state and how this maps to the environment (machine coordinates, state of switches/regulators), @@ -47,6 +48,7 @@ The HAL layer consists of parts (referred to as "components") that . adjust the planning for the next moves to complete a G-code instruction. - as non-realtime "user-space" components that run a "main loop" just like any other software, and may be interrupted or delayed when the rest of the system is busy or overloaded. + Taken together, HAL allows . to program for a machine that the programmer does not know directly, diff --git a/docs/src/hal/tutorial.adoc b/docs/src/hal/tutorial.adoc index f9b0970d246..cacd61d7c55 100644 --- a/docs/src/hal/tutorial.adoc +++ b/docs/src/hal/tutorial.adoc @@ -730,6 +730,7 @@ generator is cranking out step pulses, varying from 10 kHz forward to see how to bring those internal signals out to run motors in the real world, but first we want to look at them and see what is happening. + [[sec:tutorial-halmeter]] == Halmeter diff --git a/docs/src/hal/twopass.adoc b/docs/src/hal/twopass.adoc index 1ea2eb513a6..53a7e8104aa 100644 --- a/docs/src/hal/twopass.adoc +++ b/docs/src/hal/twopass.adoc @@ -20,6 +20,7 @@ For example, if you use a two-input AND gate component (and2) in three different 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`. @@ -182,6 +183,7 @@ as that would eliminate the benefits of TWOPASS processing. The LinuxCNC commands that create signals (`net`) and commands that establish execution order (`addf`) should not be placed in excluded files. This is especially true for addf commands since their ordering may be important. + == Examples Examples of TWOPASS usage for a simulator are included in the directories: diff --git a/docs/src/install/latency-test.adoc b/docs/src/install/latency-test.adoc index 0c401ea399d..e0f23e39cee 100644 --- a/docs/src/install/latency-test.adoc +++ b/docs/src/install/latency-test.adoc @@ -33,6 +33,7 @@ However, software step pulses also have some disadvantages: - jitter in the generated pulses - loads the CPU + [[sec:latency-tests]] == Latency Tests @@ -44,6 +45,7 @@ Running these tests will help determine if a computers is suitable for driving a [NOTE] Do not run LinuxCNC or StepConf while the latency test is running. + [[sec:latency-test]] === Latency Test diff --git a/docs/src/man/man1/emccalib.1.adoc b/docs/src/man/man1/emccalib.1.adoc index bd0d3c9cfbc..861d03a0f7d 100644 --- a/docs/src/man/man1/emccalib.1.adoc +++ b/docs/src/man/man1/emccalib.1.adoc @@ -8,6 +8,7 @@ emccalib - Adjust ini tuning variables on the fly with save option *emccalib.tcl* [_options_] + == DESCRIPTION The Calibration assistant. This tool Reads the HAL file and for every diff --git a/docs/src/man/man1/halstreamer.1.adoc b/docs/src/man/man1/halstreamer.1.adoc index d0edc9d3350..f9fecf9a47f 100644 --- a/docs/src/man/man1/halstreamer.1.adoc +++ b/docs/src/man/man1/halstreamer.1.adoc @@ -4,10 +4,12 @@ halstreamer - stream file data into HAL in real-time + == SYNOPSIS *halstreamer* [_options_] + == DESCRIPTION The HAL component *streamer*(9) and the program *halstreamer* are used together to stream data from a file into the HAL in real-time. diff --git a/docs/src/man/man1/hy_gt_vfd.1.adoc b/docs/src/man/man1/hy_gt_vfd.1.adoc index 5d90b3b951a..2e69031d7af 100644 --- a/docs/src/man/man1/hy_gt_vfd.1.adoc +++ b/docs/src/man/man1/hy_gt_vfd.1.adoc @@ -1,9 +1,11 @@ = hy_gt_vfd(1) + == NAME hy_gt_vfd - HAL non-realtime component for Huanyang GT-series VFDs + == SYNOPSIS *hy_gt_vfd* [_OPTIONS_] diff --git a/docs/src/man/man1/linuxcncrsh.1.adoc b/docs/src/man/man1/linuxcncrsh.1.adoc index fbf092d310e..424c956579f 100644 --- a/docs/src/man/man1/linuxcncrsh.1.adoc +++ b/docs/src/man/man1/linuxcncrsh.1.adoc @@ -688,6 +688,7 @@ Subcommands for 'GET' and 'SET' are: With get, the current 'WAIT_MODE' setting is returned. With set, set the 'WAIT_MODE' setting to the specified value. + == EXAMPLE SESSION This section shows an example session to the local machine (*localhost*). diff --git a/docs/src/man/man1/mb2hal.1.adoc b/docs/src/man/man1/mb2hal.1.adoc index 1f638324324..669e32d4b70 100644 --- a/docs/src/man/man1/mb2hal.1.adoc +++ b/docs/src/man/man1/mb2hal.1.adoc @@ -75,6 +75,7 @@ See https://linuxcnc.org/docs/html/drivers/mb2hal.html[] for more information. *mb2hal.m.num_errors* u32 in:: Error counter + m = HAL_TX_NAME or transaction number if not set + n = element number (NELEMENTS) diff --git a/docs/src/man/man1/melfagui.1.adoc b/docs/src/man/man1/melfagui.1.adoc index 50b7a653c87..08c8b82c363 100644 --- a/docs/src/man/man1/melfagui.1.adoc +++ b/docs/src/man/man1/melfagui.1.adoc @@ -8,6 +8,7 @@ melfagui - Vismach Virtual Machine GUI *melfagui* is one of the sample *Vismach* GUIs for LinuxCNC, simulating a Mitsubishi serial manipulator. + == SEE ALSO *linuxcnc(1)* diff --git a/docs/src/man/man1/mesambccc.1.adoc b/docs/src/man/man1/mesambccc.1.adoc index 73cc727bd56..cafddf82b11 100644 --- a/docs/src/man/man1/mesambccc.1.adoc +++ b/docs/src/man/man1/mesambccc.1.adoc @@ -145,6 +145,7 @@ the 'clamp' attribute is set in the '': (`S_ABCDEFGH`...`S_HGFEDCBA`) ** unsigned integer [0..18446744073709551615] (`U_ABCDEFGH`...`U_HGFEDCBA`) + === The main enclosing tag '' contains the communication parameters and other setup values as attributes: @@ -343,6 +344,7 @@ Recognized '/' attributes when sending Modbus commands: may be expected within the timeout period but not after the timeout expires. This may be required for flaky devices. Default false. + ==== Delay instruction Recognized '/' attributes in delay commands: diff --git a/docs/src/man/man1/svd-ps_vfd.1.adoc b/docs/src/man/man1/svd-ps_vfd.1.adoc index e3ae5a7ba2c..b28b15d25fc 100644 --- a/docs/src/man/man1/svd-ps_vfd.1.adoc +++ b/docs/src/man/man1/svd-ps_vfd.1.adoc @@ -4,6 +4,7 @@ svd-ps_vfd - HAL non-realtime component for SVD-P(S) VFDs + == SYNOPSIS *svd-ps_vfd* [_OPTIONS_] diff --git a/docs/src/man/man1/xhc-whb04b-6.1.adoc b/docs/src/man/man1/xhc-whb04b-6.1.adoc index edeba9d6001..e2beade376f 100644 --- a/docs/src/man/man1/xhc-whb04b-6.1.adoc +++ b/docs/src/man/man1/xhc-whb04b-6.1.adoc @@ -459,6 +459,7 @@ net pdnt.axis.x.jog-vel-mode whb.axis.x.jog-vel-mode net pdnt.axis.y.jog-vel-mode whb.axis.y.jog-vel-mode axis.y.jog-vel-mode net pdnt.axis.z.jog-vel-mode whb.axis.z.jog-vel-mode axis.z.jog-vel-mode + # macro buttons to MDI commands net pdnt.macro-1 whb.button.macro-1 halui.mdi-command-01 # use MDI command from main.ini net pdnt.macro-2 whb.button.macro-2 halui.mdi-command-02 # use MDI command from main.ini @@ -478,6 +479,7 @@ net pdnt.macro.11 whb.button.macro-11 net pdnt.macro.12 whb.button.macro-12 halui.mdi-command-12 # use MDI command from main.ini net pdnt.macro.13 whb.button.macro-13 halui.mdi-command-13 # use MDI command from main.ini + # flood and mist toggle signals net pdnt.flood.is-on whb.halui.flood.is-on halui.flood.is-on #return signal is on or off net pdnt.flood.off whb.halui.flood.off halui.flood.off #reserved whb.button.macro-15 diff --git a/docs/src/man/man3/hm2_pktuart.3.adoc b/docs/src/man/man3/hm2_pktuart.3.adoc index a3626a09f6c..489628c0a96 100644 --- a/docs/src/man/man3/hm2_pktuart.3.adoc +++ b/docs/src/man/man3/hm2_pktuart.3.adoc @@ -235,6 +235,7 @@ int process(void *arg, long period) { } ---- + == PINS The functions / hostmot2 component do not create any HAL pins. diff --git a/docs/src/man/man9/demux_generic.9.adoc b/docs/src/man/man9/demux_generic.9.adoc index 086d3e64be3..01d75542fe8 100644 --- a/docs/src/man/man9/demux_generic.9.adoc +++ b/docs/src/man/man9/demux_generic.9.adoc @@ -13,6 +13,7 @@ Types: **b** = bit, **f** = float, **s** = signed integer, **u** = unsigned inte Example: **loadrt demux_generic config="**bb8,fu12**"** + == FUNCTIONS **demux-gen.**_NN_ Depending on the data types can run in either a floating point or non-floating point thread. diff --git a/docs/src/man/man9/hm2_modbus.9.adoc b/docs/src/man/man9/hm2_modbus.9.adoc index 1cde71ecbee..c602e639408 100644 --- a/docs/src/man/man9/hm2_modbus.9.adoc +++ b/docs/src/man/man9/hm2_modbus.9.adoc @@ -31,6 +31,7 @@ PktUART ports. process-wide and all modules within the process will spit out messages at the requested level. This may cause quite some clutter in your terminal. + == DESCRIPTION The *hm2_modbus* driver implements the Modbus protocol and maps HAL pins to diff --git a/docs/src/man/man9/hm2_rpspi.9.adoc b/docs/src/man/man9/hm2_rpspi.9.adoc index 43b25a67c2b..d9fcb8e496c 100644 --- a/docs/src/man/man9/hm2_rpspi.9.adoc +++ b/docs/src/man/man9/hm2_rpspi.9.adoc @@ -6,6 +6,7 @@ hm2_rpspi - This driver has been superseded by the hm2_spix driver. LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware. + == SYNOPSIS *loadrt hm2_rpspi* diff --git a/docs/src/man/man9/hostmot2.9.adoc b/docs/src/man/man9/hostmot2.9.adoc index e2da9902819..743b01162a9 100644 --- a/docs/src/man/man9/hostmot2.9.adoc +++ b/docs/src/man/man9/hostmot2.9.adoc @@ -81,8 +81,10 @@ The comma character (,) separates members of the config array from each other. For example, if your control computer has one 5I20 and one 5I23 you might load the hm2_pci driver with a HAL command (in halcmd) something like this: + *loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,firmware=hm2/5i23/SVSS8_8.BIT sserial_port_0=0000 num_encoders=4"* + Note: This assumes that the hm2_pci driver detects the 5I20 first and the 5I23 second. If the detection order does not match the order of the config strings, the hostmot2 driver will refuse to load the firmware and diff --git a/docs/src/man/man9/kins.9.adoc b/docs/src/man/man9/kins.9.adoc index 0235bbf9fca..c6fc0ff36f0 100644 --- a/docs/src/man/man9/kins.9.adoc +++ b/docs/src/man/man9/kins.9.adoc @@ -69,6 +69,7 @@ Example: loadrt *trivkins coordinates=xz*:: Example: loadrt *trivkins coordinates=xyzy*:: Assigns: x==joint0, y0==joint1, z==joint2, y1==joint3: + The default kinematics type is *KINEMATICS_IDENTITY*. GUIs may provide special features for configurations using this default kinematics type. For instance, the AXIS GUI automatically handles joint and world mode @@ -76,6 +77,7 @@ operations so that the distinctions between joints and axes are not visible to the operator. This is feasible since there is an exact correspondence between a joint number and its matching axis letter. + The kinematics type can be set with the *kinstype=* parameter::: kinstype=**1** for KINEMATICS_IDENTITY (default if kinstype= omitted):: + diff --git a/docs/src/man/man9/streamer.9.adoc b/docs/src/man/man9/streamer.9.adoc index 5316bb9fd85..a05257da4f1 100644 --- a/docs/src/man/man9/streamer.9.adoc +++ b/docs/src/man/man9/streamer.9.adoc @@ -71,9 +71,11 @@ One function is created per FIFO, numbered from zero. halstreamer(1), sampler(9), halsampler(1) + == BUGS Should an enable HAL pin be added, to allow streaming to be turned on and off? + == AUTHOR Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other members of the LinuxCNC development team. diff --git a/docs/src/pdf-theme.yml b/docs/src/pdf-theme.yml index 60e7be926a7..b888cc12ed1 100644 --- a/docs/src/pdf-theme.yml +++ b/docs/src/pdf-theme.yml @@ -8,10 +8,10 @@ font: catalog: merge: true DejaVu Sans Mono: - normal: /usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf - bold: /usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf - italic: /usr/share/fonts/truetype/dejavu/DejaVuSansMono-Oblique.ttf - bold_italic: /usr/share/fonts/truetype/dejavu/DejaVuSansMono-BoldOblique.ttf + 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 diff --git a/docs/src/plasma/qtplasmac.adoc b/docs/src/plasma/qtplasmac.adoc index e901faa39e5..93ea3330c8a 100644 --- a/docs/src/plasma/qtplasmac.adoc +++ b/docs/src/plasma/qtplasmac.adoc @@ -695,6 +695,7 @@ Some functions/features are only used for particular modes and are not displayed |C |This button clears the live plot. |=== + .*MACHINE* representation [cols="4,16",options="header"] //[grid=none,frame=ends] @@ -1205,6 +1206,7 @@ The text may be edited at any time and will be loaded ready for use if the *SAVE To return the *EXIT WARNING MESSAGE* text to the last saved value press the *RELOAD* button. + .*UTILITIES* Some standard LinuxCNC utilities are provided as an aid in the diagnosis of issues that may arise: diff --git a/docs/src/remap/remap.adoc b/docs/src/remap/remap.adoc index 6adfb29c7a1..b119b22c193 100644 --- a/docs/src/remap/remap.adoc +++ b/docs/src/remap/remap.adoc @@ -2166,6 +2166,7 @@ All the interpreter does is evaluate the toolnumber parameter, looks up its corr remembers it in the `selected_pocket` variable for later, and queues a canon command (SELECT_TOOL). See 'Interp::convert_tool_select' in 'src/emc/rs274/interp_execute.cc'. + .Task action on SELECT_TOOL When `task` gets around to handle a SELECT_TOOL, it sends a EMC_TOOL_PREPARE message to the `iocontrol` process, which handles most tool-related actions in LinuxCNC. @@ -2247,6 +2248,7 @@ If zero, this means 'unload tool', else 'set current tool number to Q'. .Building the replacement for `M61` An example Python redefinition for `M61` can be found in the `set_tool_number` function in `nc_files/remap_lib/python-stdglue/stdglue.py`. + == Status . The RELOAD_ON_CHANGE feature is fairly broken. Restart after changing a Python file. 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 e5ceea71fc5..00000000000 --- a/docs/src/source-highlight/hal-demo.adoc +++ /dev/null @@ -1,43 +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 -// 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 04a78f20b0e..00000000000 --- a/docs/src/source-highlight/ini-demo.adoc +++ /dev/null @@ -1,230 +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 -// 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 a48103d5aed..00000000000 --- a/docs/src/source-highlight/ngc-demo.adoc +++ /dev/null @@ -1,114 +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. -// 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/tooldatabase/tooldatabase.adoc b/docs/src/tooldatabase/tooldatabase.adoc index d2ff3bb6fae..0fab0191b21 100644 --- a/docs/src/tooldatabase/tooldatabase.adoc +++ b/docs/src/tooldatabase/tooldatabase.adoc @@ -116,6 +116,7 @@ The updated list of tools will be used on subsequent get commands or load_tool_t [NOTE] Removal of a tool number should only be done if the tool number is not currently loaded in spindle. + ==== Debug Environmental Variables Exporting the environmental variable DB_SHOW enables LinuxCNC prints (to stdout) that show tool data retrieved from the *db_program* at startup and at subsequent reloading of tool data. diff --git a/src/configure.ac b/src/configure.ac index 8929b9f498f..d9a5aac532d 100644 --- a/src/configure.ac +++ b/src/configure.ac @@ -1122,44 +1122,33 @@ or "sudo apt-get install ruby-asciidoctor-pdf" (Debian bookworm)]) # as the cryptic "No rule to make target NotoSerifCJK-Regular.ttc" # deep in the make output -- the original hansu complaint on #4053. AC_MSG_CHECKING([for NotoSerifCJK Regular .ttc]) - NOTOCJK_REGULAR_TTC="" - for f in \ - "`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Regular' 2>/dev/null`" \ - /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc \ - /usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc \ - /usr/share/fonts/google-noto-cjk-fonts/NotoSerifCJK-Regular.ttc \ - /usr/share/fonts/google-noto-cjk/NotoSerifCJK-Regular.ttc ; do - case "$f" in - *.ttc) test -r "$f" && NOTOCJK_REGULAR_TTC="$f" && break ;; - esac - done + 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]) - AC_MSG_ERROR([NotoSerifCJK Regular TrueType Collection not found, cannot build PDF documentation + AC_MSG_ERROR([NotoSerifCJK Regular TrueType Collection not found via fc-match, cannot build PDF documentation 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. -If the .ttc is in a non-standard location, point us at it with +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_MSG_RESULT([$NOTOCJK_REGULAR_TTC]) AC_MSG_CHECKING([for NotoSerifCJK Bold .ttc]) - NOTOCJK_BOLD_TTC="" - for f in \ - "`fc-match --format='%{file}' 'Noto Serif CJK SC:style=Bold' 2>/dev/null`" \ - /usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc \ - /usr/share/fonts/noto-cjk/NotoSerifCJK-Bold.ttc \ - /usr/share/fonts/google-noto-cjk-fonts/NotoSerifCJK-Bold.ttc \ - /usr/share/fonts/google-noto-cjk/NotoSerifCJK-Bold.ttc ; do - case "$f" in - *.ttc) test -r "$f" && NOTOCJK_BOLD_TTC="$f" && break ;; - esac - done + 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]) - AC_MSG_ERROR([NotoSerifCJK Bold TrueType Collection not found, cannot build PDF documentation + AC_MSG_ERROR([NotoSerifCJK Bold TrueType Collection not found via fc-match, cannot build PDF documentation 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.]) From ad118449db8c3a990516418441681b2ede4ea761 Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Mon, 25 May 2026 11:24:41 +0200 Subject: [PATCH 25/30] docs: set heading color of PDF to black --- docs/src/pdf-theme.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/pdf-theme.yml b/docs/src/pdf-theme.yml index b888cc12ed1..7af6feff8d0 100644 --- a/docs/src/pdf-theme.yml +++ b/docs/src/pdf-theme.yml @@ -34,7 +34,7 @@ base: heading: font_family: $base_font_family - font_color: 0000FF + font_color: 000000 font_style: bold text_align: left line_height: 1.2 From 3100fb3ca2a5ec83e82a4e56fc72df931b99cb41 Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Mon, 25 May 2026 11:27:34 +0200 Subject: [PATCH 26/30] docs: extend default INI highlighter to include # comments, set syntax-hightlighting style to 'pastie' --- docs/src/Submakefile | 6 ++++++ docs/src/extensions/rouge_ini.rb | 26 ++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 docs/src/extensions/rouge_ini.rb diff --git a/docs/src/Submakefile b/docs/src/Submakefile index e21172a2997..65a7b91fbf3 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -540,6 +540,7 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% 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=html5 \ -a compat-mode \ @@ -550,6 +551,7 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% -a "stylesdir=../.." \ -a stylesheet=linuxcnc.css \ -a source-highlighter=rouge \ + -a rouge-style=pastie \ -o $@ \ "$$F" \ ; \ @@ -749,10 +751,12 @@ $(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(DOC_F $(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=pastie \ -a "pdf-fontsdir=$(realpath $(DOC_FONT_DIR));GEM_FONTS_DIR" \ -a "lversion=$(shell cat ../VERSION)" \ -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ @@ -861,6 +865,7 @@ $$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$ $$(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" \ @@ -870,6 +875,7 @@ $$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$ -a "relindir=$$(shell dirname $$*)" \ -a stylesheet=linuxcnc.css \ -a source-highlighter=rouge \ + -a rouge-style=pastie \ -d book -a toc -a numbered \ -o $$@ $$< || (X=$$$$?; rm -f $$@; exit $$$$X) endef diff --git a/docs/src/extensions/rouge_ini.rb b/docs/src/extensions/rouge_ini.rb new file mode 100644 index 00000000000..0ffaee28568 --- /dev/null +++ b/docs/src/extensions/rouge_ini.rb @@ -0,0 +1,26 @@ +# docs/src/extensions/rouge_ini.rb +# +# This extends the default Rouge lexer for INI files to include comments with leading '#'. +# +# Loaded via the asciidoctor -r flag from the docs Submakefile. + +require "rouge" + +module Rouge + module Lexers + class LinuxCNCINI < Rouge::Lexers::INI + title "INI" + desc "LinuxCNC INI dialect with # comments" + + state :root do + # add # comments + rule %r/#.*$/, Comment::Single + + # keep existing ; comments + rule %r/;.*$/, Comment::Single + + mixin :base + end + end + end +end From 7487979ac847e8412b0acdec344fbabc1eec1b55 Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Mon, 25 May 2026 11:27:55 +0200 Subject: [PATCH 27/30] docs: add syntax-highlighting for PDF-docs --- docs/src/Submakefile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 65a7b91fbf3..3845940f870 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -686,6 +686,7 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -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)" \ @@ -696,6 +697,8 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -a "lversion=$(shell cat ../VERSION)" \ -a toc -a numbered \ -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ + -a source-highlighter=rouge \ + -a rouge-style=pastie \ -d book \ -o $@.raw $< || (X=$$?; rm -f $@.raw; \ if [ $$X -eq 124 ]; then echo "asciidoctor-pdf timed out after 15 min on $<"; fi; \ From 3dc614ca644d486397c6638ec725c0445c40988e Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 15:21:39 +0800 Subject: [PATCH 28/30] build: drop nocheck workaround, ignore autom4te.cache build-package-indep.sh: nocheck was a workaround for the trixie/bookworm autorestart hang in dh_auto_test; root cause fixed in 385c57eec5 so the test step is back to its normal no-op. .gitignore: top-level autom4te.cache/ gets created by debian/configure on every run; src/autom4te.cache was already ignored, mirror it here. --- .github/scripts/build-package-indep.sh | 2 +- .gitignore | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/scripts/build-package-indep.sh b/.github/scripts/build-package-indep.sh index 6f448357fa7..9bb6b0642f3 100755 --- a/.github/scripts/build-package-indep.sh +++ b/.github/scripts/build-package-indep.sh @@ -8,6 +8,6 @@ debian/update-dch-from-git scripts/get-version-from-git | sed -re 's/^v(.*)$/\1/' >| VERSION; cat VERSION git diff apt-get --yes build-dep --indep-only . -DEB_BUILD_OPTIONS="parallel=$(nproc) nocheck" +DEB_BUILD_OPTIONS="parallel=$(nproc)" export DEB_BUILD_OPTIONS debuild -us -uc --build=source,all diff --git a/.gitignore b/.gitignore index 94e742f2bd7..cec436d255f 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,5 @@ position.txt *.*-stamp # Ignore VSCode settings .vscode/settings.json +# autoreconf cache from debian/configure +/autom4te.cache/ From e1ac2ecccf8b9fc3c9b7a171f18d025a62e4a681 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 18:12:10 +0800 Subject: [PATCH 29/30] docs: derive HTML language rules from po4a.cfg Replace 11 hardcoded ASCIIDOCTOR_HTML_RULE eval calls with a foreach over $(LANGUAGES). po4a.cfg becomes the single source of truth for which languages have HTML output; ar/sv/ta/tr (no docs/src// tree) are dropped, others added free. Addresses bertho review on PR #4053. --- docs/src/Submakefile | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 3845940f870..e24eaf71794 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -887,17 +887,8 @@ endef # 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))/)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,ar,$(DOC_SRCDIR)/ar)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,de,$(DOC_SRCDIR)/de)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,es,$(DOC_SRCDIR)/es)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,fr,$(DOC_SRCDIR)/fr)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,nb,$(DOC_SRCDIR)/nb)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,ru,$(DOC_SRCDIR)/ru)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,sv,$(DOC_SRCDIR)/sv)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,ta,$(DOC_SRCDIR)/ta)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,tr,$(DOC_SRCDIR)/tr)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,uk,$(DOC_SRCDIR)/uk)) -$(eval $(call ASCIIDOCTOR_HTML_RULE,zh_CN,$(DOC_SRCDIR)/zh_CN)) +$(foreach lang,$(LANGUAGES),\ + $(eval $(call ASCIIDOCTOR_HTML_RULE,$(lang),$(DOC_SRCDIR)/$(lang)))) default: docs From 433fe6f7ecb595bf44f47c7dd63a8535614663cc Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 25 May 2026 22:46:32 +0800 Subject: [PATCH 30/30] docs(html): theme switcher (legacy/modern) + bullet preprocessor Adds runtime Legacy/Modern theme toggle via docinfo.html. Legacy reproduces the linuxcnc.css look; Modern is asciidoctor default with prefers-color-scheme dark mode. list_blanks.rb preprocessor injects the blank line asciidoctor needs before bullets so the 200+ adoc sources authored against asciidoc-py keep rendering correctly. --- .gitignore | 4 + docs/src/Submakefile | 43 ++- docs/src/docinfo.html | 51 +++ docs/src/extensions/list_blanks.rb | 69 ++++ docs/src/lcnc-overrides.css | 508 +++++++++++++++++++++++++++++ 5 files changed, 651 insertions(+), 24 deletions(-) create mode 100644 docs/src/docinfo.html create mode 100644 docs/src/extensions/list_blanks.rb create mode 100644 docs/src/lcnc-overrides.css diff --git a/.gitignore b/.gitignore index cec436d255f..e428da3957e 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,7 @@ position.txt .vscode/settings.json # autoreconf cache from debian/configure /autom4te.cache/ +# Local dev-only doc server script (do not ship). +/dev-serve-docs.sh +# Playwright MCP scratch dir (browser snapshots / console / etc). +/.playwright-mcp/ diff --git a/docs/src/Submakefile b/docs/src/Submakefile index e24eaf71794..043446b33d0 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -448,7 +448,7 @@ endif .htmldoc-stamp: copy_asciidoc_files gen_complist $(HTML_TARGETS) .images-stamp .include-stamp touch $@ -copy_asciidoc_files: $(wildcard /etc/asciidoc/stylesheets/*.css) $(wildcard /etc/asciidoc/javascripts/*.js) +copy_asciidoc_files: $(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 gen_complist: $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc $(MAN_HTML_TARGETS) @@ -538,6 +538,7 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% exit 1; \ fi; \ asciidoctor \ + -r $(realpath $(DOC_SRCDIR))/extensions/list_blanks.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 \ @@ -546,12 +547,11 @@ $(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/% -a compat-mode \ -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ - -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=pastie \ + -a rouge-style=github \ -o $@ \ "$$F" \ ; \ @@ -682,6 +682,7 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp $(ECHO) Building $@ @rm -f $@ $@.raw $(Q)timeout 900 asciidoctor-pdf \ + -r $(realpath $(DOC_SRCDIR))/extensions/list_blanks.rb \ -r $(realpath $(DOC_SRCDIR))/extensions/xref_resolver.rb \ -r $(realpath $(DOC_SRCDIR))/extensions/image_resolver.rb \ -r $(realpath $(DOC_SRCDIR))/extensions/rouge_hal.rb \ @@ -698,7 +699,7 @@ $(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp -a toc -a numbered \ -a pdf-theme=$(DOC_SRCDIR)/pdf-theme.yml \ -a source-highlighter=rouge \ - -a rouge-style=pastie \ + -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; \ @@ -752,6 +753,7 @@ $(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(DOC_F @$(ECHO) Formatting manual pages as PDF @rm -f $@ $@.raw $(Q)timeout 900 asciidoctor-pdf \ + -r $(realpath $(DOC_SRCDIR))/extensions/list_blanks.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 \ @@ -759,7 +761,7 @@ $(DOC_DIR)/LinuxCNC_Manual_Pages.pdf: objects/LinuxCNC_Manual_Pages.adoc $(DOC_F -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ -a source-highlighter=rouge \ - -a rouge-style=pastie \ + -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 \ @@ -848,16 +850,9 @@ $(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 @@ -865,20 +860,20 @@ $(DOC_SRCDIR)/%.html: STYLES_SCRIPTS=$(shell \ define ASCIIDOCTOR_HTML_RULE $$(patsubst %.adoc,$$(DOC_SRCDIR)/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $$(DOC_SRCDIR)/%.html: $$(DOC_SRCDIR)/%.adoc $$(ECHO) "Building '$1' adoc to html: " $$< - $$(Q)asciidoctor -r $$(realpath $$(DOC_SRCDIR))/extensions/xref_resolver.rb \ + $$(Q)asciidoctor -r $$(realpath $$(DOC_SRCDIR))/extensions/list_blanks.rb \ + -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 linkcss \ - $$(STYLES_SCRIPTS) \ - -a "scriptdir=$$(DOC_SRCDIR)/" \ -a "relindir=$$(shell dirname $$*)" \ - -a stylesheet=linuxcnc.css \ + -a "lcnc-cssrel=$$(LCNC_CSSREL)" \ + -a docinfo=shared \ + -a docinfodir=$$(realpath $$(DOC_SRCDIR)) \ -a source-highlighter=rouge \ - -a rouge-style=pastie \ + -a rouge-style=github \ -d book -a toc -a numbered \ -o $$@ $$< || (X=$$$$?; rm -f $$@; exit $$$$X) endef diff --git a/docs/src/docinfo.html b/docs/src/docinfo.html new file mode 100644 index 00000000000..db2be0d315f --- /dev/null +++ b/docs/src/docinfo.html @@ -0,0 +1,51 @@ + + + + + diff --git a/docs/src/extensions/list_blanks.rb b/docs/src/extensions/list_blanks.rb new file mode 100644 index 00000000000..f0d214c3393 --- /dev/null +++ b/docs/src/extensions/list_blanks.rb @@ -0,0 +1,69 @@ +# docs/src/extensions/list_blanks.rb +# +# Asciidoctor preprocessor that inserts a blank line before a bullet-list +# marker when it follows a non-empty, non-list line. Asciidoctor strictly +# requires the blank delimiter; asciidoc-py was lenient, and the LinuxCNC +# docs were authored against the lenient behaviour. Rather than touching +# 200+ files we adjust the source stream at parse time so blame and history +# stay clean. +# +# Only touches the top-level list marker `* `. Bullets inside listing, +# literal, passthrough, comment and table blocks are left alone so we +# don't corrupt verbatim content. +# +# Wire-up (in Submakefile): +# asciidoctor -r $(DOC_SRCDIR)/extensions/list_blanks.rb ... + +require 'asciidoctor' +require 'asciidoctor/extensions' + +module LinuxCNCDocs + class ListBlanks < Asciidoctor::Extensions::Preprocessor + # Bullet at column 0 (asciidoctor allows up to '*****' for nesting, + # but only the column-0 ones are paragraph-breaking and only those + # are the broken pattern in the LinuxCNC docs). + BULLET = /\A\*\s/ + + # Delimited block fences we must NOT enter. Pair-matched on the + # *exact* delimiter length so a closing fence matches its opener. + FENCE = /\A(-{4,}|\.{4,}|\++|\/{4,}|\|={3,})\s*\z/ + + def process(document, reader) + lines = reader.lines + out = [] + inside = nil # nil or the opening fence string we're waiting to close + + lines.each_with_index do |line, i| + if inside + out << line + inside = nil if line.strip == inside + next + end + + if (m = FENCE.match(line)) + inside = m[1] + out << line + next + end + + if BULLET.match?(line) + prev = out.last + if prev && !prev.empty? && !BULLET.match?(prev) && !prev.start_with?('//') + # The previous line is a paragraph line; asciidoctor would + # glue this bullet onto it. Inject a blank so the list + # opens. + out << '' + end + end + + out << line + end + + Asciidoctor::PreprocessorReader.new(document, out, reader.cursor) + end + end +end + +Asciidoctor::Extensions.register do + preprocessor LinuxCNCDocs::ListBlanks +end diff --git a/docs/src/lcnc-overrides.css b/docs/src/lcnc-overrides.css new file mode 100644 index 00000000000..b2fed2a3595 --- /dev/null +++ b/docs/src/lcnc-overrides.css @@ -0,0 +1,508 @@ +/* LinuxCNC HTML theme overrides. + Two themes activated by body class set in docinfo.html JS: + body.lcnc-legacy -> approximate the python-asciidoc + linuxcnc.css + look (default for now, switchable via top-right + button). + body.lcnc-modern -> asciidoctor default plus small fixes: + - drop yellow #text# highlight + - uniform listing-block grey background + - opt-in dark mode via prefers-color-scheme +*/ + +/* ====================================================================== + * MODERN (asciidoctor default + small fixes) + * ====================================================================== */ + +/* #text# in compat-mode -> ; drop yellow. */ +body.lcnc-modern mark { + background: transparent; + color: inherit; +} + +/* Uniform grey background on every listing block (hal/ini/ngc/plain). */ +body.lcnc-modern .listingblock > .content, +body.lcnc-modern .literalblock > .content, +body.lcnc-modern .listingblock pre, +body.lcnc-modern .literalblock pre, +body.lcnc-modern .listingblock > .content > pre[class^="highlight"], +body.lcnc-modern .listingblock > .content > pre:not(.highlight), +body.lcnc-modern .literalblock pre.highlight { + background: #f7f7f7; +} + +/* Dark mode honours the OS / browser preference; only modern opts in. */ +@media (prefers-color-scheme: dark) { + body.lcnc-modern { + background: #1e1e1e; + color: #e0e0e0; + } + body.lcnc-modern #header h1, + body.lcnc-modern h1 { + color: #f0f0f0; + } + body.lcnc-modern h2, + body.lcnc-modern #toctitle { + color: #e08a5a; + } + body.lcnc-modern h3, + body.lcnc-modern h4, + body.lcnc-modern h5, + body.lcnc-modern h6 { + color: #d8a070; + } + body.lcnc-modern #preamble > .sectionbody > .paragraph p, + body.lcnc-modern #preamble > .sectionbody > .paragraph.lead > p { + color: #d0d0d0; + } + body.lcnc-modern a { color: #6fa8dc; } + body.lcnc-modern a:visited { color: #b48ead; } + body.lcnc-modern .listingblock > .content, + body.lcnc-modern .literalblock > .content, + body.lcnc-modern .listingblock pre, + body.lcnc-modern .literalblock pre, + body.lcnc-modern .listingblock > .content > pre[class^="highlight"], + body.lcnc-modern .listingblock > .content > pre:not(.highlight), + body.lcnc-modern .literalblock pre.highlight { + background: #2a2a2a; + color: #f0f0f0; + } + body.lcnc-modern .listingblock pre *, + body.lcnc-modern .literalblock pre * { + color: #f0f0f0 !important; + background: transparent !important; + } + body.lcnc-modern code, + body.lcnc-modern tt { + background: #3a3a3a; + color: #f0f0f0; + } + body.lcnc-modern p code, + body.lcnc-modern li code, + body.lcnc-modern td code { + padding: 1px 4px; + border-radius: 3px; + } + body.lcnc-modern table.tableblock, + body.lcnc-modern table.tableblock th, + body.lcnc-modern table.tableblock td { + border-color: #444; + color: #e0e0e0; + background: #1e1e1e; + } + body.lcnc-modern table.tableblock tbody tr th, + body.lcnc-modern table.tableblock tfoot tr th, + body.lcnc-modern table.tableblock thead tr th { + background: #2a2a2a; + color: #f0f0f0; + } + body.lcnc-modern table.tableblock tbody tr th p, + body.lcnc-modern table.tableblock tfoot tr th p { + color: #f0f0f0; + } + body.lcnc-modern table.stripes-all > * > tr, + body.lcnc-modern table.stripes-odd > * > tr:nth-of-type(odd), + body.lcnc-modern table.stripes-even > * > tr:nth-of-type(even), + body.lcnc-modern table.stripes-hover > * > tr:hover { + background: #2a2a2a; + } + body.lcnc-modern .admonitionblock > table td.content { + color: #d0d0d0; + border-left-color: #444; + } + body.lcnc-modern .admonitionblock > table td.icon, + body.lcnc-modern .admonitionblock > table td.icon .title { + color: #e06464; + font-weight: bold; + } +} + +/* ====================================================================== + * LEGACY (python-asciidoc + linuxcnc.css look) + * ====================================================================== */ + + +/* ---- compat-mode #text# -> : drop yellow highlight ----------- */ +body.lcnc-legacy mark { + background: transparent; + color: inherit; +} + +/* ---- body: Georgia serif, narrow side margin, full text contrast --- */ +body.lcnc-legacy { + font-family: Georgia, "Times New Roman", serif; + font-size: 19px; + line-height: normal; + color: #000; + margin: 1em 5%; +} + +/* ---- paragraphs: legacy tight spacing & size ----------------------- */ +body.lcnc-legacy p { + font-family: inherit; + font-size: 19px; + line-height: normal; + margin: 0 0 0.5em; +} + +/* Asciidoctor styles the first paragraph in #preamble as a "lead" + paragraph (1.21em) at specificity (1,3,1). Beat it. */ +body.lcnc-legacy #preamble > .sectionbody > .paragraph p, +body.lcnc-legacy .paragraph.lead > p { + font-size: 19px; + line-height: normal; + color: #000; +} + +/* ---- definition list: tight legacy layout -------------------------- */ +body.lcnc-legacy .dlist dl { + margin: 0; +} +body.lcnc-legacy dt, +body.lcnc-legacy .hdlist1 { + font-family: Georgia, "Times New Roman", serif; + font-size: 19px; + font-weight: 400; + color: #000080; + margin: 0; +} +body.lcnc-legacy dd { + margin: 0 0 0 40px; +} +body.lcnc-legacy dd > p, +body.lcnc-legacy dd .paragraph p { + font-size: 19px; + line-height: normal; + margin: 0 0 0.5em; +} + +/* ---- section blocks: tighten padding, drop separator strike ------- */ +body.lcnc-legacy .sect1, +body.lcnc-legacy .sect2, +body.lcnc-legacy .sect3 { + padding-bottom: 0; +} +body.lcnc-legacy .sect1 + .sect1 { + border-top: 0; +} + +/* ---- headings: Arial bold, light-purple underline ------------------ */ +body.lcnc-legacy h1, +body.lcnc-legacy h2, +body.lcnc-legacy h3, +body.lcnc-legacy h4, +body.lcnc-legacy h5, +body.lcnc-legacy h6 { + font-family: Arial, Helvetica, sans-serif; + font-weight: 700; + color: #000; + line-height: 1.2; +} +body.lcnc-legacy h1 { + font-size: 32px; + background: #c0c0f0; + border-bottom: 2px solid #8080c0; + margin: 1.2em 0 0.5em; + padding: 0 0 0 0.4em; +} +body.lcnc-legacy h2 { + font-size: 24px; + background: #c0c0f0; + border-bottom: 2px solid #8080c0; + margin: 1.2em 0 0.5em; + padding: 0.5em 0 0 0.4em; +} +body.lcnc-legacy h3 { + display: inline-block; + font-size: 18.72px; + background: transparent; + border-bottom: 2px solid #8080c0; + padding: 0; + margin: 1.2em 0 0.5em; +} +body.lcnc-legacy h4, +body.lcnc-legacy h5, +body.lcnc-legacy h6 { + display: block; + background: transparent; + border-bottom: 2px solid #8080c0; + padding: 0; + margin: 1.2em 0 0.5em; +} +body.lcnc-legacy h4 { font-size: 16px; } + +/* ---- :target highlight: light-blue background on jumped-to anchor -- */ +body.lcnc-legacy :target { + background: #ddeeff !important; +} + +/* ---- italic / em: navy (legacy asciidoc-py style) ------------------ */ +body.lcnc-legacy em, +body.lcnc-legacy i { + color: #000080; +} + +/* ---- links: classic blue / magenta-visited underline --------------- */ +body.lcnc-legacy a { + color: #0000ff; + text-decoration: underline; +} +body.lcnc-legacy a:visited { + color: #ff00ff; +} + +/* ---- list bullets: restore visible markers (asciidoctor default + zeros padding so disc markers are clipped) -------------------- */ +body.lcnc-legacy .ulist ul, +body.lcnc-legacy .olist ol, +body.lcnc-legacy #content ul, +body.lcnc-legacy #content ol { + padding-left: 2em; + margin-left: 0; +} +body.lcnc-legacy .ulist ul { list-style: disc outside; } +body.lcnc-legacy .ulist ul ul { list-style: circle outside; } +body.lcnc-legacy .ulist ul ul ul { list-style: square outside; } +body.lcnc-legacy .olist ol { list-style: decimal outside; } +body.lcnc-legacy .ulist ul li::marker { color: #aaaaaa; } + +/* ---- monospace: Courier ------------------------------------------- */ +body.lcnc-legacy tt, +body.lcnc-legacy code, +body.lcnc-legacy kbd, +body.lcnc-legacy pre { + font-family: "Courier New", Courier, monospace; +} + +/* ---- inline code: navy text, no background ----------------------- */ +body.lcnc-legacy code { + background: transparent; + color: #000080; + padding: 0; + border: 0; + font-size: 0.9em; + font-weight: normal; +} +body.lcnc-legacy .title code { + font-weight: bold !important; + font-size: 1em; +} + +/* ---- listing/literal blocks: uniform bg, thin left bar, navy text - */ +body.lcnc-legacy .listingblock > .content, +body.lcnc-legacy .literalblock > .content { + background: #f7f7f7; + border: 1px solid #dedede; + border-left: 5px solid #f0f0f0; +} +body.lcnc-legacy .listingblock pre, +body.lcnc-legacy .literalblock pre, +body.lcnc-legacy .listingblock pre.rouge, +body.lcnc-legacy .listingblock pre.highlight { + background: #f7f7f7 !important; + border: 0; +} +body.lcnc-legacy .listingblock pre, +body.lcnc-legacy .literalblock pre, +body.lcnc-legacy .listingblock code, +body.lcnc-legacy .literalblock code { + color: #000080; + font-weight: normal; +} + +/* ---- TOC: drop sidebar layout, inline at top ----------------------- */ +body.lcnc-legacy.toc2 { + padding-left: 0; +} +body.lcnc-legacy #toc, +body.lcnc-legacy #toc.toc, +body.lcnc-legacy #toc.toc2 { + position: static; + width: auto; + height: auto; + border: 0 !important; + background: transparent; + padding: 0; + font-family: Georgia, "Times New Roman", serif; + font-size: 16px; + margin-bottom: 2.5em; +} +body.lcnc-legacy #toctitle { + font-family: Arial, Helvetica, sans-serif; + font-weight: 700; + font-size: 1.1em; + color: #527bbd; +} +body.lcnc-legacy #toc ul { + list-style: none; + padding: 0; + margin: 0; +} +body.lcnc-legacy #toc li { + font-family: Georgia, "Times New Roman", serif; + font-size: 17px; + line-height: 1.05; + margin: 0; + padding: 0; +} +body.lcnc-legacy #toc ul.sectlevel2 { margin-left: 2em; font-size: 0.9em; } +body.lcnc-legacy #toc ul.sectlevel3 { margin-left: 4em; font-size: 0.9em; } +body.lcnc-legacy #toc ul.sectlevel4 { margin-left: 6em; font-size: 0.9em; } +body.lcnc-legacy #toc a, +body.lcnc-legacy .toc a { + font-family: Georgia, "Times New Roman", serif; + color: #0000ff; + text-decoration: underline; +} +body.lcnc-legacy #toc a:visited, +body.lcnc-legacy .toc a:visited { + color: #ff00ff; +} + +/* ---- manpage doctype: indent section content (legacy look) -------- */ +body.manpage.lcnc-legacy .sectionbody { + margin-left: 3em; +} + +/* ---- content area: no asciidoctor max-width box -------------------- */ +body.lcnc-legacy #content, +body.lcnc-legacy #header, +body.lcnc-legacy #footer, +body.lcnc-legacy #footnotes { + max-width: none; + margin-left: 0; + margin-right: 0; + padding-left: 0; + padding-right: 0; +} + +/* ---- block titles (image, table, listing...): legacy blue --------- */ +body.lcnc-legacy .title, +body.lcnc-legacy .imageblock > .title, +body.lcnc-legacy .listingblock > .title, +body.lcnc-legacy .literalblock > .title, +body.lcnc-legacy table.tableblock > caption.title, +body.lcnc-legacy .exampleblock > .title, +body.lcnc-legacy .quoteblock > .title, +body.lcnc-legacy .openblock > .title, +body.lcnc-legacy .paragraph > .title, +body.lcnc-legacy .ulist > .title, +body.lcnc-legacy .olist > .title, +body.lcnc-legacy .dlist > .title, +body.lcnc-legacy .hdlist > .title { + font-family: Arial, Helvetica, sans-serif; + font-style: normal; + font-weight: bold; + color: #527bbd; +} + +/* ---- admonition (NOTE/TIP/WARN): mixed-case label, vertical bar --- */ +body.lcnc-legacy .admonitionblock > table td.icon { + width: 1%; + white-space: nowrap; + text-align: left; + padding: 0 0.5em 0 0; + vertical-align: top; +} +body.lcnc-legacy .admonitionblock > table td.icon .title { + font-family: Arial, Helvetica, sans-serif; + font-size: 1em; + font-weight: bold; + text-transform: none; + text-decoration: underline; + color: #527bbd; +} +body.lcnc-legacy .admonitionblock > table td.icon [class^="fa icon-"], +body.lcnc-legacy .admonitionblock > table td.icon i.fa { + display: none; +} +body.lcnc-legacy .admonitionblock > table td.content { + padding: 0 0.5em; + border-left: 3px solid #dddddd; + color: #606060; + font-size: 1.05em; + line-height: 1.2; +} +body.lcnc-legacy .admonitionblock > table td.content > .title { + font-family: Arial, Helvetica, sans-serif; + font-style: normal; + font-weight: bold; + color: #497dc2; +} + +/* ---- tables (content only): centered, 3px #527bbd outer border ---- */ +body.lcnc-legacy table.tableblock { + margin-left: auto; + margin-right: auto; + border: 3px solid #527bbd; + border-collapse: collapse; +} +body.lcnc-legacy table.tableblock th, +body.lcnc-legacy table.tableblock td { + border: 1px solid #527bbd; + padding: 4px 8px; +} +body.lcnc-legacy table.tableblock thead th, +body.lcnc-legacy table.tableblock th.tableblock { + font-family: Arial, Helvetica, sans-serif; + font-weight: bold; + font-size: 0.9em; + line-height: 1.2; + color: #527bbd; + background: transparent; +} +body.lcnc-legacy table.tableblock td, +body.lcnc-legacy table.tableblock td.tableblock { + line-height: 1.2; +} +body.lcnc-legacy table.tableblock thead, +body.lcnc-legacy table.tableblock tfoot, +body.lcnc-legacy table.tableblock tbody tr { + background: transparent; +} + +/* ---- footnotes: small, silver hairline divider -------------------- */ +body.lcnc-legacy .footnote, +body.lcnc-legacy .footnoteref, +body.lcnc-legacy #footnotes div.footnote { font-size: 15px; } +body.lcnc-legacy #footnotes div.footnote p { font-size: 15px; } +body.lcnc-legacy #footnotes div.footnote { line-height: 1.05; } +body.lcnc-legacy #footnotes { + margin: 1em 0 0; + padding: 0.4em 0 0; +} +body.lcnc-legacy #footnotes div.footnote { + margin: 0 0 5px !important; + padding: 0 !important; + text-indent: 0; +} +body.lcnc-legacy #footnotes .footnote a:first-of-type { + text-decoration: underline; + color: #0000ff; + font-weight: 400; + margin-left: 0 !important; +} +body.lcnc-legacy #footnotes hr { + border: none; + border-top: 1px solid #999; + height: 1px; + width: 20%; + margin: 0 0 0.5em; +} +body.lcnc-legacy #footnotes .footnote a:first-of-type:visited { + color: #ff00ff; +} + +/* ---- footer: small Arial, silver hairline above ------------------- */ +body.lcnc-legacy #footer { + background: transparent !important; + color: #000 !important; + font-family: Arial, Helvetica, sans-serif; + font-size: small; + border-top: 1px dashed #999; + padding: 0.5em 0; + margin-top: 1em; +} +body.lcnc-legacy #footer-text, +body.lcnc-legacy #footer * { + color: #000 !important; +}