Francesco <[email protected]> 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. _______________________________________________ zeromq-dev mailing list [email protected] https://lists.zeromq.org/mailman/listinfo/zeromq-dev
