Hi, Wolfgang Corcoran-Mathe <xxxxxx@sigwinch.xyz> writes: [...] > You could just as well recommend a specific version of HTML (preferably > without dynamic elements). XHTML and HTML 4.01 are well-defined, > and probably easier to parse than most of the manpage or "quick" > documentation formats out there. But SRFIs authors basically use what > they want, and, with the unbounded expansion of WHATWG HTML, some of > them want plenty. This is an issue with a large social component, > in other words. It'd be nice if there was a requirement for authors to stick to what's used in the HTML SRFI document template; but yeah with HTML being very large and flexibly there's always going to be some wiggle room that will make a good tool to transform from HTML to something else (PDF, Info, Groff, etc.) difficult (has anyone tried pandoc? My experience with it is that it's output is useful/good, but far from perfect). > After doing R7RS small in both Texinfo and DocBook, I personally believe > Texinfo is the worse of the two, when it comes to describing documents. > Its tree-structuring is weak, compared to the XML format. (texi2any > does the best it can, but it’s pretty hard to translate texinfo > to *good* XML, for example.) Texinfo is OK — it’s an incremental > improvement on the old troff macros — but it is not much of a semantic > format, and it’s certainly not the panacea some GNU folks seem to > believe it is. I believe the strength of Texinfo lies not in its data representation but in the existing tooling around it that allows generating high quality documents in various formats, such as PDF or HTML, along Info, which is pretty handy with automatically handling indexing of procedures (as long as they are declared as such) and is still very usable even from a terminal emulator, if you must (I'd argue more than an HTML page thanks to the keyboard-based navigation and indices). It also strikes a good balance of being human readable in source form, thus natural/easy to author. It reminds me a bit of (La)TeX, which places the focus on the content rather than the minutia of presentation details. Finally, it's actively used to document Guile (and Guix, along other projects), and there is a Scheme module for manipulating Texinfo already in Guile (for parsing, rendering or serializing it for example) in (info "(guile) Texinfo Processing") or <https://doc.guix.gnu.org/guile/latest/en/html_node/Texinfo-Processing.html> -- Thanks, Maxim
