Emacs and changing documentation formats
The GNU Emacs project is debating the idea of changing the format in which its official documentation is written and maintained. Proposing the change is Eric S. Raymond, who argues that the Texinfo format currently used is archaic and constitutes a barrier to entry. His proposal has its supporters—including Richard Stallman—but plenty of other project members contend that whatever shortcomings the Emacs documentation may have, replacing Texinfo as Raymond suggests is not the fix.
For those unfamiliar with it, Texinfo is a GNU project with a long history. It is the format behind the command-line info tool (although Emacs uses its own, built-in info page browser) and is the officially blessed manual format for all GNU projects. The syntax itself is akin to many other text-markup formats, but it was designed with structured, cross-referenced user manuals in mind. Thus, it provides some features not found in other markup languages. The most prominent example is its support for document-wide indexes. In addition to their usage in terminal commands like info, Texinfo documents can also be converted to HTML or (through TeX) to print-quality PostScript output. Texinfo is used by a number of non-GNU projects as well; users may have encountered reference to info documents from Linux man pages.
On December 5, Raymond wrote to the Emacs development list to announce his intention to migrate the project's documentation away from GNU's Texinfo as its master format, in order to adopt AsciiDoc instead. Raymond's message came on the heels of a lengthy discussion thread about attracting and retaining new contributors, which is certainly an issue most free-software projects can relate to. In the earlier discussion, several barriers to entry for newcomers were mentioned, such as the fact that Emacs's official how-to-contribute document is a text file installed in a local directory, rather than a web page.
Raymond cited that concern in his message, saying that
" I have discussed this with RMS and, pending my ability to actually write
proper translation tools, we have agreed on asciidoc as a new master
format.
Raymond volunteered to take on the " As might be expected for a change as large as the one proposed,
reaction to Raymond's email was varied. Several list members
expressed support, although many of those who supported the idea of
dropping Texinfo favored other documentation formats. Plenty of
others were opposed, either on the grounds that Raymond's assessments
of suitability of the various documentation formats were off or out of
conviction that the costly migration proposed would do little if anything
to increase the ranks of Emacs contributors.
Chris Webber was one of the first to register agreement with Raymond's dissatisfaction
about the status quo, but he called the choice of AsciiDoc as an
alternative " Altogether, AsciiDoc did not seem to elicit much support from list
members. In fact, among those who agreed that Texinfo should be
replaced, there were more voices in favor of adopting Emacs's Org mode for the markup style of choice than any other option. Rasmus Pank
Roulund raised the idea first, noting
that Emacs does not have a reliable editing mode for AsciiDoc and, at
present, AsciiDoc tools can only generate HTML output. Org mode, in contrast, is
well-supported in Emacs and can generate output in a variety of
formats.
Raymond, both in his reply to Webber and elsewhere, responded that
Org-mode markup would be a poor choice for a documentation format
because its use is too limited to the existing Emacs community:
Stallman also weighed in on that
suggestion, initially dismissing Org mode because it is a program, not
a format, and furthermore it is a program that only runs within Emacs.
Org mode's supporters, like Achim Gratz, disagreed, pointing to several other
org-mode compliant programs and the official specification
for the syntax. Stallman subsequently conceded the points, concluding:
Then there will be no reason to insist on one particular source format
for manuals for GNU packages. We could allow any source markup format
that can generate the three kinds of output we want:
* Nicely formatted PS or PDF. (Ideally, passed through TeX.)
* HTML used like Info version 2.
* Plain ASCII.
If Org format can do these jobs, it would be one of the
acceptable source markup formats.
However, there is far from any consensus as to whether or not Org
mode's syntax—or, for that matter, AsciiDoc's—is better
than Texinfo's. In fact, it has proven fairly difficult to come to
any agreement on what better means in this context. Raymond
contended that Texinfo syntax involves
duplicating a document's structure in several places, and said he appreciates the fact that
AsciiDoc is readable as plain text. " In contrast, David Kastrup said
that " A number of people also pointed out that, contrary to Raymond's initial
claim, Texinfo can (and does) generate HTML content from its source
files. Rüdiger Sonderfeld pointed out
that Texinfo supports images and can produce eye-pleasing output,
citing GNU Octave as an example. Kastrup, similarly, pointed to LilyPond as a positive show piece.
On the other hand, the most oft-cited feature of Texinfo is its
support for indexes: when writing text, the user can add any term to
the manual's index with a markup tag, making the term easy to look up or
search for. The format comes with built-in support for a variety of
separate indexes, and adding additional indexes is relatively trivial.
Critics of the other formats discussed were quick to point out that
similar features are not available in the competition, but Eli
Zaretskii (Emacs's documentation maintainer), countered that it is not the ability to
mark up index entries that is the killer feature—rather, it is the
support in the various info browsers for searching the index of a manual.
Ultimately, arguments about markup formats are probably just as
doomed as arguments about programming languages: too many of the
perceived benefits and drawbacks come down to personal judgment calls
on which a large group of people will rarely reach a consensus. Most
of the list membership agreed that work could be done to improve the
HTML output generated for Emacs's documentation. The notion that a
different source format was required to improve the output, however,
was a harder sell.
But the proposed change in formats also encountered resistance on
another front: Raymond's assertion that switching to AsciiDoc would
attract more Emacs contributors. Several people, such as Ted
Zlatanov, did acknowledge that they
considered Texinfo " Kastrup, though argued that
switching formats might attract different people, but was
unlikely to attract more. Furthermore, switching formats
would likely have the unwanted effect of causing existing
documentation writers to lose interest. Zaretskii, for his part, called the AsciiDoc plan " Zaretskii also argued that:
Few documentation writers would likely disagree with that
sentiment. What is harder to assess, however, is the degree to which
Texinfo, AsciiDoc, or any other documentation tool plays a role in
attracting or repelling a hypothetical new recruit. Zaretskii's position is that " Reconciling those stances would not be easy under any
circumstances. It does seem, though, that Raymond may have made his
own task substantially more difficult by the manner in which he presented his
proposal. He approached the list with a solution already in hand—one
that seemingly arose from private conversation with Stallman and not
with Zaretskii or other Emacs documentation team members. It can
hardly be surprising, then, that his scheme was not received with
unbridled enthusiasm by the volunteers on whom he announced it would
be enacted.
Raymond, though, is certainly no stranger to controversy nor to the
job of pushing a project forward on a difficult change. He recently
spearheaded Emacs's move to Git revision control—a process that
was difficult and at times prickly to deal with, but one that most
people seem to regard as a good idea. He positioned dropping Texinfo
in favor of AsciiDoc as a similar endeavor: modernizing the project
for long-term benefit. But not all of Raymond's attempts to push the
bar forward are particularly successful; some may recall his ill-fated
mid-2000
effort to
radically rework the kernel configuration system.
Stallman's support can often be sufficient to push through even a major
change in Emacs, although at present it is not clear if strong
objections from Zaretskii and the other documentation authors is
enough to block the plan. It seems a bit unlikely that Raymond's
original changeover from Texinfo to AsciiDoc will be implemented as-is
(at least, without quite a bit more discussion),—although it is
interesting to note that Stallman has
exhibited a surprisingly open mindset about the possibility of
ditching Texinfo for other formats. But Raymond's proposal has
clearly prompted a number of Emacs contributors to take another look
at Texinfo's HTML output and the web presence of the project's documentation.
As Filipp Gunbin observed, most people's first instinct
when looking for an answer to a programming question is to search
online. Historically, Emacs has not optimized its documentation for
that approach. Whether the project can improve its documentation to
the level expected by adapting its tools to produce slicker-looking,
well-indexed HTML is hard to say—but there seems to be a
willingness to try.Emacs's web resources are weak, scattered, and
unfocused
", which he said was primarily because "
the Emacs
development culture is still largely stuck in a pre-Web
mindset
" that comes across to the public as behind-the-times.
And because the Emacs documentation is written in Texinfo, he said, it
actually is behind the times. He concluded by saying that a
change is required:
tools end
" of such
a change—starting with writing software to translate from
Texinfo to AsciiDoc—but called for someone else to take on the
"policy/organization end
" of the transition.
Formats and converts
very confusing
" and asked why it was it
chosen. Raymond replied that AsciiDoc
was in use by both the Git project and by Linux kernel developers
(although it was later pointed out that only
a small portion of the kernel's documentation makes use of AsciiDoc).
Moreover, AsciiDoc is "a modern, lightweight markup
in general use outside the Emacs project.
" Among the
other markup options, he said, Markdown suffers from a lack of
standardization (and he is not convinced the current standardization effort will bear fruit) and is not designed for structured documentation,
while reStructuredText
and Sphinx have not been adopted by as many
high-profile projects as AsciiDoc.
I get to write *foo*
instead of <emphasis>foo</emphasis> and you know what? It's better -
lower overhead not just in typed characters but in the amount of
attention required to read it structurally.
"
When looking at existing Texinfo source, I get a good idea of how to
write Texinfo markup of my own. When looking at AsciiDoc, I have no
clue since it is not apparent what is formatting, and what is
content.
"
Change
a nasty hurdle
", even discouraging
them from contributing documentation.
simply
insane
", given that Texinfo is the only source format in use by
the existing documentation authors.
until more people
start contributing to the docs, it makes very little sense to me to
change the tools
", which Raymond called "
exactly backwards
".
Posted Dec 11, 2014 0:25 UTC (Thu)
by josh (subscriber, #17465)
[Link] (2 responses)
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.
Posted Dec 11, 2014 15:05 UTC (Thu)
by nix (subscriber, #2304)
[Link]
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.
Posted Dec 12, 2014 12:26 UTC (Fri)
by jschrod (subscriber, #1646)
[Link]
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
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.)
Posted Dec 11, 2014 1:29 UTC (Thu)
by Per_Bothner (subscriber, #7375)
[Link] (63 responses)
Emacs does have a new web-browser feature (eww-mode). The best solution is to come up with an Emacs mode
that uses the
info-mode key-bindings and user interface, while processing
html files. (Possibly restricted to an html subset as might
be generated from texinfo.) There are additional problems: info mode has nicer index-search features which would need to be handled someway.
There is also the issue of whether eww-mode is up to the task, but
that can presumably be fixed.
It is quite possible to generate nice html web-pages from texinfo documentation.
The discussion mentioned LilyPond.
I will also point to my own Kawa website, the majority of which is generated from texinfo (via docbook).
Posted Dec 11, 2014 1:48 UTC (Thu)
by Per_Bothner (subscriber, #7375)
[Link] (2 responses)
A separate issue is that makeinfo, the primary tool form converting
texinfo documentation to other formats, is now over a magnitude slower than it was: Version 4 of makeinfo was written in C and very fast; version 5 was re-written in Perl and is very slow. Unfortunately the C version of makeinfo was hard to maintain and extend. No immediate solution is at hand. I would recommend taking makeinfo 5 as a prototype and re-writing it in C++, but that is moot without somebody volunteering to do the work.
Another point worth mentioning: The html you would want for you web site
would probably be different than the html you would want for a documentation browser. The former might want side bars with various links, for example; they would be clutter inside an Emacs window or standalone
documentation browser. But that's a matter of re-running makeinfo with different options. (In the Kawa case: For the website, I generate DocBook rather than html from the texinfo, and then a separate pass converts the DocBook to the desired web pages.)
Posted Dec 11, 2014 2:16 UTC (Thu)
by JoeBuck (subscriber, #2330)
[Link] (1 responses)
Posted Dec 11, 2014 2:45 UTC (Thu)
by Per_Bothner (subscriber, #7375)
[Link]
That assumes eww-mode has reasonable stylesheet support (which one hopes).
We would need to standardize how info-using-eww-mode (and similar documentation readers) selects a stylesheet other than the normally-default one.
Note that for a web-site you might want to do some extensive munging
or post-processing of the kind that wouldn't be appropriate to build into a makeinfo-like tool. You might also want to include dynamic content
such as "latest news" on your web site but not in a documentation reader.
Posted Dec 11, 2014 4:13 UTC (Thu)
by madscientist (subscriber, #16861)
[Link] (56 responses)
So I'll say to Eric et.al., please first solve all the issues with HTML that make it vastly inferior to info, or at least provide a concrete plan as to how they can be solved, then we can talk about switching all the documentation over to something else. This entire thing seems to me like inventing problems that don't actually exist: it's make-work. I've never had anyone suggest to me that the texinfo-based doc I maintain is too hard to read or should be written in some other format. People don't seem to care at all.
I have no problem admitting that the "default" HTML output format generated by texinfo is not always the most beautiful, but it seems clear to me that the biggest bang for the buck here would be to improve it, not try to reformat all the thousands of pages of texinfo documentation available today. If Eric is offering to spend time writing tools to do something, why not write that tool? There's absolutely nothing inherent to texinfo that makes it less suitable for HTML generation than AsciiDoc or any other markup format.
Posted Dec 11, 2014 5:00 UTC (Thu)
by sfeam (subscriber, #2841)
[Link] (5 responses)
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.
Posted Dec 11, 2014 9:18 UTC (Thu)
by drothlis (guest, #89727)
[Link] (4 responses)
Posted Dec 11, 2014 14:30 UTC (Thu)
by pj (subscriber, #4506)
[Link] (3 responses)
Posted Dec 11, 2014 17:27 UTC (Thu)
by drothlis (guest, #89727)
[Link] (2 responses)
Posted Dec 13, 2014 20:35 UTC (Sat)
by alfille (subscriber, #1631)
[Link]
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.
Posted Dec 13, 2014 21:07 UTC (Sat)
by mgedmin (subscriber, #34497)
[Link]
Posted Dec 11, 2014 5:09 UTC (Thu)
by b7j0c (guest, #27559)
[Link] (8 responses)
info is terrible and occupies a strange space between man pages and using elinks to look at web pages. i don't know anyone who likes info or targets it as a documentation platform.
Posted Dec 11, 2014 14:05 UTC (Thu)
by mpr22 (subscriber, #60784)
[Link] (5 responses)
I don't like /usr/bin/info very much, and I wouldn't write my own documentation in Texinfo, but on the other hand, I certainly wouldn't want to read the GNU Compiler Collection manual via any other mechanism.
Posted Dec 11, 2014 15:08 UTC (Thu)
by nix (subscriber, #2304)
[Link]
Sure, its HTML output is not particularly pretty -- but it is googleable (searching for e.g. 'Emacs point' finds the HTML version of the Info manual on the very first page) and thus sufficient for web-wedded Emacs users, if there are any. This all seems to me very much like a giant mass of work for less than no reward.
Posted Dec 13, 2014 20:47 UTC (Sat)
by paulj (subscriber, #341)
[Link] (3 responses)
The GNOME help viewer may also be used on some systems, e.g. try: yelp info:gcc.
Posted Dec 16, 2014 8:17 UTC (Tue)
by hickinbottoms (subscriber, #14798)
[Link] (2 responses)
Posted Dec 18, 2014 5:31 UTC (Thu)
by jzbiciak (guest, #5246)
[Link] (1 responses)
Pinfo has preserved my sanity many times as compared to Info.
I'm not an Emacs user (and so have no vested interest or opinion on how Emacs distributes its documentation). That said, 'info' pages pervade the GNU project and are in practice inescapable. So having something with a more approachable interface (without having to fire up a web browser) is very nice.
So add my vote for pinfo as well.
Posted Dec 18, 2014 15:54 UTC (Thu)
by dakas (guest, #88146)
[Link]
Yelp also is useless for browing Info files with substantial amounts of images. For example, starting it on the LilyPond notation manual (which contains thousands of images) will lock it up for some intolerable amount of time (I think the most I tried before aborting was an hour or so).
So the only competent Info reader supporting image display is Emacs. Which is a less than thrilling situation. On the other hand, Emacs' info reader knocks the pants off any other documentation viewing solution to a degree that is not even funny.
I have no good idea how to significantly improve this situation.
Posted Dec 18, 2014 15:44 UTC (Thu)
by dakas (guest, #88146)
[Link] (1 responses)
Man pages, in contrast, are again placed in centrally managed places and indexed with keywords (man -k ...).
So "html is what the world uses to distribute documents, not info." is just not true with regard to program documentation: HTML documentation tends to get dumped without love and reference and indexing tools in some local directory with non-standard paths differing from application to application, or it gets dumped somewhere on the Internet and good luck finding a version corresponding to your installed version and written in a competent manner rather than cobbled together from bits and pieces, possibly in a Wiki-like manner.
And it's not like you cannot produce HTML from Texinfo anyway. Info is just one output format from Texinfo, the one that is really *good* to use from inside of Emacs.
Posted Dec 19, 2014 13:11 UTC (Fri)
by cortana (subscriber, #24596)
[Link]
Posted Dec 11, 2014 5:39 UTC (Thu)
by rsidd (subscriber, #2582)
[Link] (5 responses)
Posted Dec 11, 2014 14:32 UTC (Thu)
by mpr22 (subscriber, #60784)
[Link]
Posted Dec 12, 2014 3:49 UTC (Fri)
by sadboy (guest, #94691)
[Link] (2 responses)
Searchable index.
Posted Dec 12, 2014 9:36 UTC (Fri)
by rsidd (subscriber, #2582)
[Link] (1 responses)
Posted Dec 12, 2014 20:10 UTC (Fri)
by rgmoore (✭ supporter ✭, #75)
[Link]
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.
Posted Jan 13, 2015 17:44 UTC (Tue)
by benbadge72 (guest, #100585)
[Link]
Posted Dec 11, 2014 20:19 UTC (Thu)
by fb (guest, #53265)
[Link] (34 responses)
I could /never/ figure out what was the point of using info or how to make proper use of it. At some point I just gave up. I'll either check a program's man page and if that does not answer, I'll search the web.
Whatever advantages info may have (to people that invest the time to learn it) IMHO they are all moot given the fact that, well, almost no one else uses it AND the fact that it has such a steep learning curve.
[...]
The entire planet uses HTML for documentation. Nearly no one uses info. You ought to reckon that there's got to be something that HTML got right.
Posted Dec 11, 2014 20:34 UTC (Thu)
by mpr22 (subscriber, #60784)
[Link] (1 responses)
I have no idea how one makes "proper" use of info. I just go "info $program_of_interest" in my shell, then use Ctrl-S (repeatable isearch - I believe this keybinding is itself an emacs-ism) to flip forward through the open info document in search of the term of interest. Occasionally I stray into using some of the other navigation keys (m, u, n, g, ENTER). (None of my computers even have emacs installed. On the computer someone else owns that I have a shell account on, I use emacs -f vm to read my e-mail.)
Posted Dec 18, 2014 15:58 UTC (Thu)
by dakas (guest, #88146)
[Link]
Also l for getting to the last page viewed before is nice particularly after following links.
Posted Dec 12, 2014 13:16 UTC (Fri)
by epa (subscriber, #39769)
[Link] (14 responses)
Posted Dec 12, 2014 19:20 UTC (Fri)
by sorpigal (guest, #36106)
[Link] (6 responses)
Posted Dec 18, 2014 20:05 UTC (Thu)
by Wol (subscriber, #4433)
[Link] (5 responses)
"Start at the beginning, finish at the end" is how I learnt to read, and it's still how I prefer to read.
Cheers,
Posted Dec 19, 2014 10:19 UTC (Fri)
by epa (subscriber, #39769)
[Link] (4 responses)
Posted Dec 19, 2014 11:00 UTC (Fri)
by sorpigal (guest, #36106)
[Link] (2 responses)
Posted Dec 19, 2014 19:55 UTC (Fri)
by bronson (subscriber, #4806)
[Link] (1 responses)
It's time for us to get over it. It's perfectly fine for a single HTML document to be 300 pages long, complete with a table of contents, index, and deep linking.
Posted Dec 20, 2014 16:22 UTC (Sat)
by Wol (subscriber, #4433)
[Link]
Sneakernet is still the best available if you're in the back of beyond (although what was that quote - never underestimate the bandwidth of a truck full of 9-track tapes ... ?)
Cheers,
Posted Dec 19, 2014 15:41 UTC (Fri)
by Wol (subscriber, #4433)
[Link]
Cheers,
Posted Dec 14, 2014 21:42 UTC (Sun)
by robbe (guest, #16131)
[Link] (6 responses)
Just checked again (I don't use /usr/bin/info very often):
$ info grub
So you can treat the info document just like any old manpage, and read it from beginning to end by just using your choice of the two key, conveniently compatible with our favourite pager. What confuses you? The additional whitespace at the end of chapters? Does
info PROGRAM 2>/dev/null | less
work better for you?
Posted Dec 15, 2014 18:18 UTC (Mon)
by nix (subscriber, #2304)
[Link] (2 responses)
It's improved. You might want to take a look. :)
Posted Dec 24, 2014 12:29 UTC (Wed)
by arafel (subscriber, #18557)
[Link] (1 responses)
Posted Dec 24, 2014 13:46 UTC (Wed)
by madscientist (subscriber, #16861)
[Link]
If you'd prefer to go to your browser, search for the location of the manual on the web, search around to find the index, then search to find "foo" (remembering that the version of the documentation on the website is always the latest version which may not match the version of software you have installed), rather than typing "info gcc <RET> i foo <RET>" and getting the exact correct documentation for your software version...
Well, that's up to you.
Posted Dec 17, 2014 11:36 UTC (Wed)
by epa (subscriber, #39769)
[Link] (2 responses)
There are still a few interfaces that work by pages - two that come to mind are PDF viewers (where you are viewing a document with hard page boundaries) and ebook readers (often with slowly-updating displays that would blur on scrolling, and attempting to reproduce the experience of reading a book). But on the whole, scrolling interfaces have driven out paginated ones, and with good reason.
I would much prefer the Info reader to show the whole document and scroll through it, a line at a time with up / down and a screenful (not a 'section') at a time with page up / page down. That doesn't stop it from accepting Space to jump to the start of the next section, but you could still visually see your position in the document.
Yes, I have sometimes used the trick of info | less to get a more usable interface...
Posted Dec 17, 2014 12:04 UTC (Wed)
by mchapman (subscriber, #66589)
[Link]
Posted Dec 17, 2014 12:26 UTC (Wed)
by tao (subscriber, #17563)
[Link]
Posted Dec 14, 2014 16:40 UTC (Sun)
by nix (subscriber, #2304)
[Link] (16 responses)
Nearly all these keys are conventional for this use in many other programs; the rest are bleedin' obvious. Rocket science this really isn't. If you can't figure out how to use info, I can't figure out how you even worked out how to start Emacs.
Posted Dec 14, 2014 18:47 UTC (Sun)
by cortana (subscriber, #24596)
[Link]
Posted Dec 14, 2014 18:51 UTC (Sun)
by sfeam (subscriber, #2841)
[Link]
Posted Dec 15, 2014 14:08 UTC (Mon)
by fb (guest, #53265)
[Link] (10 responses)
Here you are at LWN of all places, and a bunch of seasoned Linux/Unix users telling you: "I could never figure it out" etc. You really ought to reckon that, at the very least, something went very wrong in communicating how to use info or at its usage assumptions.
Wrong assumption: I use/do a lot of stuff from within emacs, but I don't live inside emacs (I'm sure you all understand what this means). If the assumption from the GNU project was that folks ought to live inside Emacs to read GNU programs' manuals then they really got things wrong.
Bad documentation: if using info is so easy ("all you need are keys space/backspace/u/q"), and if that is really everything I need to know about it, why the heck isn't that written in info's manual? I mean, where else do you expect that non-info users will look for how to get started using info? I tell you: 'man info'. Please open 'man info' and try to read it as someone who has no clue about 'info'. Guess what? You'll be done reading that and you will still have no clue about how to use it.
Posted Dec 15, 2014 15:33 UTC (Mon)
by rleigh (guest, #14622)
[Link] (3 responses)
- the texinfo .texi source format
The .texi source format can be replaced with e.g. Sphinx or DocBook, both of which can be translated to .info as well as more modern formats such as HTML and PDF. Having written a manual in .texi, I think it's fair to say it's OK if you like a LaTeX-style markup, but maintaining the section links is painful and easy to screw up, and while the format is good, it does have limitations. Using Sphinx (or even DocBook) is generally easier to write and maintain. And despite being TeX-based, the .texi table support is fairly woeful; not that Sphinx or DocBook are amazing, but they are both much better, as is basic troff tbl. Support for figures and images is also fairly rudimentary. Generally I think that the .texi source format is due for retirement; the replacements are generally nicer and simpler to use.
On the viewer side, I agree it seems less simple than man/less. While the added structure does seem nice, in practice I always seem to end up searching for what I need or using the index. That said, I do think the criticisms are somewhat overblown; even the basic info viewer is perfectly functional. There is significant room for improvement though, particularly on the Emacs side where it can draw on the rendering features of the editor.
The .texi manual I wrote was converted to DocBook a decade back. And all the stuff I currently maintain is either manpages (with translations via po4a) or Sphinx. Both are far nicer to maintain than .texi. I think the days of .texi as a source format are waning, but this is relatively independent of the .info viewers.
Regards,
Posted Dec 15, 2014 17:31 UTC (Mon)
by nix (subscriber, #2304)
[Link] (1 responses)
Posted Dec 15, 2014 19:03 UTC (Mon)
by rleigh (guest, #14622)
[Link]
Posted Dec 15, 2014 18:22 UTC (Mon)
by Per_Bothner (subscriber, #7375)
[Link]
Note that with recent version of texinfo format, the cross-references (forward/back/up) in the @node command are optional.
It's best to just leave them out.
Posted Dec 15, 2014 16:18 UTC (Mon)
by mbunkus (subscriber, #87248)
[Link] (5 responses)
1. »man info« pretty much tells you to type »h« inside info itself in order to get help on key bindings. Citing »man info«:
> For a summary of key bindings, type h within Info.
2. When you run info (the program) then the bottom line will read »Welcome to Info version 5.2. Type h for help, m for menu item.«.
Hitting that aforementioned »h« inside h will get you exactly the information you need.
So I do dispute the claim that how to use info is not documented enough.
Posted Dec 18, 2014 20:37 UTC (Thu)
by Wol (subscriber, #4433)
[Link]
Cheers,
Posted Dec 18, 2014 22:29 UTC (Thu)
by bronson (subscriber, #4806)
[Link]
Posted Dec 19, 2014 10:53 UTC (Fri)
by fb (guest, #53265)
[Link] (2 responses)
It seems OSX ships a version of info which is from Dec 2004 (Info version 4.8). (at work I pretty much sit the whole day inside OSX).
So while the documentation may have been fixed recently to address many usability issues. This old man page shows (as far as I am concerned) why so many people that made an honest attempt to use info 'back in day' did not succeed and pretty much learned ways to avoid using it.
Posted Dec 19, 2014 14:10 UTC (Fri)
by oldtomas (guest, #72579)
[Link] (1 responses)
This could be an instance of "Steve's wrath": AFAIK Apple hates GPLV3 and prefers treating its customers to outdated Gnu software before even coming close to this license (Bash's another typical case: watch Apple's strange dance in the shellshock drama).
Whether that's in your (as Apple's customer) interest is quite another thing...
Posted Dec 19, 2014 14:36 UTC (Fri)
by fb (guest, #53265)
[Link]
[...]
I am seriously /not/ an Apple fan. But from my experience working for large IT companies, I don't think it has much to do with a former CEO's wrath or not. My **guess** is that something like this took place:
1. when the GPLv3 came out, folks in charge of updating utilities knew they had to get Legal to approve the new license. They asked Legal. Legal said "nope".
2. the (GPLv3 inclusion) request won't ever get reevaluated without pressure coming from product managers, and I suppose Apple product managers really do not have that anywhere in their priority list.
[...]
Bash's shell-shock back and forth of fix-attempts was, in my understanding, embarrassing for everyone.
Posted Dec 15, 2014 16:53 UTC (Mon)
by k8to (guest, #15413)
[Link] (2 responses)
Its okay to support these keys, but the arrow keys should work always. There should be oncreen prompts visible at all times for what to press to go up, next etc. The '/' key should start a search like with all the other terminal programs. And so on.
The whole concept of having a document tree that you can't visualize is sort of unfortunate as well. It would be far less bad if there was a list down the left side of the chapters or something.
pinfo makes info reading livable for me, and the only real important advancement was to use the correct keys. However, I still prefer manpages for the majority of caess where I encounter info pages.
Posted Dec 15, 2014 18:16 UTC (Mon)
by nix (subscriber, #2304)
[Link] (1 responses)
Posted Dec 16, 2014 7:59 UTC (Tue)
by k8to (guest, #15413)
[Link]
Posted Dec 11, 2014 9:30 UTC (Thu)
by marcH (subscriber, #57642)
[Link]
> The discussion (and this summary) sometimes conflated two separate issues:...
Thanks - it's good to see there still a few people demonstrating common sense and trying to stick to facts and research in one of the least fact-based debates reported here for a long time.
Is the texinfo format at the cutting edge of markup technology? Maybe not. Any distant sign of any proof that it actually matters in any significant way? Could not spot anything yet in all this hand-waving and confusion of vaguely informed opinions.
PS: I've used a few markup languages, including texinfo.
Posted Dec 14, 2014 0:04 UTC (Sun)
by kleptog (subscriber, #1183)
[Link]
Quite. The number of people who can do markup is much greater than the people who can write good documentation. If people like writing asciidoc better, that's great. You can always convert it to texinfo prior to commit.
Posted Jan 13, 2015 17:40 UTC (Tue)
by benbadge72 (guest, #100585)
[Link]
Posted Dec 11, 2014 6:51 UTC (Thu)
by smurf (subscriber, #17840)
[Link] (3 responses)
Posted Dec 11, 2014 9:44 UTC (Thu)
by willnewton (guest, #68395)
[Link] (1 responses)
LLVM also uses Sphinx.
Posted Dec 11, 2014 14:05 UTC (Thu)
by dave_malcolm (subscriber, #15013)
[Link]
(yes, I need to get those docs built onto the gcc.gnu.org site)
Posted Dec 11, 2014 22:34 UTC (Thu)
by kjp (guest, #39639)
[Link]
Very interested seeing a sphinx vs asciidoc comparison from someone who has used both.
Posted Dec 11, 2014 7:31 UTC (Thu)
by Karellen (subscriber, #67644)
[Link] (15 responses)
I do find a table of contents with per-chapter links handy on occasion. But they're still not necessary, due to the magic of [ctrl]+f,"chapter title".
(Naturally, this required that your computer-based documentation is available as one large document. If you're creating a zillion tiny documents with links between them, just stop it, please? "Flipping" through documentation is much nicer with page up/page down, or roughly dragging a scrollbar thumb, than it is with endlessly clicking "prev"/"next" links.)
Posted Dec 11, 2014 8:39 UTC (Thu)
by ibukanov (subscriber, #3942)
[Link] (6 responses)
100% spot on. This is the reason that info sucks for me with its viewers showing typically one node without a possibility to quickly search the whole document. I have found that man pages for GNU utils that refer to info pages for full details are more usable then info themselves because I can quickly locate the term using search in the man page.
Posted Dec 11, 2014 9:33 UTC (Thu)
by marcH (subscriber, #57642)
[Link]
The default info viewer searches across multiple info nodes. 100% "off spot"?
And this is not even related to the source format.
Posted Dec 11, 2014 9:43 UTC (Thu)
by drothlis (guest, #89727)
[Link] (1 responses)
Having said that, I really feel for non-Emacs users who try to use the "info" command-line tool. It's just so different to anything else. You already know how to search in man pages because it uses $PAGER, which in turn uses the same keybindings as vi. Info is just alien.
Emacs users don't use the "info" command-line tool either, they use Emacs's built-in info browser which uses keybindings an Emacs user is already familiar with. Sometimes I wonder why distros don't replace "info" with a script that opens up the corresponding documentation in your web browser -- after all you can generate html from texinfo sources.
Posted Dec 11, 2014 17:44 UTC (Thu)
by sjj (guest, #2020)
[Link]
Posted Dec 18, 2014 16:05 UTC (Thu)
by dakas (guest, #88146)
[Link] (2 responses)
Posted Dec 18, 2014 23:38 UTC (Thu)
by flussence (guest, #85566)
[Link]
But I agree with the rest. HTML is a poor output format for technical documentation.
Posted Dec 24, 2014 1:46 UTC (Wed)
by bjartur (guest, #67801)
[Link]
Posted Dec 11, 2014 9:03 UTC (Thu)
by marcH (subscriber, #57642)
[Link] (1 responses)
Yes they are. When using info I use regularly BOTH indices and search because sometimes one hits faster and sometimes it's the other.
> I don't think I've needed to use an index for online documentation in about a decade.
Before mobile phones or tablets existed most people did not think they would ever feel the need for one.
Posted Dec 11, 2014 9:11 UTC (Thu)
by marcH (subscriber, #57642)
[Link]
Posted Dec 11, 2014 9:27 UTC (Thu)
by drothlis (guest, #89727)
[Link] (4 responses)
As an Emacs user, my use case for documentation indexes is this:
* I'm editing a Makefile.
It's so convenient that I try to find or generate info versions of the documentation for any programming language I use frequently. So far I've managed to get bash / coreutils / awk / sed, gnu make, automake / autoconf, perl, and python manuals.
Posted Dec 11, 2014 10:28 UTC (Thu)
by dgm (subscriber, #49227)
[Link] (3 responses)
Posted Dec 11, 2014 11:08 UTC (Thu)
by drothlis (guest, #89727)
[Link] (2 responses)
Posted Dec 11, 2014 11:24 UTC (Thu)
by drothlis (guest, #89727)
[Link]
Furthermore, indexed documentation gives you things that introspection doesn't -- I often find myself looking up the documentation for Python keywords, standard exception hierarchy, etc etc etc. None of which I can get from ipython's contextual help, at least.
Posted Dec 11, 2014 15:11 UTC (Thu)
by nix (subscriber, #2304)
[Link]
Posted Dec 12, 2014 4:00 UTC (Fri)
by sadboy (guest, #94691)
[Link]
Searching is a terribly inefficient method of reading documentation. Imagine searching through a million page document with ten thousand references to 'foo', for that one definition of 'foo'.
Additionally indices have auto-completion which will give you a quick list of potentially relevant terms.
Posted Dec 11, 2014 10:15 UTC (Thu)
by kashyap (guest, #55821)
[Link]
Posted Dec 11, 2014 10:31 UTC (Thu)
by debacle (subscriber, #7114)
[Link] (3 responses)
A much more severe problem is, IMHO, the license. The GNU FDL with "invariant sections" practically means, that if I want to use a small subset of the Emacs documentation for anything else, I have to include "The GNU Manifesto", the chapter "Distribution", the "GPL" with the front cover texts being "A GNU Manual" and a specifc back cover text.
I'm a fan of copyleft licenses, including AGPL3, but the FDL, at least with invariant sections and mandatory cover texts, is a step in the wrong direction.
Posted Dec 11, 2014 15:16 UTC (Thu)
by drag (guest, #31333)
[Link]
these things are easy to use, the amount of boiler plate is extremely minimal, and I can easily visualize what different formats will look like as I use them without needing to 'compile' them.
But then again I am in no position to write any Emacs documentation even if they use a very easy format because while I like Emacs it's something that I have to devote hours to getting it configured to just be able to use it properly. The idea of actually being able to meaningfully understand what is going on when I use emacs and then simplify it in a way that I can explain it to other people isn't something that I think I am capable of.
Posted Dec 12, 2014 8:32 UTC (Fri)
by pbonzini (subscriber, #60935)
[Link] (1 responses)
Posted Dec 12, 2014 9:18 UTC (Fri)
by mjg59 (subscriber, #23239)
[Link]
Posted Dec 11, 2014 20:09 UTC (Thu)
by rgb (subscriber, #57129)
[Link] (1 responses)
Posted Dec 12, 2014 6:58 UTC (Fri)
by mtaht (subscriber, #11087)
[Link]
IMHO.
It is used today to generate lovely tex presentations, html, and so on, but the real power is the integrated lisp throughout.
the power of org-mode seduces anyone that ever once used a competent outliner, like more. It keeps me IN emacs, using it, logging my time, scheduling reminders (with a single keystroke) and focused on the task at hand.
If you haven't used emacs in a while, try it, and lay down a few tasks in
Posted Dec 11, 2014 23:20 UTC (Thu)
by dlang (guest, #313)
[Link]
esr has a tendency to do this sort of thing, sometimes successfully, sometimes not (although even his failures tend to generate a lot of useful discussion and leave things better, remember Aunt Tillie and kernel configuration for one of the early examples??)
Given that the topics he tends to tackle are hard and tailor made for bikeshed arguments, I'm not sure that any approach is going to be easy. At least with his approach, nobody ends up feeling that a big change was secretly put in or that they thought he was working on one thing and feel ambushed because the end result was something different. His approach virtually guarantees that anyone who cares and is even casually watching the project will hear about it and have a chance to be part of the debate early on.
He also does take feedback and adjust his approach (to a large extent anyway :-)
He also avoids the "this is what someone else should do" trap, he goes in with the "this is what should change, and I am willing to write the tools to change it" approach instead.
Posted Dec 12, 2014 0:02 UTC (Fri)
by skissane (subscriber, #38675)
[Link]
Posted Dec 12, 2014 12:49 UTC (Fri)
by deepfire (guest, #26138)
[Link] (2 responses)
My experience with writing documentation in it is enjoyable, with the only problem being the PDF export pipeline seemingly never quite working by default. But that problem is about documentation export.
The lovely thing about Org is the _ease of document composition_.
When you add the power of Org markup, like dictionaries, term definition anchors, various kinds of links, source code blocks (executable!), node states, per-node-properties.. it all really quickly becomes hard to resist.
Org is very light-weight, and very expressive at the same time.
Posted Dec 16, 2014 20:21 UTC (Tue)
by sjj (guest, #2020)
[Link] (1 responses)
I just started putting our company sysadmin docs into Org documents, stored in git and rendered to web pages with this: https://github.com/fniessen/org-html-themes and I'm in love.
If Emacs wants to ditch texinfo, they could do much worse than use Orgmode instead.
Posted Dec 23, 2014 6:56 UTC (Tue)
by blujay (guest, #39961)
[Link]
Posted Dec 16, 2014 2:03 UTC (Tue)
by ldo (guest, #40946)
[Link]
And then there’s Pandoc, which can convert between a whole range of formats, including AsciiDoc.
Posted Dec 16, 2014 2:14 UTC (Tue)
by ldo (guest, #40946)
[Link] (5 responses)
If it comes to a choice of man pages over info pages, I would choose man every time. Even after many years of exposure to documentation in info format, I still cannot get used to how clunky it is to find things. My first instinct when looking for documentation for any command-line tool is to see if there is a man page for it.
OK, so how would you provide cross-referencing and searchability? Look at these two examples:
Either option works just fine, and lets me find stuff much quicker than info would.
Posted Dec 18, 2014 16:50 UTC (Thu)
by perlwolf (guest, #46060)
[Link] (4 responses)
The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings. Whereas man uses whichever pager *I* chose for all of my viewing of long texts with the key bindings I already know. A learning curve of zero wins by a factor of infinity.
Every time I am forced to go to info to read documentation, I spend ten times as much time trying to figure out how to make it work than I do in reading actual documentation. So, I only use info as a absolute last resort. I've never, in all the time since the first info docs came available (yes, I've been using Unix systems that long) used info enough time to actually learn its command line. I've always considered the single fact of required a special program with its own random keystrokes to do a simple task as being an extremely arrogant act in the GNU choice of using info.
Posted Dec 21, 2014 6:50 UTC (Sun)
by madscientist (subscriber, #16861)
[Link] (3 responses)
You want to page through the entire manual as a single document? SPC/DEL (like less/more) will page down and back, and at the end of the page they automatically go to the next/previous page, just as you'd expect. Also PgUp/PgDown work the same way. Also arrow keys work the same way.
You want to search the entire document? "s" does that. So does "/" (a la less or vi).
You can't remember a key? "h" gives a quick key reference. So does "?".
These are all the common keys that I would try in any reader program, that work just as I'd expect them to work, and for which I wouldn't need to read any documentation first. I see lots of generic expressions of frustration, but no one is saying exactly what is missing.
Of course there are more advanced operations which don't have direct analogs in other programs... because info has more capabilities than those programs. Things like "i" for searching the index, or "n" (next section), "p" (previous section), "u" (up to parent section), "m" (choose menu item), "t" (top of manual), or "d" (directory of manuals). But if you don't know about these you don't have to use them.
Just about the only common navigation keys not supported by info are vi's hjkl.
So what, pray tell, are these magical keys that everyone expects info to support and are so frustrated when it doesn't, and take ten times as long to discover as it does to read the documentation?
Regarding man pages vs. texinfo manuals; I will definitely agree that man pages are better for some sorts of documentation and that in general, the GNU project does a disservice when they produce anemic man pages that say little more than "read the texinfo manual". Some things are better documented via man pages. However, man pages are reference documentation: that is, they work best when you already have a basic idea of what command you want to use and more or less how it works, but need a refresher on the details. Texinfo documentation is user documentation. Reworking the GNU Emacs manual, for example, into a man page (or even a huge set of man pages) would be excruciating and ridiculous.
As I said in my first reply, I won't pretend texinfo is the greatest markup ever but anyone wanting to move to something else should first ensure that the something else has at least all the capabilities of info. My suspicion is it would take less effort overall to keep texinfo as a markup and fix up the problematic output formats... the HTML output for example could be significantly improved: maybe having a floating menu that followed as you scroll and contained next/previous/up/top/directory buttons and search and index search boxes, plus providing info-like keybindings for keyboard control.
Posted Dec 25, 2014 13:47 UTC (Thu)
by DigitalBrains (subscriber, #60188)
[Link]
I think the biggest problem with info I had quite some years ago before I discovered 'pinfo' was simply related to scrolling. Using the arrow keys to scroll is so much in my muscle memory that I felt like a stranger in an unfamiliar, not very friendly environment when it did not work. I was focusing my attention on the text, and kept getting drawn back to having to think about navigation halfway through a paragraph.
Trying info for the first time in years just now, it does indeed support one-line scrolling with the arrow keys, and there's the very helpful "Press 'h' for help" message. It would be nice if scrolling from one chapter to the next were fluid, though. Now it behaves like PgUp/PgDn at the boundaries. And it does so before I have finished reading the last chapter, whisking away the text I'm reading. The By the way, my 'less' does not have Del for PgUp; its help mentions b, ^B, Esc-v and w. The unmentioned PgUp works as well.
Posted Jan 21, 2015 11:38 UTC (Wed)
by bmur (guest, #52954)
[Link] (1 responses)
For comparison, I just did a "man ls" and "info ls".
The man page gives me a nice short description of the command, a synopsis of the syntax, and jumps into the options. Very unix.
Info tells me that ls lists directory content and quickly sends me down a rabbithole. It gets pedantic about files vs directories, locales, and gives me a full paragraph telling me this command has a lot of options. (duh) Maybe all of these details are important. But for me, seeing the command line options are my goal and the edge cases about ls output sorting behavior can be put at the end of the manual.
Pressing the arrow key to scroll down doesn't move the page down. I have to take my focus off of the document and figure out why the down key didn't work. Oh, there is a cursor moving in-page on a read-only document... that seems useless. So I hold the down key to get a page full of keystrokes hoping to find the command line options. At such point the command description disappears and the options start like a new document. My expected behavior was to see it as a continuation of the documentation.
But oh wait, my down key isn't moving the page down anymore. The cursor starts moving from the top and needs another 30 presses to get to the bottom.
If you want to review something you read a few seconds ago, you need 30 up keypresses to move the page up a single line.
This is the hell of using the info command.
If I decide I want to skip a full page ahead, I press the space bar because that is what most standard unix utilities use. Sometimes it was moving me down a page and sometimes I get a blank screen (I have no idea why).
I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.
All of these minor things add up to a horrible experience. Imagine if instead of ls, I was trying to get info about a command I was less familiar with. The frustration would be immense.
Posted Jan 21, 2015 11:55 UTC (Wed)
by mpr22 (subscriber, #60784)
[Link]
This is because GNU ls is a component of the GNU coreutils suite, and whoever wrote the documentation for GNU coreutils made the IMO completely misguided decision that there should be a single info document covering all the disparate components of coreutils. I'd never noticed this before because I've never used the info documentation for coreutils because every Linux distribution I've ever used has a man page for the programs in coreutils. Some other info documents (such as the manuals for GCC, Flex, and Bison; if you tell me any of those should be a single man page each, or even a farm of man pages, I will laugh like a hyena and refer you to the reply in the case of Arkell v. Pressdram (1971)) are more sensible.
Posted Dec 18, 2014 13:16 UTC (Thu)
by ssokolow (guest, #94568)
[Link]
That means perfect fidelity conversion to DocBook and easy construction of a toolchain to output anything DocBook tooling can do. (Which, when you consider that Pandoc accepts DocBook, is quite a lot.)
Heck, I don't know how well it works, but there already exists a DocBook->TexInfo converter OTHER THAN Pandoc which is mature enough to have made it into Debian as docbook2x and Ubuntu as docbook2x-texi. (It also does manpages, thus the split)
Posted Dec 25, 2014 15:19 UTC (Thu)
by job (guest, #670)
[Link] (1 responses)
One day a clown pops up: "I'm here to take all your tools away! But don't worry, I will get you new and different ones!" It's not hard to imagine the outcome. Especially if the said person was widely known to let others pick up the pieces.
The ONLY way to manage such a change is to do it in manageable chunks. First create new html templates with all the functionality of the current info pages. Then, change the internal viewer to show the nice html documents instead. THEN, change the file formats for documentation maintainers, because this time there'll be benefits to it.
If it is at all a welcome change, that is. I know neither Sphinx (which I regard as much nicer to write than asciidoc) nor html directly would solve any of the real problems I see with documentation. The most obvious one is that neither has any support for figures and screenshots. It's all delegated to external tooling, and at best stored hierarchically together with the documentation source.
But an integrated figure system could solve so much more. It could update screenshots when the underlying software is updated and make sure figures don't look out of place graphically. Just look at Lilypond which is rightly pointed out as well done. No offense meant, but while it's absolutely good, it doesn't look remotely modern. Text as pictures, bad aliasing, strange positioning, colors out of place, and no visible connect to the actual software in use. There's no doubt even better is possible.
Posted Dec 25, 2014 16:48 UTC (Thu)
by vonbrand (subscriber, #4458)
[Link]
"Keep screenshots in documentation and code in sync automatically" is just a very tiny part of the job of structuring and writing said doumentation. And mostly science fiction. There are several objectives to documentation. One is "answer somebody's specific question, who has already a pretty good idea what they are looking for", where short man pages excel. Another, almost opposite, is "get an overview of what <foo> is all about", which is typically covered by textbooks and such. The info system tries to do both in a book-style format, no wonder it isn't too good at delivering the first. Some of the info documentation I've used is excellent in the second aspect, for example the bison manual. And the info format isn't at all a hindrance in its use, making it navigable is much better than having it as a printout. You can even pilfer the code examples, but that takes a bit too much effort. Redoing the extant texinfo format documentation in some other format won't solve the problem that it isn't easy to extract answers to narrow questions out of broad descriptions. Perhaps complementing texinfo manuals with narrow man pages (or something equivalent) would be a step forward, but that requires knowledegable brains to write the missing pieces, not just a format change or some vaporware extraction tool.
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
> PDF/PostScript, but very poor tools for producing HTML, man, or plain
> text, all critical formats for documentation.
> an afterthought.
The discussion (and this summary) sometimes conflated two separate issues:
source format vs info/html
That should have been "Well-established tools can create html, pdf/dvi, or docbook (as well as info format) from texinfo source."
source format vs info/html
No, you can have one version of the HTML and use style sheets to present the information differently for different uses (a printed manual, online documentation browser, or help text).
source format vs info/html
No, you can have one version of the HTML and use style sheets to present the information differently for different uses (a printed manual, online documentation browser, or help text).
source format vs info/html
There are a heck of a lot of ifs, maybes, and should be possibles in the second point here. Meanwhile, info mode is far and away the simplest, fastest, most useful, most usable way to read serious documentation, rather than little FAQ tidbits.
source format vs info/html
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.
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
Many thanks for the pinfo pointer -- worth the visit to the comments for this alone.
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
Incremental search on arbitrary terms across the entire document, without needing to have the entire document be presented as a single HTML page.
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
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
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
Wol
source format vs info/html
HTML also does hyperlinks, just like info, and encourages this kind of split document.
source format vs info/html
source format vs info/html
source format vs info/html
Wol
source format vs info/html
Wol
source format vs info/html
(shows the zeroth chapter, i.e. the main-level TOC)
<space> or <page-down>
(shows the second page of the TOC)
<space> or <page-down>
(shows the Contents of "1. Introduction to GRUB")
<space> or <page-down>
(shows "1.1. Overview")
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
> Yes you can page through it with space - which causes the current page to vanish and be replaced by the next page.source format vs info/html
I find the single biggest usability improvement to GNU Info is to turn this behaviour off. If the documentation is going to be split up into separate chapters (which I don't find particularly annoying, to be honest), then it's better to not have the viewer jump between chapters and completely refresh the screen when you're not expecting it to.
To change this behaviour you need to set up an ~/.infokey file containing:
#var
scroll-behaviour=Page Only
Then run infokey to compile that to ~/.info. Who said GNU Info wasn't user-friendly? :-)
source format vs info/html
source format vs info/html
source format vs info/html
You seriously underestimate how foreign this is to people who are not Emacs users. When someone says "I am confused by X", it is pointless to respond "X is not really confusing".
source format vs info/html
source format vs info/html
source format vs info/html
- the info .info viewer format
- the viewer program (info/pinfo/emacs/yelp/...)
Roger
source format vs info/html
source format vs info/html
"maintaining the section links is painful and easy to screw up"
source format vs info/html
source format vs info/html
source format vs info/html
Wol
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
Its okay to support these keys, but the arrow keys should work always.
They do, if by that you mean they should navigate to the next/previous node -- in standalone info. in Emacs info, they don't: probably an oversight.
There should be oncreen prompts visible at all times for what to press to go up, next etc.
What, like there is in less?
The '/' key should start a search like with all the other terminal programs. And so on.
Again, in the standalone info viewer, it does. In Emacs Info this would be rather alien, but / is unbound at present so it might as well work that way :)
source format vs info/html
source format vs info/html
source format vs info/html
source format vs info/html
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/...
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
This is the reason that info sucks for me with its viewers showing typically one node without a possibility to quickly search the whole document.
Except that s does search the whole document. So does i. And much faster than any HTML search, I might add.
Having one large HTML page for a 700-page manual is a huge pain in the behind. Try to do any sensible scrolling with the scrollbar: pretty much impossible. Try getting back to the previous place when scrollbar or text search led to some uninteresting chapter: pretty much impossible. There is no "Back" button for in-page navigation.
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
* Hmmm what does "$*" mean again?
* Press magic Emacs key incantation ("F1 S")
* Bam the documentation for "$*" appears. Not just the right document, but with the viewpoint centred at the relevant paragraph, which is highlighted.
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Better discuss the license!
Better discuss the license!
Better discuss the license!
Better discuss the license!
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats
The simple ergonomics it has for extending, reorganising, drilling down into the document outline -- it's really in a class of its own.
Emacs and changing documentation formats
Emacs and changing documentation formats
Who Says AsciiDoc Tools Only Output HTML?
man > info
man > info
man > info
The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings.
I really cannot understand this. I've seen many posts similar to this in this thread and I'm still stumped. Hardly any of the criticisms seem accurate to me.
While reading a text, I don't scroll with PgUp/PgDn; I scroll with the arrow keys. The more fluid motion of one line at a time helps me keep my orientation, I think. I only use PgUp/PgDn for skipping text, as a poor man's search for the next piece I'm interested in when I can't be bothered to think of a search term or genuinely don't know one.
Scrolling
scroll-behaviour=Page Only option mentioned by mchapman is preferable to me now.
man > info
man > info
I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.
Emacs and changing documentation formats
Emacs and changing documentation formats
Emacs and changing documentation formats