Hi Fabrice, Thanks for the pointer. Pandoc however seems to be able to convert only _to_ Asciidoc, not _from_ Asciidoc (by looking at https://pandoc.org/). Anyway, thanks to some regex I managed to upgrade the format of the Asciidoc documentation from the legacy format to the "modern/current" Asciidoc format.
I have updated the PR at https://github.com/zeromq/libzmq/pull/4607 Documentation rendered as Github Pages in my own fork: https://f18m.github.io/libzmq/ Any comment is welcome Thanks, Francesco Il giorno mar 24 ott 2023 alle ore 09:20 Fabrice Bacchella < [email protected]> ha scritto: > Did you try pandoc ? > > Le 23 oct. 2023 à 23:16, Francesco <[email protected]> a écrit > : > > Update: apparently the point a) is blocked by point b). > > In more details: the Asciidoc modern syntax to get a cross-reference > correctly rendered in both manpages and HTMLs is: > > xref:name_of_doc.adoc[name_of_doc] > > This will produce a valid link to "name_of_doc.html" for HTML output and a > simple "name_of_doc" span of text for manpage output. This is the fix > mentioned in step a). > However this syntax is accepted only when Asciidoctor is NOT running in > legacy/deprecated mode. > To avoid that, I first need step b). > > Shall I put steps a) and b) together in my same WIP PR ? > It will be harder to review it... > > thanks > > > Il giorno lun 23 ott 2023 alle ore 22:43 Francesco < > [email protected]> ha scritto: > >> Hi all, >> >> Here's an update on my attempt to refresh the doc system for libzmq API. >> >> *Current status:* >> libzmq is built around the "ancient" python Asciidoc tool. That tool is >> unmaintained for several years and has been replaced by the Asciidoctor >> tool (see >> https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/). >> Note that the original tool used for interpreting the .txt files was >> named "asciidoc" just like the language markup contained in the .txt files >> itself. To avoid confusion, that tool is now referred to as "asciidoc-py". >> The tool asciidoc-py is the one unmaintained. The language Asciidoc >> itself instead is still maintained and developed, but Asciidoctor is the >> only updated tool to process Asciidoc documents. >> The manpages are built today in libzmq through this chain: >> .txt --[asciidoc]--> .xml docbook --[xmlto]--> .3 or .7 >> manpages >> where the [] indicate the tool used for the conversion. Also the >> utility "xmlto" seems quite unmaintained. >> Finally the wikidot website http://api.zeromq.org/ is built from some >> scripts located in the "ztools" repo that basically leverages the ability >> of that wiki to produce a listing of all wiki pages uploaded by group; the >> group used is the ZMQ API version. This makes it possible to document >> multiple versions of the libzmq API in the same website/wiki. However >> wikidot itself seems unmaintained as well. >> >> *Where I got so far:* >> I managed to convert to obtain usable and nicely-formatted HTML docs >> running Asciidoctor on libzmq docs, after some mass-replacement passes to >> fix some syntax issues. >> Asciidoctor is still processing all libzmq docs using the so-called >> "compatibility mode". >> In my libzmq fork I enabled Github pages and I got them deployed on >> every checkin of my branch. >> Documentation rendered as Github Pages in my own fork: >> https://f18m.github.io/libzmq/ >> PR: https://github.com/zeromq/libzmq/pull/4607 >> >> *Next steps:* >> a) I'm fighting a little bit with Asciidoctor to get the right >> rendering also for manpages. >> b) Some smart mass-replace is still needed to convert from the >> deprecated Asciidoc format to the "modern" Asciidoc (see >> https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax >> ) >> c) The Github pages approach is able to deploy only the documentation >> for the latest "master" branch. Maintaining documentation for the multiple >> API versions is probably best achieved using the more popular >> readthedocs.io. As pointed out already in this email thread, >> readthedocs.io is mostly designed around Sphinx and MkDocs but most >> recent versions are flexible enough to accomodate also Asciidoc >> documentation. I think eadthedocs.io is the best solution to store >> different versions of libzmq API. >> >> Please let me know if you have any comments. >> In my opinion to simplify the PR review, after step a) it's best to do a >> first merge, and then carry out points b) and c) in 2 more separate PRs. >> >> What do you think? >> >> Thanks, >> >> >> >> Il giorno ven 20 ott 2023 alle ore 18:19 Brett Viren < >> [email protected]> ha scritto: >> >>> On Fri, Oct 20, 2023 at 12:03 PM Francesco <[email protected]> >>> wrote: >>> > >>> > Maybe an even simpler solution is to activate the Github "Pages" >>> support in libzmq.org and link it with a github action that just uses >>> the Asciidoctor generator to convert all of doc/*.txt into static HTML. >>> > >>> > What do you think about this? >>> >>> This sounds like a very good idea to me. And, it's even easier as the >>> existing libzmq build already produces the HTML. >>> >>> On could prototype some additional build action that populate the >>> special gh-pages by committing these generated HTML files. This can >>> be tested using a personal fork of libzmq to make your own >>> https://<name>.github.io/libzmq/. When that works, a PR to libzmq >>> would be needed. Bonus if some .github/ CI bits could automate this. >>> And, someone with GitHub permissions would need to go into libzmq's >>> repo settings to turn on the publish setting. >>> >>> -Brett. >>> _______________________________________________ >>> zeromq-dev mailing list >>> [email protected] >>> https://lists.zeromq.org/mailman/listinfo/zeromq-dev >>> >> _______________________________________________ > zeromq-dev mailing list > [email protected] > https://lists.zeromq.org/mailman/listinfo/zeromq-dev > > > _______________________________________________ > zeromq-dev mailing list > [email protected] > https://lists.zeromq.org/mailman/listinfo/zeromq-dev >
_______________________________________________ zeromq-dev mailing list [email protected] https://lists.zeromq.org/mailman/listinfo/zeromq-dev
