source format vs info/html

Posted Dec 11, 2014 5:00 UTC (Thu) by sfeam (subscriber, #2841)
In reply to: source format vs info/html by madscientist
Parent article: Emacs and changing documentation formats

Let me speak up for an opposing viewpoint. Info is IMHO the worst tool for documentation that has ever been invented, or at least the worst I have ever had to deal with. Plain ascii text is better. Plain anything is better. I have used info2xxx converters whenever I must deal with documentation that is available no other way. These are in my experience rather hit-or-miss, but even a miss is better than the original. I suppose that one or more of these converters could be improved, but permanently replacing the original *.texi or *.info files with something else would be preferable.

I get it that you are talking about viewing docs in emacs rather than in info, but for us non-emacs people that only makes it worse. Do you not care that you are restricting docs to emacs users?

So yeah - I care. If you maintain documentation in texinfo format please consider converting it to something more user friendly.

source format vs info/html

Posted Dec 11, 2014 9:18 UTC (Thu) by drothlis (guest, #89727) [Link] (4 responses)

I thought this article was about Emacs documentation -- why would it matter to a non-Emacs user if the Emacs documentation uses info?

source format vs info/html

Posted Dec 11, 2014 14:30 UTC (Thu) by pj (subscriber, #4506) [Link] (3 responses)

...because all Emacs users start out as non-Emacs users? IMO you're limiting your adoption audience by sticking to info-only docs - adding another skillset (using info) to the list of things they have to learn in order to use Emacs. Wouldn't it be better for a newbie to be able to learn Emacs by reading docs using methods they already know (web/html) ?

source format vs info/html

Posted Dec 11, 2014 17:27 UTC (Thu) by drothlis (guest, #89727) [Link] (2 responses)

Emacs (and every other GNU project I know of) host publically available html versions of their documentation, generated from the texinfo sources. See https://www.gnu.org/software/emacs/manual/emacs.html

source format vs info/html

Posted Dec 13, 2014 20:35 UTC (Sat) by alfille (subscriber, #1631) [Link]

I followed that link. It's a very poor example of introductory documentation. Irrelevant choices (documentation format is the first choice), not even saying what the program is for! A long list of pages, including all the examples having equal priority.

Note this is much more a problem of documentation writing and exposition. Most modern languages and programs start with a simple enticing approachable use case, highlight the features and advantages, and then offer increasing detail.

source format vs info/html

Posted Dec 13, 2014 21:07 UTC (Sat) by mgedmin (subscriber, #34497) [Link]

Every time I have to look something up in the GNU Make manual I wish the FSF would hire a web designer.