[zeromq-dev] ZeroMQ docs

[Brett Viren]

Francesco <francesco.montorsi at gmail.com> writes:

> 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]

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.

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)?

Given the similarity between asciidoctor and markdown syntax, this
change would not be so large for both human editors and the
mass-replacement you are developing.  The additional benefit is that
having the API docs in markdown syntax would give libzmq more options
for building end-user document formats.

I guess these docs will not see much change going forward but as someone
who recently contributed a new one I can say that process would have
been easier if the API docs were in markdown format.  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.

-Brett.