Recently I’ve been digging a lot into GNU/Linux system administration and as part of this, I have finally taken some time to google about that mysterious info command that has been sitting here in my GNU/Linux systems, unused for years.
Well, I can tell you, it has been a life-changing experience.
Texinfo-based documentation is awesome.
In this article, I want to share why is info documentation cool and why you should read its documentation if you didn’t already.
First, some terminology.
- info: the command-line tool you use to read documents written using the texinfo format.
- Texinfo is a document format and a software package providing tools to manipulate texinfo documents.
Texinfo was invented by the Free Software Foundation to overcome the limitations of manpages such as “un-browseability” (man pages are really documents supposed to be printed to paper but rendered to the terminal instead) and the lack of hyperlinking capabilities in the format.
GNU info was designed as a third level in documentation. If you take a typical program from the free software foundation, you can expect it to have three level of documentations:
- the –help option: quick, one- or two-screenful of documentation
- the man page
- the info manual
Try and do “ls –help”, “man ls” and see the difference.
So info documents are documents that can be divided into sections, browsed only in parts, can have links to other pages of the documentations and can have links to other pieces of documentation as well! Also, they can be viewed with different viewers.
How do I learn to use info ?
Well, if the right way to learn about man is “man man”, the right way to learn about info is “info info”, and indeed such command will teach how to use the info tool.
Basically, you can go browser documents going forwards and backwards between nodes using n/] or p/[. Scrolling happens with space or backspace.
That is really the basic usage. Now go and type “info info” in your terminal.
As I said earlier, Texinfo Documents can be viewed outside the terminal too, while retaining all of their capabilities. I you have ever read some documentation on the webside of the Free Software Foundation then congrats, you have been reading a texinfo document translated to HTML.
For me, the game changer has been reading the GNU Emacs manual (a texinfo document) using GNU Emacs itself! They keystrokes are pretty much the same as the terminal ones, but you get variable-sized fonts and different colors for, say, hyperlinks and stuff like this.
Being able to read the Emacs manual inside Emacs is a game-changer for me because every time I don’t know something about Emacs, I can just start the manual and look it up. Clean and fast, no browser required (my CPUs are thanking me a lot)
Writing Texinfo documents
Here is where, sadly, the story takes an ugly turn.
I didn’t dig this topic very deep, but as far as I’ve seen, Texinfo documents are a major pain to write. The syntax looks quirky, but it seems worth it as Texinfo documents can be exported to HTML and PDF too.
There should be an org-mode plugin to export to Texinfo, but I couldn’t get it to work.
Again, I have to dig this topic a bit more, but it seems quite worth it.