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] <mailto:[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 >> <http://readthedocs.io/>. As pointed out already in this email thread, >> readthedocs.io <http://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 <http://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] >> <mailto:[email protected]>> ha scritto: >>> On Fri, Oct 20, 2023 at 12:03 PM Francesco <[email protected] >>> <mailto:[email protected]>> wrote: >>> > >>> > Maybe an even simpler solution is to activate the Github "Pages" support >>> > in libzmq.org <http://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/ <http://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] <mailto:[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
