source format vs info/html

Posted Dec 12, 2014 3:49 UTC (Fri) by sadboy (guest, #94691)
In reply to: source format vs info/html by rsidd
Parent article: Emacs and changing documentation formats

> So, what does info offer that HTML-ised manpages don't?

Searchable index.

source format vs info/html

Posted Dec 12, 2014 9:36 UTC (Fri) by rsidd (subscriber, #2582) [Link] (1 responses)

I think the problem with "info" is multiple pages. "man" is just faster to use, and searching is a question of hitting the / key and typing what you want. The concept of a "page" is an artifact of print media, anyway -- "sections" are enough structure for on-screen reading. There are a few programs for which a single-page manual may be unwieldy (ie, they may require "chapters" not just "sections"), but it's not worth the effort to learn to use info just for those...

source format vs info/html

Posted Dec 12, 2014 20:10 UTC (Fri) by rgmoore (✭ supporter ✭, #75) [Link]

There are a few programs for which a single-page manual may be unwieldy (ie, they may require "chapters" not just "sections"), but it's not worth the effort to learn to use info just for those...

Still, there are still some programs that have documentation for which a single-page manual is unwieldy*- emacs being a classic case, in fact- and they need real solutions. The fraction of programs that need more complex manuals isn't necessarily justification for ignoring them, either. Critical tools are more likely to require complex documentation, so the need to work with it is greater than implied by the simple number of programs that require it. There's also the general tendency of better tools to produce a better product; maybe Unix/Linux documentation would be better if documentation writers had been focusing on a better target than man pages.

*This isn't purely a matter of size, either. Single-page documents force a linear structure on the documentation that is often inappropriate for a comprehensive manual.