Skip to content

Commit bd87edd

Browse files
hansuhansu
authored
Merge pull request #3484 Move halcompile generated docs to asciidoc instead of (t)roff
Pull request #3484 from BsAtHome/docs_halcompile-adoc-manual
2 parents 259ad89 + 67c4529 commit bd87edd

98 files changed

Lines changed: 2295 additions & 1452 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/html/asciidoc.css‎

Lines changed: 527 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/html/linuxcnc.css‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
:target { background: #DEF !important; }
22
tt {font-family: "Courier New", Courier, monospace; font-size: 0.95em;}
33
pre { font-family: monospace !important; }
4-
h1, h2 { background: #c0c0f0; }
4+
h1, h2 { background: #c0c0f0; padding-left: 0.5em;}
5+
h2 { padding-top: 0.35em; padding-bottom:0.15em;}
56
h1, h2, h3, h4, h5 { border-bottom: 2px solid #8080c0; color: black; }
67
div.nav { float: right; background: #ffffff; }
78
dt { font-weight: bold; }
@@ -47,3 +48,4 @@ figcaption.title {
4748
dt.hdlist1 {
4849
font-weight: normal;
4950
}
51+
#footer { margin-top: 1em; border-top: 1px dashed silver;}

‎docs/po4a.cfg‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
[options] --master-charset UTF-8 --localized-charset UTF-8
22

3-
[po4a_langs] ar bg ckb cs da de es fr hu it ka nb pl pt_BR pt ro ru sai sk sv tr uk vi zh_CN
3+
# Original list
4+
#[po4a_langs] ar bg ckb cs da de es fr hu it ka nb pl pt_BR pt ro ru sai sk sv tr uk vi zh_CN
5+
# Actual in makefile(s)
6+
#[po4a_langs] ar de es fr nb ru sv tr zh_CN
7+
# Languages with any real translations
8+
[po4a_langs] de es fr nb ru zh_CN
9+
410
[po4a_paths] po/documentation.pot $lang:po/$lang.po
511

612
[po4a_alias:AsciiDoc_def] AsciiDoc opt:"--keep 0 --option 'entry=lang' --option 'tablecells'"
@@ -406,7 +412,6 @@
406412
[type: man_def] man/man9/flipflop.9 $lang:man/$lang/man9/flipflop.9
407413
[type: man_def] man/man9/gantry.9 $lang:man/$lang/man9/gantry.9
408414
[type: man_def] man/man9/gearchange.9 $lang:man/$lang/man9/gearchange.9
409-
[type: man_def] man/man9/genserkins.9 $lang:man/$lang/man9/genserkins.9
410415
[type: man_def] man/man9/gray2bin.9 $lang:man/$lang/man9/gray2bin.9
411416
[type: man_def] man/man9/histobins.9 $lang:man/$lang/man9/histobins.9
412417
[type: man_def] man/man9/hypot.9 $lang:man/$lang/man9/hypot.9

‎docs/src/Submakefile‎

Lines changed: 77 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,8 @@ GENERATED_MANPAGES += $(patsubst ../docs/src/man/%.adoc, ../docs/man/%, $(wildca
1515

1616
MAN_SRCS = $(sort \
1717
$(wildcard $(DOC_DIR)/man/man1/*.1) \
18-
$(wildcard $(DOC_DIR)/man/man3/*.3*) \
18+
$(wildcard $(DOC_DIR)/man/man3/*.3) \
1919
$(wildcard $(DOC_DIR)/man/man9/*.9) \
20-
$(wildcard $(DOC_DIR)/man/es/man1/*.1) \
21-
$(wildcard $(DOC_DIR)/man/es/man3/*.3*) \
22-
$(wildcard $(DOC_DIR)/man/es/man9/*.9) \
2320
$(GENERATED_MANPAGES))
2421

2522
$(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc: $(DOC_SRCDIR)/man/man1/linuxcnc.1.adoc.in config.status
@@ -171,7 +168,7 @@ DOC_SRCS_EN := \
171168
Master_Integrator.adoc \
172169
Master_Developer.adoc
173170

174-
LANGUAGES := $(shell grep '\[po4a_langs\]' $(DOC_DIR)/po4a.cfg| cut -d" " -f2-)
171+
LANGUAGES := $(shell sed -e's/#.*//' < $(DOC_DIR)/po4a.cfg | grep '^\[po4a_langs\]' | cut -d" " -f2-)
175172
LANGUAGES_MATCH := $(shell echo $(LANGUAGES) | tr " " "|")
176173

177174

@@ -190,13 +187,19 @@ ifneq (${TIME_CMD},)
190187
TIME_CMD := ${TIME_CMD} -v
191188
endif
192189

190+
ifeq ($(BUILD_VERBOSE),1)
191+
PO4A_VERBOSE = -v
192+
else
193+
PO4A_VERBOSE =
194+
endif
195+
193196
$(DOC_DIR)/po/documentation.pot: $(addprefix $(DOC_SRCDIR)/, $(DOC_SRCS_EN))
194-
cd $(DOC_DIR); ${TIME_CMD} po4a -v --msgmerge-opt='-v' --no-translations po4a.cfg
197+
cd $(DOC_DIR); ${TIME_CMD} po4a $(PO4A_VERBOSE) --msgmerge-opt='-v' --no-translations po4a.cfg
195198
pofiles: $(DOC_DIR)/po/documentation.pot
196199

197200
ifeq ($(BUILD_DOCS_TRANSLATED),yes)
198201
translateddocs: manpages $(DOC_DIR)/po/documentation.pot
199-
cd $(DOC_DIR); ${TIME_CMD} po4a -v --msgmerge-opt='-v' --no-update po4a.cfg
202+
cd $(DOC_DIR); ${TIME_CMD} po4a $(PO4A_VERBOSE) --msgmerge-opt='-v' --no-update po4a.cfg
200203
else
201204
translateddocs:
202205
endif
@@ -538,11 +541,41 @@ $(DOC_DIR)/LinuxCNC_Developer_zh_CN.pdf: $(DOC_SRCDIR)/zh_CN/Master_Developer.pd
538541
$(DOC_DIR)/html/man/%.html: $(DOC_DIR)/man/%
539542
@echo Formatting $(notdir $<) as HTML
540543
@mkdir -p $(dir $@)
541-
# Attention! This is a temporary fix until Groff 1.23 is released. Should be
542-
# set back to "-m man" when 1.23 is available.
543-
# This fixes the formatting of subsections and appearance in the toc.
544-
# It uses the local an-old.tmac instead of the one which is shipped with Groff.
545-
@(cd $(DOC_DIR)/man; groff -Thtml -m an-old-fixed -M . stylesheet.9 $(patsubst $(DOC_DIR)/man/%,%,$<)) > $@
544+
$(Q)if grep -q '^\.so' $<; then \
545+
ln -srf ../docs/html/man/$$(awk '{print $$2}' $<).html $@; \
546+
else \
547+
N="$$(basename "$<").adoc"; \
548+
D="$$(dirname "$<")"; \
549+
S="$$(basename "$$D")"; \
550+
if [ -r "$(DOC_SRCDIR)/man/$$S/$$N" ]; then \
551+
F="$(DOC_SRCDIR)/man/$$S/$$N"; \
552+
elif [ -r "objects/man/$$S/$$N" ]; then \
553+
F="objects/man/$$S/$$N"; \
554+
else \
555+
echo "Error: Cannot find manpage '$<' in adoc format"; \
556+
exit 1; \
557+
fi; \
558+
asciidoc \
559+
--doctype=manpage \
560+
--backend=html \
561+
-a mansource=LinuxCNC \
562+
-a manmanual='LinuxCNC Documentation' \
563+
-f $(DOC_SRCDIR)/xhtml11.conf \
564+
-f $(DOC_SRCDIR)/xhtml11-head-foot.conf \
565+
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
566+
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
567+
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
568+
-a disable-javascript \
569+
-a autowidth-option \
570+
-a "footer-style=none" \
571+
-a linkcss \
572+
-a "scriptsdir=../.." \
573+
-a "stylesdir=../.." \
574+
-a stylesheet=linuxcnc.css \
575+
-o $@ \
576+
"$$F" \
577+
; \
578+
fi;
546579

547580
SA := <p><a onclick=\"return toggle('man_
548581
SB := ')\"><img id=\"man_
@@ -581,13 +614,17 @@ objects/index.incl: $(GENERATED_MANPAGES) objects/var-MAN_HTML_TARGETS $(DOC_SRC
581614
$(call ADD_HTML_MANPAGES, rtapi, API: RTAPI, $(filter $(DOC_DIR)/html/man/man3/rtapi%.html, $(MAN_HTML_TARGETS))) \
582615
$(call ADD_HTML_MANPAGES, hm2, API: Hostmot2, $(filter $(DOC_DIR)/html/man/man3/hm2%.html, $(MAN_HTML_TARGETS))) \
583616
$(call ADD_HTML_MANPAGES, 3, API: General, $(filter-out $(DOC_DIR)/html/man/man3/hal%.html, $(filter-out $(DOC_DIR)/html/man/man3/rtapi%.html, $(filter-out $(DOC_DIR)/html/man/man3/hm2%.html, $(filter $(DOC_DIR)/html/man/man3/%.html, $(MAN_HTML_TARGETS)))))) \
584-
# now make sure all manpages made it into the html index \
617+
# now make sure all manpages made it into the html index
585618
FAIL=0; \
586619
for F in $$(find $(DOC_DIR)/man/man* -type f); do \
587620
B=$$(basename $$F); \
588621
if ! grep -q $$B $@; then \
589-
echo stray manpage not added to index: $$B; \
590622
FAIL=1; \
623+
if ! grep -q '^\.so' $$F; then \
624+
echo stray manpage not added to index: $$F; \
625+
else \
626+
echo manpage alias not added to index: $$F; \
627+
fi; \
591628
fi; \
592629
done; \
593630
if [ $$FAIL -ne 0 ]; then exit 1; fi
@@ -606,7 +643,7 @@ $(DOC_DIR)/html/index.html: $(DOC_SRCDIR)/index.tmpl objects/index.incl $(DOC_SR
606643
$(DOC_SRCDIR)/%.pdf: $(DOC_SRCDIR)/%.adoc svgs_made_from_dots .adoc-images-stamp
607644
$(ECHO) Building $@
608645
@rm -f $@
609-
$(A2X) -L -d book -vf pdf $< || (X=$$?; rm -f $@; exit $$X)
646+
$(Q)$(A2X) -L -d book -vf pdf $< || (X=$$?; rm -f $@; exit $$X)
610647
@test -f $@
611648

612649
depends/%.d: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/asciideps .include-stamp
@@ -617,9 +654,9 @@ depends/%.d: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/asciideps .include-stamp
617654

618655
objects/%.links-stamp: $(DOC_SRCDIR)/%.adoc $(DOC_SRCDIR)/links.xslt
619656
@mkdir -p `dirname $@`
620-
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)
621-
sh move-if-change $@.tmp $(patsubst %-stamp,%,$@)
622-
touch $@
657+
$(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)
658+
$(Q)sh move-if-change $@.tmp $(patsubst %-stamp,%,$@)
659+
$(Q)touch $@
623660

624661
objects/%.links: objects/%.links-stamp
625662
@:
@@ -734,7 +771,8 @@ $(DOC_SRCDIR)/%.html: STYLES_SCRIPTS=$(shell \
734771
)
735772

736773
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_EN_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_en.links $(LOC_LANG_MAP)
737-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
774+
$(ECHO) "Building 'en' adoc to html: " $<
775+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
738776
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
739777
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
740778
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -747,7 +785,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_EN_SMALL)): $(DOC_SRCDIR)/%.ht
747785
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
748786

749787
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_AR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_ar.links $(LOC_LANG_MAP)
750-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
788+
$(ECHO) "Building 'ar' adoc to html: " $<
789+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
751790
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
752791
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
753792
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -760,7 +799,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_AR_SMALL)): $(DOC_SRCDIR)/%.ht
760799
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
761800

762801
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_DE_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_de.links $(LOC_LANG_MAP)
763-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
802+
$(ECHO) "Building 'de' adoc to html: " $<
803+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
764804
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
765805
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
766806
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -773,7 +813,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_DE_SMALL)): $(DOC_SRCDIR)/%.ht
773813
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
774814

775815
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_ES_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_es.links $(LOC_LANG_MAP)
776-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
816+
$(ECHO) "Building 'es' adoc to html: " $<
817+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
777818
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
778819
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
779820
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -786,7 +827,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_ES_SMALL)): $(DOC_SRCDIR)/%.ht
786827
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
787828

788829
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_FR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_fr.links $(LOC_LANG_MAP)
789-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
830+
$(ECHO) "Building 'fr' adoc to html: " $<
831+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
790832
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
791833
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
792834
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -799,7 +841,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_FR_SMALL)): $(DOC_SRCDIR)/%.ht
799841
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
800842

801843
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_NB_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_nb.links $(LOC_LANG_MAP)
802-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
844+
$(ECHO) "Building 'nb' adoc to html: " $<
845+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
803846
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
804847
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
805848
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -812,7 +855,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_NB_SMALL)): $(DOC_SRCDIR)/%.ht
812855
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
813856

814857
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_RU_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_ru.links $(LOC_LANG_MAP)
815-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
858+
$(ECHO) "Building 'ru' adoc to html: " $<
859+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
816860
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
817861
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
818862
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -825,7 +869,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_RU_SMALL)): $(DOC_SRCDIR)/%.ht
825869
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
826870

827871
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_SV_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_sv.links $(LOC_LANG_MAP)
828-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
872+
$(ECHO) "Building 'sv' adoc to html: " $<
873+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
829874
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
830875
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
831876
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -838,7 +883,8 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_SV_SMALL)): $(DOC_SRCDIR)/%.ht
838883
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
839884

840885
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_TR_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_tr.links $(LOC_LANG_MAP)
841-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
886+
$(ECHO) "Building 'tr' adoc to html: " $<
887+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
842888
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
843889
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
844890
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
@@ -851,9 +897,12 @@ $(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_TR_SMALL)): $(DOC_SRCDIR)/%.ht
851897
-d book -a toc -a numbered -b xhtml11 $< || (X=$$?; rm -f $@; exit $$X)
852898

853899
$(patsubst %.adoc,$(DOC_SRCDIR)/%.html,$(DOC_SRCS_ZH_CN_SMALL)): $(DOC_SRCDIR)/%.html: $(DOC_SRCDIR)/%.adoc objects/xref_zh_CN.links $(LOC_LANG_MAP)
854-
asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
900+
$(ECHO) "Building 'zh_CN' adoc to html: " $<
901+
$(Q)asciidoc -f $(DOC_SRCDIR)/xhtml11.conf \
855902
-f $(DOC_SRCDIR)/asciidoc-dont-replace-arrows.conf \
856903
-a linkcss \
904+
-f $(LOC_HL_DIR)/emc-langs-source-highlight.conf \
905+
-a "source_highlight_dir=$(LOC_HL_DIR)/local" \
857906
$(STYLES_SCRIPTS) \
858907
-a "scriptdir=$(DOC_SRCDIR)/" \
859908
-a "relindir=$(shell dirname $*)" \

‎docs/src/gen_complist.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -41,17 +41,17 @@ def generate_complist(complist_path):
4141
gen_filename = '../docs/src/hal/components_gen.adoc'
4242
file2 = open(gen_filename, 'w')
4343
if len(miss_in_list) > 0:
44-
file2.write('=== Not categorized (auto generated from man pages)\n')
45-
file2.write('[{tab_options}]\n|=======================\n')
44+
file2.write('\n== Not categorized (auto generated from man pages)\n')
45+
file2.write('[{tab_options}]\n|===\n')
4646
for i in sorted(miss_in_list):
4747
file2.write('| ' + i + ' |||\n')
48-
file2.write('|=======================\n')
48+
file2.write('|===\n')
4949
if len(miss_in_man) > 0:
50-
file2.write('\n=== Without man page or broken link (auto generated from component list)\n')
51-
file2.write('[{tab_options}]\n|=======================\n')
50+
file2.write('\n== Without man page or broken link (auto generated from component list)\n')
51+
file2.write('[{tab_options}]\n|===\n')
5252
for i in sorted(miss_in_man):
5353
file2.write('| ' + i + ' |||\n')
54-
file2.write('|=======================\n')
54+
file2.write('|===\n')
5555
file2.close()
5656

5757
generate_links(gen_filename, False, True)

‎docs/src/man/man1/halcompile.1.adoc‎

Lines changed: 53 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ halcompile - Build, compile and install LinuxCNC HAL components
77
== SYNOPSIS
88

99
____
10-
*halcompile* [**--compile**|**--preprocess**|**--document**|**--view-doc**] compfile...
10+
*halcompile* [*--compile*|*--preprocess*|*--document*|*--adoc*|*--view-doc*] compfile...
1111
____
1212

13-
_sudo_ *halcompile* [**--install**|**--install-doc**] compfile...
13+
_sudo_ *halcompile* [*--install*|*--install-doc*] compfile...
1414

1515
____
1616
*halcompile* *--compile* *--userspace* cfile...
@@ -33,6 +33,51 @@ to set the maximum of personality items to 4: [sudo] *halcompile
3333

3434
Do not use [sudo] for RIP installation.
3535

36+
== OPTIONS
37+
38+
*-a*, *--adoc*::
39+
Extract only asciidoc format documentation from the component.
40+
*-c*, *--compile*::
41+
Compile a component or C-source module.
42+
*-d*, *--document*::
43+
Extract man-page format documentation from the component (builds asciidoc and
44+
then converts to manpage). This option requires **asciidoctor**(1) or **a2x**(1)
45+
to be installed on your system.
46+
*-h*, *-?*, *--help*::
47+
Show a brief usage message and exit.
48+
*-i*, *--install*::
49+
Build and install a component.
50+
*-J*, *--view-doc*::
51+
Deprecated. Live view the manpage of the component (builds asciidoc, converts
52+
to manpage and runs **man**(1)). This option requires **asciidoctor**(1)
53+
or **a2x**(1) to be installed on your system.
54+
*-j*, *--install-doc*::
55+
Install the man-page documentation in _usr/share/man1_ or _usr/share/man9_,
56+
depending whether this is a userspace or realtime component.
57+
*-k* _file_, *--keep-adoc*=_file_::
58+
Keep the generated asciidoc file when generating manpage documentation. The
59+
file is saved to _file_. You cannot specify multiple input files when using
60+
this option and it has no effect when only asciidoc formatted documentation is
61+
requested using the *-a* or *--adoc* option.
62+
*-l*, *--require-license*::
63+
Obsolete. The component is always required to have a *licence* tag.
64+
*-o* _file_, *--outfile*=_file_::
65+
Write output to _file_. Can _only_ be used with *--preprocess*, *--adoc* and
66+
*--document* processing.
67+
*-P* _int_, *--personalities*=_int_ (default: 64)::
68+
Set the maximum number of personalities in the component.
69+
*-p*, *--preprocess*::
70+
Only generate a C-file from the component file.
71+
*-U*, *--unix*::
72+
Require the source to have unix-style NL-only line endings.
73+
*-u*, *--userspace*::
74+
Create a userspace C-source (non-realtime). Default is to build realtime
75+
components.
76+
*--extra-compile-args*=_args_::
77+
Extra arguments passed to the C-compiler.
78+
*--extra-link-args*=_args_::
79+
Extra arguments passed to the linker.
80+
3681
== DESCRIPTION
3782

3883
*halcompile* performs many different functions:
@@ -42,19 +87,19 @@ components (the *--compile* flag)
4287
* Compile *.comp* and *.c* files into HAL non-realtime components (the
4388
*--compile --userspace* flag)
4489
* Preprocess *.comp* files into *.c* files (the *--preprocess* flag)
45-
* Extract documentation from *.comp* files into *.9* manpage files (the
46-
*--document* flag)
90+
* Extract documentation from *.comp* files into asciidoc or manpage
91+
section *1* or *9* files (the *--adoc* and *--document* flags)
4792
* Display documentation from *.comp* files onscreen (the *--view-doc*
4893
flag)
4994
* Compile and install *.comp* and *.c* files into the proper directory
5095
for HAL realtime components (the *--install* flag), which may require
5196
_sudo_ to write to system directories.
5297
* Install *.c* and *.py* files into the proper directory for HAL
53-
non-realtime components (the *--install --userspace* flag), which may
98+
non-realtime components (the *--install* *--userspace* flag), which may
99+
require _sudo_ to write to system directories.
100+
* Extract documentation from *.comp* files into *.1* or *.9* manpage
101+
files in the proper system directory (the *--install* flag), which may
54102
require _sudo_ to write to system directories.
55-
* Extract documentation from *.comp* files into *.9* manpage files in
56-
the proper system directory (the *--install* flag), which may require
57-
_sudo_ to write to system directories.
58103
* Preprocess *.comp* files into *.c* files (the *--preprocess* flag)
59104

60105
== SEE ALSO

0 commit comments

Comments
 (0)