Emacs and changing documentation formats

Posted Dec 11, 2014 0:25 UTC (Thu) by josh (subscriber, #17465)
Parent article: Emacs and changing documentation formats

I'd certainly love to see the GNU project as a whole migrate away from Texinfo. TeX and LaTeX are incredible tools for typesetting and producing PDF/PostScript, but very poor tools for producing HTML, man, or plain text, all critical formats for documentation. Texinfo is slightly better at producing HTML, but it still feels like an afterthought.

I'm not entirely convinced that AsciiDoc is the right choice of format to migrate to, but it's a major improvement, and there's no sense letting the perfect be the enemy of the good here.

While it isn't critical for emacs documentation, I *do* hope that in the future, GNU projects will start having first-class manual pages again, rather than having downstream distributions write and bundle them.

Emacs and changing documentation formats

Posted Dec 11, 2014 15:05 UTC (Thu) by nix (subscriber, #2304) [Link]

It's very bad for Emacs documentation. As mentioned, there is no index, there is no viewer, the markup is notably worse, Emacs already *has* a consistent documentation language which is really quite easy to get to grips with... there are no upsides to this idiotic proposal and a great deal of downsides. The nakedly political way ESR tried to force this through despite his utter ignorance of the field suggests that he knew this damn well (e.g. getting RMS's approval-in-principle rather than that of the people who actually write the docs, and he didn't know makeinfo could produce HTML, which suggests he didn't even try to run makeinfo --help).

This is just another one of ESR's odious attention-grabbing moves. If this actually happens, which I doubt, he'll run off and leave other people to pick up the mess. Again.

Emacs and changing documentation formats

Posted Dec 12, 2014 12:26 UTC (Fri) by jschrod (subscriber, #1646) [Link]

> TeX and LaTeX are incredible tools for typesetting and producing
> PDF/PostScript, but very poor tools for producing HTML, man, or plain
> text, all critical formats for documentation.

I don't understand this sentence, in context of the article's topic. The only task of TeX at hand is to produce typeset versions of a Texinfo documentation (PDF/Postscript). LaTeX is not involved at all.

Creation of other formats is the task of makeinfo, which can produce Docbook, HTML, XML, plain text, and, of course, Info.

man pages are not supported by makeinfo, granted -- but that is IMHO quite difficult, as the structure of a user manual or programming language manual (that's what Texinfo is used for most often) and of a man page is often quite different. I expect from a man page sections like NAME, SYNOPSIS, DESCRIPTION, OPTIONS, etc., -- all of them not appearing in that way in a user manual.

So please, would you please care to explain what your (correct) notion that TeX is a poor tool to produce HTML or plain text has to do with the actual tool (makeinfo) that is used to produce these formats?

> Texinfo is slightly better at producing HTML, but it still feels like
> an afterthought.

Since makeinfo creates Info, the raison d'etre of Texinfo, it is unlikely to be an afterthought itself. HTML creation is surely implemented later, as Texinfo existed before HTML. Since Texinfo markup was a major influence in shaping the HTML markup tags, it's not difficult. Existing styles are dreadful, though; some designer's work would be handy.

Your first paragraph can be interpreted as if you think that Texinfo has something to do with TeX or LaTeX (maybe because it starts with the same two [sic!] characters as TeX?). It hasn't. AFAIR, it might even predate LaTeX. (FWIW: I'm involved in the development of TeX and LaTeX, but not of Texinfo.)