Skip to content

docs(build): relocate generated manpages under docs/build/man/, build translated#4109

Open
grandixximo wants to merge 3 commits into
LinuxCNC:masterfrom
grandixximo:docs/man-tree-on-build
Open

docs(build): relocate generated manpages under docs/build/man/, build translated#4109
grandixximo wants to merge 3 commits into
LinuxCNC:masterfrom
grandixximo:docs/man-tree-on-build

Conversation

@grandixximo
Copy link
Copy Markdown
Contributor

@grandixximo grandixximo commented Jun 3, 2026 •
edited
Loading

Follow-up to #4081. Moves the generated troff manpage tree out of the source tree into docs/build/man/.

Layout follows the /usr/share/man hierarchy (per your call, Bertho): English at build/man/manN for the C/default locale, translations at build/man/<lang>/manN. This differs on purpose from the build/html/<lang> convention, because man(1) resolves a MANPATH entry by locale and LANG=C only checks <path>/manN; the English special-casing is documented in the Submakefile.

It also builds the translated manpages into that tree: po4a emits the generated comp manpages straight to build/man/<lang>/, and the .adoc-sourced ones render there from their po4a-translated adocs (per-language HTML reuses the same rule). This folds in what was a separate translated-manpages branch, since the relocation already carries the translated plumbing and shipping it half-translated would be odd.

Touches the manpage generation/install paths throughout: docs/src/Submakefile, the hal component/user_comp Submakefiles, install-man + swish (src/Makefile), Doxygen MAN_OUTPUT, halcompile's run-in-place fallback, gen_complist.py, the run-in-place MANPATH (rip-environment), po4a.cfg man_def paths (structural only, no string changes), .gitignore, and the man -M example in tutorial.adoc.

It also relocates a few committed but unreferenced pre-asciidoctor groff leftovers (an-old-fixed.tmac, stylesheet.9, man/images/) into docs/src/man/ rather than discarding them. Open question: should I just delete these instead?

@grandixximo grandixximo force-pushed the docs/man-tree-on-build branch 2 times, most recently from 74f8f98 to bac7260 Compare June 3, 2026 01:33
@grandixximo grandixximo changed the title docs(build): relocate generated manpages under docs/build/man/ docs(build): relocate generated manpages under docs/build/man/, build translated Jun 3, 2026
@BsAtHome
Copy link
Copy Markdown
Contributor

BsAtHome commented Jun 3, 2026

There is one thing I just noted again. The man-page translations are made on basis of the troff output and not on basis of the adoc sources. That will have to change too, eventually. Probably best not to do it with this PR, but this is should be a reminder. Probably best done when we separate man-page pot/po out of main body.

@BsAtHome BsAtHome mentioned this pull request Jun 3, 2026
Open
@grandixximo
Copy link
Copy Markdown
Contributor Author

grandixximo commented Jun 3, 2026 •
edited
Loading

That will have to change too, eventually. Probably best not to do it with this PR, but this is should be a reminder.

Noted

In case you missed it in the PR body, this also relocates a few committed but unreferenced pre-asciidoctor groff leftovers (an-old-fixed.tmac, stylesheet.9, man/images/) into docs/src/man/ rather than discarding them. Open question: should I just delete these instead?

@BsAtHome
Copy link
Copy Markdown
Contributor

BsAtHome commented Jun 3, 2026

In case you missed it in the PR body, this also relocates a few committed but unreferenced pre-asciidoctor groff leftovers (an-old-fixed.tmac, stylesheet.9, man/images/) into docs/src/man/ rather than discarding them. Open question: should I just delete these instead?

I was wondering about them. They are unused afaik. Therefore, should be removed.

If we get complaints or into trouble,... we'll just revert that ;-)

@hansu
Copy link
Copy Markdown
Member

hansu commented Jun 3, 2026

There is one thing I just noted again. The man-page translations are made on basis of the troff output and not on basis of the adoc sources. That will have to change too, eventually. Probably best not to do it with this PR, but this is should be a reminder. Probably best done when we separate man-page pot/po out of main body.

The build output put that into your mind but it is actually building the html man pages from the adoc sources.

See this fix: #4117

@grandixximo grandixximo force-pushed the docs/man-tree-on-build branch from bac7260 to 3002378 Compare June 4, 2026 01:27
@grandixximo
docs(build): relocate generated manpages under docs/build/man/, build…
9e240de 
… translated

Move the generated troff manpage tree out of the source tree into
docs/build/man/.  Layout follows the /usr/share/man hierarchy: English at
docs/build/man/manN (the C/default locale) and translations at
docs/build/man/<lang>/manN.  This differs on purpose from the
build/html/<lang> and build/adoc/<lang> convention, because man(1) resolves
a MANPATH entry by locale and LANG=C only checks <path>/manN; the English
special-casing is documented in the Submakefile header.  docs/man/ is
removed; nothing generated lives in the source tree anymore.

- docs/src/Submakefile: add DOC_MAN; repoint manpage generation, MAN_SRCS,
  MAN_HTML_RULE, gen_complist prereq, MAN_DEPS and clean targets.
- Build translated manpages: po4a emits the [type: man_def] comp manpages
  straight to build/man/<lang>/, and TRANSLATED_TROFF_RULE renders the
  .adoc-sourced manpages from build/adoc/<lang>/man into build/man/<lang>/;
  per-language HTML reuses MAN_HTML_RULE.
- comp/driver/user_comp manpages (src/hal/.../Submakefile) and linuxcnc.1
  now emit to docs/build/man/manN.
- po4a.cfg: point the [type: man_def] entries at build/man/ for both master
  and per-language output (structural paths only; no translatable strings).
- install-man + swish index (src/Makefile), Doxygen MAN_OUTPUT, halcompile
  run-in-place fallback, gen_complist paths, and the run-in-place MANPATH
  (rip-environment) all follow.
- docs/.gitignore: drop the obsolete man/ ignores; build/ already covers them.
- delete the unreferenced legacy groff_www assets rather than carry them into
  the new tree (Bertho confirmed unused): an-old-fixed.tmac, man/images/, and
  both stylesheet.9 copies (docs/man/ and src/hal/components/).  These were the
  old groff -Thtml pipeline (.HEAD CSS injection, wavedrom waveform images),
  obsolete since component manpages render through asciidoctor.
- tutorial.adoc: update the `man -M` example path.
@grandixximo grandixximo force-pushed the docs/man-tree-on-build branch from 3002378 to 9e240de Compare June 4, 2026 01:37
@grandixximo
Copy link
Copy Markdown
Contributor Author

grandixximo commented Jun 4, 2026

There is one thing I just noted again. The man-page translations are made on basis of the troff output and not on basis of the adoc sources. That will have to change too, eventually. Probably best not to do it with this PR, but this is should be a reminder. Probably best done when we separate man-page pot/po out of main body.

The build output put that into your mind but it is actually building the html man pages from the adoc sources.

See this fix: #4117

Thought he was talking about man_def, that 'leg' still on troff. I'm refactoring a bit this PR, building all man in english when not translated, like that we have all main page links populated, so they can be navigated to and will have tag from topbar when merged that will show ..% translated

@grandixximo
docs(build): render the full manpage set in every language
a2b3fb4 
Translated landing pages now list and link the same manpages English
does, rather than only the ~205 that have a po4a translation.  Each
language renders all 455 manpages: translated where a po4a leg provides
it (AsciiDoc_def adoc or man_def troff), English fallback otherwise.  The
per-page completeness is for the topbar banner (separate branch) to show.

- MAN_HTML_TARGETS_<lang> is the full English stem set, not just the
  AsciiDoc_def stems.
- MAN_ENONLY_TROFF_RULE copies the English troff for stems with no po4a
  entry (man3 API reference, a few man1/man9) so they have a per-language
  prerequisite; install ships English man only, so no install impact.
- MAN_HTML_RULE gains committed-src and en-generated adoc fallbacks so
  man_def-only and generated manpages (matrix_kb.9, linuxcnc.1) resolve
  their English adoc per language instead of erroring.
- Per-language index.html appends the English manpage index; with full
  parity every relative man/ href resolves under <lang>/man/.

Clean -j8 htmldocs: 386s -> 465s (+79s) for the extra per-language
renders.
@grandixximo
docs(build): index.incl depends on English man list, not full 9-lang
06df292 
With every language rendering the full manpage set, MAN_HTML_TARGETS
grew to ~4000 paths; echoing it into objects/var-MAN_HTML_TARGETS made a
single bash argument over Linux's 128 KiB MAX_ARG_STRLEN, so CI htmldocs
failed with 'Argument list too long' (passed locally on shorter paths).
index.incl is built only from MAN_HTML_TARGETS_EN, so depend on that var
instead: ~9x smaller, well under the limit, and it no longer rebuilds
when a translation changes.
@grandixximo grandixximo mentioned this pull request Jun 4, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@grandixximo @BsAtHome @hansu