[zeromq-dev] ZeroMQ docs

[Francesco]

Hi Brett,


FWIW, I think it is very reasonable to accept some syntax change in
> order to migrate to a better supported document compiler and to gain the
> new functionality of readthedocs.  So, for whatever it may be worth, I
> take back my initial opinion to leave the API .txt files as-is.
>

Actually in my PR I'm proposing to rename all .txt files to .adoc to
clarify they use Asciidoc syntax. It's clearly the correct extension that
should be used according to Asciidoc online resources.
As per the content: I migrated them to use the more modern asciidoc syntax.


> Francesco, I know you have already invested effort down the asciidoctor
> path but maybe it is worth considering to jump fully to a flavor of
> markdown (eg github's)?
>

I'm not sure. Of course they're biased but Asciidoc community claims to be
better and a "more sound alternative" to Markdown, see:
   https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

A less-biased comparison (much longer to read -- I didn't read it all) is
at:
  https://www.dewanahmed.com/markdown-asciidoc-restructuredtext/


Actually, when I
> started writing I half assumed they were in markdown and half assumed
> they were in some special markdown'ish GSL syntax and only later figured
> out they were asciidoc.  But then I got confused about how to compile them
> (ie,
> asciidoc-py vs asciidoctor that you described).  Certainly, my stumbles
> were due to my ignorance/assumptions but had the docs been in markdown,
> all these little frictions would not have shown up.  Again, opinion fwiw.
>
I totally agree.
I also contributed some fixes/new features in the past and documenting them
was tricky. The .txt extension does not help at all.
The use of archaic tools makes it very hard to the "casual" contributor to
see the actual documentation rendered.
Even more tricky: I was expecting api.zeromq.org to automatically get
updated after some time the PR was merged... I discovered it's not the case
:)

Last but not least: my use case for spending a few hours on this PR /
documentation improvement was very simple: I noticed a very nice new option
(ZMQ_BUSY_POLL) in the release notes. Then I started to search for docs to
share with the rest of the teams. I found only the .txt version, nothing I
could easily link in an email or share with simplicity... that was the
trigger point... :)


Thanks,
Francesco
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20231024/7f8c937a/attachment.htm>