Convert the linuxcnc.1 man-page to asciidoc format

docs/src/.gitignore

@@ -30,3 +30,4 @@ uk/*
 vi/*
 zh_CN/*
 index_*.tmpl
+man/man1/linuxcnc.1.adoc

docs/src/Submakefile

@@ -1,4 +1,4 @@
-.PHONY: docs docsclean checkref checkref_en checkref_ar checkref_de checkref_es checkref_fr checkref_nb checkref_ru checkref_sv checkref_tr checkref_zh_CN
+.PHONY: docs docclean checkref checkref_en checkref_ar checkref_de checkref_es checkref_fr checkref_nb checkref_ru checkref_sv checkref_tr checkref_zh_CN
 .PHONY: pdfdocs htmldocs install-doc install-doc-pdf install-doc-html
 
 # To make linuxcnc-checklink widely available
@@ -22,9 +22,11 @@ MAN_SRCS = $(sort \
 	$(wildcard $(DOC_DIR)/man/es/man9/*.9) \
 	$(GENERATED_MANPAGES))
 
-../docs/man/man1/linuxcnc.1: $(DOC_SRCDIR)/man/man1/linuxcnc.1.in config.status
+$(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc: $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc.in config.status
 	./config.status --file=$@:$<
 
+../docs/man/man1/linuxcnc.1: $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc
+
 ifneq ($(MANDB),)
 docs: $(DOC_DIR)/man/index.db
 $(DOC_DIR)/man/index.db: $(MAN_SRCS)
@@ -396,7 +398,7 @@ htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en
 	touch $@
 
 copy_asciidoc_files: $(wildcard /etc/asciidoc/stylesheets/*.css) $(wildcard /etc/asciidoc/javascripts/*.js)
-	cp -f $^ $(DOC_DIR)/html
+	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)
 	mkdir -p $(DOC_DIR)/html/hal
@@ -949,6 +951,7 @@ docclean:
 	-rm -f .images-stamp
 	-rm -f .include-stamp
 	-rm -f $(DOTFILES:.dot=.svg)
+	$(RM) $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc
 
 
 MAN_DEPS := $(patsubst $(DOC_DIR)/man/%, depends/%.d, $(MAN_SRCS))
@@ -985,6 +988,8 @@ else
 docs:
 	$(error Cannot build documents, missing AsciiDoc or some other required program, or explicitly disabled in configure)
 
+clean:
+	$(RM) $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc
 endif
 
 manpages: $(GENERATED_MANPAGES)

docs/src/man/man1/linuxcnc.1.adoc.in

@@ -0,0 +1,116 @@
+= linuxcnc(1)
+
+== NAME
+
+linuxcnc - LinuxCNC (The Enhanced Machine Controller)
+
+== SYNOPSIS
+
+*linuxcnc* [_-h_] [_-v_] [_-d_] [_-r_] [_-l_] [_-k_] [_-t <tpmodulename>
+ [parameters]_] [_-m <homemodulename> [parameters]_] [_-H <dirname>_]
+ [_INI file_]
+
+== DESCRIPTION
+
+*linuxcnc* is used to start LinuxCNC (The Enhanced Machine Controller).
+It starts the realtime system and then initializes a number of LinuxCNC
+components (IO, Motion, GUI, HAL, etc). The most important parameter is
+_INI file_, which specifies the configuration name you would like to
+run. If _INI file_ is not specified, the *linuxcnc* script presents a
+graphical wizard to let you choose one.
+
+== OPTIONS
+
+*-h*::
+  Shows the help
+*-v*::
+  Be a little bit verbose. This causes the script to print information
+  as it works.
+*-d*::
+  Print lots of debug information. All executed commands are echoed to
+  the screen. This mode is useful when something is not working as it
+  should.
+*-r*::
+  Disable redirection of stdout and stderr to ~/linuxcnc_print.txt and
+  ~/linuxcnc_debug.txt when stdin is not a tty. Used when running
+  linuxcnc tests non-interactively.
+*-l*::
+  Use the last-used INI file without prompting. This is often a good
+  choice for a shortcut command or startup item.
+*-k*::
+  Continue in the presence of errors in HAL files
+*-t <tpmodulename> [parameters]*::
+  Specify custom trajectory_planning_module overrides optional INI
+  setting [TRAJ]TPMOD
+*-m <homemodulename> [parameters]*::
+  Specify custom homing_module overrides optional INI setting
+  [EMCMOT]HOMEMOD
+*-H <dirname>*::
+  Search dirname for HAL files before searching INI directory and system
+  library: $HALLIB_DIR
+*<INIFILE>*::
+  The INI file is the main piece of a LinuxCNC configuration. It is not
+  the entire configuration; there are various other files that go with
+  it (NML files, HAL files, TBL files, VAR files). It is, however, the
+  most important one, because it is the file that holds the
+  configuration together. It can adjust a lot of parameters itself, but
+  it also tells *linuxcnc* which other files to load and use.
+
+There are several ways to specify which config to use:
+
+Specify the absolute path to an INI, e.g., +
+*linuxcnc* _/usr/local/linuxcnc/configs/sim/sim.ini_
+
+Specify a relative path from the current directory, e.g. +
+*linuxcnc* _configs/sim/sim.ini_
+
+Otherwise, in the case where the *INIFILE* is not specified, the
+behavior will depend on whether you configured LinuxCNC with
+*--enable-run-in-place*. If so, the LinuxCNC config chooser will search
+only the configs directory in your source tree. If not (or if you are
+using a packaged version of LinuxCNC), it may search several
+directories. The config chooser is currently set to search the path:
+
+....
+@LINUXCNC_CONFIG_PATH@
+....
+
+== EXAMPLES
+
+*linuxcnc*
+
+*linuxcnc* _configs/sim/sim.ini_
+
+*linuxcnc* _/etc/linuxcnc/sample-configs/stepper/stepper_mm.ini_
+
+== SEE ALSO
+
+*halcmd(1)*
+
+Much more information about LinuxCNC and HAL is available in the
+LinuxCNC and HAL User Manuals, found at /usr/share/doc/linuxcnc/.
+
+Web: https://www.linuxcnc.org/
+
+User forum: https://forum.linuxcnc.org/
+
+== BUGS
+
+None known at this time.
+
+== AUTHOR
+
+This man page written by Alex Joni, as part of the LinuxCNC Enhanced
+Machine Controller project.
+
+== REPORTING BUGS
+
+Please report any bugs at https://github.com/LinuxCNC/.
+
+== COPYRIGHT
+
+Copyright © 2003- The LinuxCNC authors.
+
+This is free software; see the source for copying conditions. There is
+NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE.