docs: fix the two remaining htmldocs CI warnings - #4410
Merged
Conversation
The three links to the LinuxCNC realtime check used inter-document xref syntax (xref:python-lcnc_realtime.adoc[]). The documentation is built as a single book, so asciidoctor emitted href="#python-lcnc_realtime.adoc", a fragment that does not exist anywhere in the output. htmlcheck.sh reported the resulting broken fragments for every language. Use the anchor the target chapter actually declares, <<cha:python-lcnc_realtime>>, matching the reference style already used in hal/halmodule.adoc.
The rc.local example was written as a markdown-style ``` fenced block. Asciidoctor renders that correctly for English, but po4a's asciidoc parser does not recognise the fences: it extracts the block as an ordinary paragraph and reflows it onto one line. In every translated build the opening fence then read as an unterminated listing block, so asciidoctor warned about it and swallowed the rest of the page. The German manpage, for example, lost the NOTE, AUTHOR and LICENSE sections entirely and put the shell commands in a data-lang attribute. With a proper ---- listing block po4a classifies it as a verbatim block and keeps the line breaks, and the translated pages render in full.
Contributor
Author
|
no warnings 🌞 |
Contributor
|
One new bummer from me and one old one, it seems ;-) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clears the two remaining
htmldocsCI warnings.python-hal-interface.adocused inter-document xref syntax,xref:python-lcnc_realtime.adoc[]. The docs build as one book, so it renders ashref="#python-lcnc_realtime.adoc", a fragment that does not exist;htmlcheck.shflagged it in all eight languages. Now<<cha:python-lcnc_realtime>>, the anchor the target chapter declares.The rc.local example in
hm2_rpspi.9.adocused a markdown ``` fence. po4a does not recognise fences and reflows the block onto one line, so every translated build hitunterminated listing blockand lost the rest of the page (the German manpage drops NOTE, AUTHOR and LICENSE). A plain `----` listing block fixes it; po4a then keeps the line breaks.