Move away from DocBook for documentation #1588
Comments
|
It has been suggested to me that Commonmark can be localized with po4a. It would be a big plus to have a more efficient way to manage the Japanese localization. |
|
@NJRoadfan Heads-up: My current thinking here is to add a I have found a workflow for automatically converting docbook to markdown fairly painlessly. Only minor manual cleanup needed in the header and synopsis. Here's how the aecho man page looks in markdown format:
% aecho(1) Netatalk @netatalk_version@ | Netatalk AFP Fileserver Manual
# Name
aecho - send AppleTalk Echo Protocol packets to network hosts
# Synopsis
`aecho [-c count] [ address | nbpname ]`
# Description
`aecho` repeatedly sends an Apple Echo Protocol (AEP) packet to the host
specified by the given AppleTalk `address` or `nbpname` and reports
whether a reply was received. Requests are sent at the rate of one per
second.
`address` is parsed by `atalk_aton(3)`{.citerefentry}. `nbpname` is
parsed by `nbp_name(3)`{.citerefentry}. The nbp type defaults to
\`*Workstation*\'.
When `aecho` is terminated, it reports the number of packets sent, the
number of responses received, and the percentage of packets lost. If any
responses were received, the minimum, average, and maximum round trip
times are reported.
# Example
Check to see if a particular host is up and responding to AEP packets:
example% aecho bloodsport
11 bytes from 8195.13: aep_seq=0. time=10. ms
11 bytes from 8195.13: aep_seq=1. time=10. ms
11 bytes from 8195.13: aep_seq=2. time=10. ms
11 bytes from 8195.13: aep_seq=3. time=10. ms
11 bytes from 8195.13: aep_seq=4. time=10. ms
11 bytes from 8195.13: aep_seq=5. time=9. ms
^C
----8195.13 AEP Statistics----
6 packets sent, 6 packets received, 0% packet loss
round-trip (ms) min/avg/max = 9/9/10
# Options
`-c` \<count\>
: Stop after *count* packets.
# See Also
`ping(1)`{.citerefentry}, `atalk_aton(3)`{.citerefentry},
`nbp_name(3)`{.citerefentry}, `aep(4)`{.citerefentry},
`atalkd(8)`{.citerefentry}.
# Author
See [CONTRIBUTORS](https://netatalk.io/contributors)Then turn this into a troff man page with: Note that the By using markdown, web publishing and localization will become much easier and more flexible. |
|
Linux distros and BSDs are all distributing pandoc packages. But the situation in Solaris land is dire. Oracle Solaris does not ship a package AFAICT, while SmartOS pkgsrc (via OmniOS) does. However, it takes over 5 minutes just to install all Haskell dependencies, and after that Meson still cannot detect the pandoc program... I think the reasonable option here would be to go back to distributing pre-generated troff man pages. A bit of a step backwards, but the upsides with pandoc and markdown for documentation make up for it I think. |
|
This is what a plain commonmark version of the above would look like. The one additional manual adjustment needed is to indent items in the definition list, which can be done with a global search and replace. The biggest drawback is that we won't get any man page headers, which looks a little empty. On the plus side, this is entirely standards compliant markdown, without pandoc extensions. And, we can use the extremely fast and portable cmark app to generate the troff pages on the fly. So no need for a intermediate step, or heavy Haskell stack... # Name
aecho - send AppleTalk Echo Protocol packets to network hosts
# Synopsis
`aecho [-c count] [ address | nbpname ]`
# Description
`aecho` repeatedly sends an Apple Echo Protocol (AEP) packet to the host
specified by the given AppleTalk `address` or `nbpname` and reports
whether a reply was received. Requests are sent at the rate of one per
second.
`address` is parsed by `atalk_aton(3)`. `nbpname` is parsed by
`nbp_name(3)`. The nbp type defaults to \`*Workstation*'.
When `aecho` is terminated, it reports the number of packets sent, the
number of responses received, and the percentage of packets lost. If any
responses were received, the minimum, average, and maximum round trip
times are reported.
# Example
Check to see if a particular host is up and responding to AEP packets:
example% aecho bloodsport
11 bytes from 8195.13: aep_seq=0. time=10. ms
11 bytes from 8195.13: aep_seq=1. time=10. ms
11 bytes from 8195.13: aep_seq=2. time=10. ms
11 bytes from 8195.13: aep_seq=3. time=10. ms
11 bytes from 8195.13: aep_seq=4. time=10. ms
11 bytes from 8195.13: aep_seq=5. time=9. ms
^C
----8195.13 AEP Statistics----
6 packets sent, 6 packets received, 0% packet loss
round-trip (ms) min/avg/max = 9/9/10
# Options
`-c` \<count\>
> Stop after *count* packets.
# See Also
`ping(1)`, `atalk_aton(3)`, `nbp_name(3)`, `aep(4)`, `atalkd(8)`.
# Author
See [CONTRIBUTORS](https://netatalk.io/contributors) |
Leveraged pandoc's docbook filter to convert to CommonMark, then cmark-gfm (or cmark for man pages only) to transcode to roff or html. Introduces with-docs, with-docs-l10n, and with-website Meson options.
Leveraged pandoc's docbook filter to convert to CommonMark, then cmark-gfm (or cmark for man pages only) to transcode to roff or html. Introduces with-docs, with-docs-l10n, and with-website Meson options.
Leveraged pandoc's docbook filter to convert to CommonMark, then cmark-gfm (or cmark for man pages only) to transcode to roff or html. This gives us a much, much leaner toolchain for generating documentation through the build system. No need to provide the heavy XML and Docbook suites. Localization is done with po4a, which uses gettext in the backend. Introduces with-docs, with-docs-l10n, and with-website Meson options.
Leveraged pandoc's docbook filter to convert to CommonMark, then cmark-gfm (or cmark for man pages only) to transcode to roff or html. This gives us a much, much leaner toolchain for generating documentation through the build system. No need to provide the heavy XML and Docbook suites. Localization is done with po4a, which uses gettext in the backend. Introduces with-docs, with-docs-l10n, and with-website Meson options.
Leveraged pandoc's docbook filter to convert to CommonMark, then cmark-gfm (or cmark for man pages only) to transcode to roff or html. This gives us a much, much leaner toolchain for generating documentation through the build system. No need to provide the heavy XML and Docbook suites. Localization is done with po4a, which uses gettext in the backend. Introduces with-docs, with-docs-l10n, and with-website Meson options.
The DocBook toolchain relies on XML parsing and XSL stylesheets that is heavy, complex, and partially on the verge of obsolescence.
For one, we use traditional non-namespaced DocBook XSL style sheets which are two generations behind where DocBook is today. The docbook-xsl package is orphaned in Debian, for instance.
Another concrete drawback is that Debian tries to proactively strip XML related dependencies from architecture dependent builds, to save on computing resources and speed up builds. But this can’t be done for netatalk because of how we generate the troff man pages from XML.
This is to look into converting the documentation sources to a markup format that is parseable by pandoc, such as Commonmark. This would allow us to transcode to human readable formats with the light-weight cmark.
The text was updated successfully, but these errors were encountered: