docs: review on man pages asciidoc transition

A non-working markup with "*" appears as a pointer in C/C++. Introduced [source,c] and blocks to avoid such extra troublesome trouble.
hansu · Sep 1, 2024 · 129c926 · 129c926
1 parent f4b383a
commit 129c926
Show file tree

Hide file tree

Showing 129 changed files with 1,000 additions and 1,147 deletions.
diff --git a/debian/control.top.in b/debian/control.top.in
@@ -34,6 +34,7 @@ Build-Depends:
     libusb-1.0-0-dev,
     libxmu-dev,
     netcat-traditional | netcat-openbsd | netcat,
+    netpbm,
     po4a,
     procps,
     psmisc,

diff --git a/docs/README.adoc b/docs/README.adoc
@@ -5,25 +5,25 @@
 
 == Adding files
 
-The src/Submakefile, src/docs.xml, docs/po4a.cfg and src/index.tmpl
+The `src/Submakefile`, `src/docs.xml`, `docs/po4a.cfg` and `src/index.tmpl`
 files must be updated to add a new document file.
 
 The relevant pdf.adoc must be updated to include the new document in the
-pdf documentation. e.g. if a new document belongs in the Master
-Documentation then an entry is required in src/Master_Documentation.adoc.
+pdf documentation. E.g., a new document belonging to the Master
+Documentation requires an entry in src/Master_Documentation.adoc.
 
-docs.xml is used to create the "previous" and "next" buttons at the top
+`docs.xml` is used to create the "previous" and "next" buttons at the top
 of each individual HTML document. It should generally match the order of
 the index.tmpl.
 
-po4a.cfg is used to map source files to translated documentation when
-generating translated files using the files in docs/po/.
+`po4a.cfg` is used to map source files to translated documentation when
+generating translated files using the files in `docs/po/`.
 
 == Notes on LinuxCNC documentation
 
 The main LinuxCNC Makefile can optionally build the documentation and
 other files in this directory tree. Use "--enable-build-documentation"
-when invoking src/configure, and run "make" from src.
+when invoking `src/configure`, and run "make" from src.
 
 == Notes about drawings
 
@@ -130,7 +130,7 @@ e.g. vec2web drawing.dxf drawing.png
 ```
 
 Initial attempts to use vec2web resulted in the graphical parts of the
-drawing being converted, but all text was lost. I don't know if vec2web
+drawing being converted, but all text was lost. It is not clear if vec2web
 is worth spending much more time on, however, it _is_ GPLv2, and it
 includes a library for reading DXF files, which might be worthwhile to
 the LinuxCNC community.

diff --git a/docs/help/asciidoc-markup_es.adoc b/docs/help/asciidoc-markup_es.adoc
@@ -19,7 +19,7 @@ Los atributos típicos autorizados son: doctype, lang, encoding, icons,
 data-uri, toc, numbered
 
 Más información aquí
-http://www.methods.co.nz/asciidoc/userguide.html#_introduction
+https://www.methods.co.nz/asciidoc/userguide.html#_introduction
 8.2 Header
 
 = Título del documento (nivel 0)
@@ -47,7 +47,7 @@ Solo se mostrará "bombas" en el texto con un subrayado, así que siempre
 proporcione una leyenda para un enlace.
 
 Enlace externo
-http://linuxnc.org/someplace[descripcion del link]
+https://linuxnc.org/someplace[descripcion del link]
 
 = Bloque de comentarios
 
@@ -181,8 +181,8 @@ alternativa es utilizar Open Office Math (o LibreOffice) para crear la
 imagen matemática y gimp para la captura de pantalla y guardarla en un
 png.
 
-Compruebe la http://powerman.name/doc/asciidoc[hoja de referencia de asciidoc]
-o el http://www.methods.co.nz/asciidoc/userguide.html[manual del usuario]
+Compruebe la https://powerman.name/doc/asciidoc[hoja de referencia de asciidoc]
+o el https://www.methods.co.nz/asciidoc/userguide.html[manual del usuario]
 para detalles sobre el formato.
 
 // vim: set syntax=asciidoc:
diff --git a/docs/html/gcode.html b/docs/html/gcode.html
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <!-- 
 Copyright (C) 2006, 2007 Jeff Epler
 
@@ -18,7 +17,7 @@
     along with this program; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 -->
-<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
+<html xml:lang="en" xmlns="https://www.w3.org/1999/xhtml">
   <head>
     <title>LinuxCNC "G-code" Quick Reference</title>
 
@@ -202,7 +201,7 @@
     for(var i=0; i<links.snapshotLength; i++) {
         var it = links.snapshotItem(i);
         it.setAttribute('href',
-            "http://linuxcnc.org/docs/devel/html/" + it.getAttribute('href'));
+            "https://linuxcnc.org/docs/devel/html/" + it.getAttribute('href'));
     }
 }
 

diff --git a/docs/man/an-old-fixed.tmac b/docs/man/an-old-fixed.tmac
@@ -17,7 +17,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see
-.\" <http://www.gnu.org/licenses/>.
+.\" <https://www.gnu.org/licenses/>.
 .
 .
 .\" The file man.local is loaded at the end.  Put local additions there.

diff --git a/docs/src/common/emc-history.adoc b/docs/src/common/emc-history.adoc
@@ -33,14 +33,14 @@ was pursued with success. Next up was the issue of the expensive intelligent
 motion control boards. By this time the processing power of a PC was
 considered great enough to directly take control of the motion routines.
 A quick search of available hardware resulted in the selection of a
-http://www.servotogo.com/[Servo-To-Go] interface board as the first platform
+https://www.servotogo.com/[Servo-To-Go] interface board as the first platform
 for letting the PC directly control the motors. Software for trajectory
 planning and PID loop control was added to the existing user interface and
 RS274 interpreter. Matt successfully used this version to upgrade a couple
 of machines with dead controls and this became the EMC system that first
 caught the attention of the outside world. Mention of EMC on the
 rec.crafts.metalworking USENET newsgroup resulted in early adopters
-like http://pico-systems.com/motion.html[Jon Elson] building systems
+like https://pico-systems.com/motion.html[Jon Elson] building systems
 to take advantage of EMC.
 
 NIST set up a mailing list for people interested in EMC. As time went on,
@@ -54,7 +54,7 @@ Ray went on to write a Tcl/Tk program that became the predominant user
 interface for EMC at the time.
 
 For NIST's perspective, see this
-http://web.archive.org/web/20120417094958/http://www.isd.mel.nist.gov/documents/shackleford/4191_05.pdf[paper]
+https://web.archive.org/web/20120417094958/https://www.isd.mel.nist.gov/documents/shackleford/4191_05.pdf[paper]
 written by William Shackleford and Frederick Proctor, describing the
 history of EMC and its transition to open source.
 

diff --git a/docs/src/drivers/opto22.adoc b/docs/src/drivers/opto22.adoc
@@ -25,7 +25,7 @@ an adapter.
 
 See the manufacturer's website for more info:
 
-http://www.opto22.com/site/pr_details.aspx?cid=4&item=PCI-AC5
+https://www.opto22.com/site/pr_details.aspx?cid=4&item=PCI-AC5
 
 I would like to thank Opto22 for releasing info in their manual,
 easing the writing of this driver!

diff --git a/docs/src/drivers/servo-to-go.adoc b/docs/src/drivers/servo-to-go.adoc
@@ -15,7 +15,7 @@ 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
 quadrature encoder input, 8 channels of analog input and output, 32
 bits digital I/O, an interval timer with interrupt and a watchdog. For more
-information see the http://www.servotogo.com/[Servo To Go] web page.
+information see the https://www.servotogo.com/[Servo To Go] web page.
 
 NOTE: We have had reports that the opamps on the Servo To Go card do
 not work with newer ATX power supplies that use modern switch

diff --git a/docs/src/drivers/vfs11.adoc b/docs/src/drivers/vfs11.adoc
@@ -269,9 +269,8 @@ The VF-S11 has an RJ-45 jack for serial communication.
 Unfortunately, it does not have a standard RS-232 plug and logic levels.
 The Toshiba-recommended way is: connect the USB001Z USB-to-serial conversion unit to the drive, and plug the USB port into the PC.
 A cheaper alternative is a homebrew interface (
-http://git.mah.priv.at/gitweb/vfs11-vfd.git/blob_plain/refs/heads/f12-prod:/VFS11-RJ45_e.pdf[hints
-from Toshiba support],
-http://git.mah.priv.at/gitweb/vfs11-vfd.git/blob_plain/refs/heads/f12-prod:/vfs11-rs232.pdf[circuit diagram]).
+https://git.mah.priv.at/gitweb/vfs11-vfd.git/blob_plain/refs/heads/f12-prod:/VFS11-RJ45_e.pdf[hints from Toshiba support],
+https://git.mah.priv.at/gitweb/vfs11-vfd.git/blob_plain/refs/heads/f12-prod:/vfs11-rs232.pdf[circuit diagram]).
 
 Note: the 24V output from the VFD has no short-circuit protection.
 
@@ -289,11 +288,11 @@ I increased them from 50 to 80.
 
 See dump-params.mio for a description of non-standard VF-S11 parameters of my setup.
 This file is for the
-http://git.mah.priv.at/gitweb/modio.git[modio Modbus interactive utility].
+https://git.mah.priv.at/gitweb/modio.git[modio Modbus interactive utility].
 
 == Programming Note
 
-The vfs11_vfd driver uses the http://www.libmodbus.org[libmodbus version 3] library which is more recent than the version 2 code used in +gs2_vfd+.
+The vfs11_vfd driver uses the https://www.libmodbus.org[libmodbus version 3] library which is more recent than the version 2 code used in +gs2_vfd+.
 
 The Ubuntu +libmodbus5+ and +libmodbus-dev+ packages are only available starting from Ubuntu 12 ('Precise Pengolin').
 Moreover, these packages lack support for the MODBUS_RTS_MODE_* flags.

diff --git a/docs/src/getting-started/getting-linuxcnc.adoc b/docs/src/getting-started/getting-linuxcnc.adoc
@@ -67,7 +67,7 @@ sudo apt-get install zsync
 . Then run this command to download the iso to your computer
 +
 ----
-zsync http://www.linuxcnc.org/iso/linuxcnc_2.9.2-amd64.hybrid.iso
+zsync https://www.linuxcnc.org/iso/linuxcnc_2.9.2-amd64.hybrid.iso
 ----
 
 .zsync in Windows
@@ -178,7 +178,7 @@ sudo dd if=/linuxcnc_2.9.2-amd64.hybrid.iso of=/dev/rdiskN bs=1m
 .Writing the image to a DVD in Windows
 
 . Download and install Infra Recorder, a free and open source image
-  burning program: http://infrarecorder.org/ .
+  burning program: https://infrarecorder.org/ .
 . Insert a blank CD in the drive and select Do nothing or Cancel if an
   auto-run dialog pops up.
 . Open Infra Recorder, and select the 'Actions' menu, then 'Burn image'.
@@ -273,9 +273,9 @@ Synaptic Package manager or with apt-get at the command-line.
 The RTAI kernels are available for download from the linuxcnc.org debian archive.
 The apt source is:
 
-* Debian Bookworm: `deb http://linuxcnc.org bookworm base`
-* Debian Bullseye: `deb http://linuxcnc.org bullseye base`
-* Debian Buster: `deb http://linuxcnc.org buster base`
+* Debian Bookworm: `deb https://linuxcnc.org bookworm base`
+* Debian Bullseye: `deb https://linuxcnc.org bullseye base`
+* Debian Buster: `deb https://linuxcnc.org buster base`
 
 LinuxCNC and the RTAI kernel are now only available for 64-bit OSes but
 there are very few surviving systems that can not run a 64-bit OS.

diff --git a/docs/src/getting-started/hardware-interface.adoc b/docs/src/getting-started/hardware-interface.adoc
@@ -50,10 +50,10 @@ Realtime (time critical) tasks such as step generation are done in hardware (not
 === Mesa via Parallel Port
 Mesa use Field-programmable gate array (FPGA) interfaced via parallel port - e.g. 7i43
 
-Website: http://mesanet.com/    Store: http://store.mesanet.com/
+Website: https://mesanet.com/    Store: https://store.mesanet.com/
 
 === Pico Systems via Parallel Port
-http://pico-systems.com/univstep.html
+https://pico-systems.com/univstep.html
 
 
 == Ethernet
@@ -62,7 +62,7 @@ Mesa cards with a Field-programmable gate array (FPGA), interfaced to LinuxCNC c
 
 Multiple ethernet interface FPGA cards are available, with many expansion cards
 
-Website: http://mesanet.com/    Store: http://store.mesanet.com/
+Website: https://mesanet.com/    Store: https://store.mesanet.com/
 
 === Remora Ethernet
 Realtime requirements are offloaded onto a controller board. Multiple different controller boards are supported - see https://remora-docs.readthedocs.io[Remora docs].
@@ -125,7 +125,7 @@ Mesa PCI / PCIe cards with a Field-programmable gate array (FPGA). Time critical
 
 Multiple daughter / expansion cards are available
 
-Website: http://mesanet.com/    Store: http://store.mesanet.com/
+Website: https://mesanet.com/    Store: https://store.mesanet.com/
 
 == SPI
 SPI = Serial Peripheral Interface. SPI interfaces can be found on single board computers like Raspberry Pi, or Orange Pi. SPI interface is _not_ generally present on standard computers (AMD/Intel).
@@ -144,7 +144,7 @@ Mesa cards with a Field-programmable gate array (FPGA), interfaced to LinuxCNC c
 
 Example: 7C80 for Raspberry Pi
 
-Website: http://mesanet.com/    Store: http://store.mesanet.com/
+Website: https://mesanet.com/    Store: https://store.mesanet.com/
 
 
 == USB

diff --git a/docs/src/gui/qtvcp-libraries.adoc b/docs/src/gui/qtvcp-libraries.adoc
@@ -1179,7 +1179,7 @@ It uses https://launchpad.net/onboard[`Onboard`] or https://git.yoctoproject.org
 
 //TODO Virtual Keyboard: What about other VKB alternatives like:
 //  * kvkbd https://github.com/KDE/kvkbd
-//  * Florence http://florence.sourceforge.net/
+//  * Florence https://florence.sourceforge.net/
 //  * Maliit https://maliit.github.io/, https://github.com/maliit/keyboard
 //    which seems to have interesting contextual features.
 

diff --git a/docs/src/html-images.xslt b/docs/src/html-images.xslt
@@ -3,8 +3,8 @@
   vim: sts=2 sw=2 et
   -->
 <xsl:stylesheet version="1.0"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-    xmlns:html="http://www.w3.org/1999/xhtml">
+    xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
+    xmlns:html="https://www.w3.org/1999/xhtml">
 <xsl:output method='text'/>
 
 <xsl:template match="/">

diff --git a/docs/src/index.tmpl b/docs/src/index.tmpl
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"><head>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xml:lang="en" xmlns="https://www.w3.org/1999/xhtml"><head>
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
 <meta content="width=device-width, initial-scale=1" name="viewport"/>
 <title>LinuxCNC</title>
@@ -113,7 +112,7 @@ function setup_page(){
 <h2>LinuxCNC version <strong>@VERSION@</strong> Documentation</h2>
 
 <div style="margin-top: 0em; margin-bottom: 1em; line-height: 150%">
-<p><a href="http://linuxcnc.org">LinuxCNC Home Page</a>  &bull;
+<p><a href="https://linuxcnc.org">LinuxCNC Home Page</a>  &bull;
 <a href="https://wiki.linuxcnc.org/cgi-bin/wiki.pl">Wiki</a> &bull;
 <a href="https://forum.linuxcnc.org">Forum</a> &bull;
 <a href="https://github.com/LinuxCNC/linuxcnc">Source</a> &bull;
-Original file line number
+Diff line change
@@ Expand Up / @@ -34,6 +34,7 @@ Build-Depends: @@
         libusb-1.0-0-dev,
         libxmu-dev,
         netcat-traditional | netcat-openbsd | netcat,
+        netpbm,
         po4a,
         procps,
         psmisc,
@@ Expand Down @@