Per Bothner's blog

A Roadmap for TexInfo without Info

TexInfo is a decent system for writing documentation. Its weakness is the “info” file format, which is an obsolete kludge but replacing it is a multi-pronged task.

The paper attempts to specify a replacement format and associated tooling. I will call this format “hinfo” as it is a replacement for info format using html syntax. (However “hinfo” is not proposed as a file extension; hinfo files should use the .html or .xhtml extensions.)

Problems with info

• Info is a non-standard format used by no-one else. Hence there is very little tooling.
• Info lines are pre-broken, so it cannot adjust to different screen widths.
• Info requires a monospace font, and so valuable semantic information is lost. Info cannot distinguish @samp and @code. It indicates @var using upper-case. Info-reading programs have limited ability to recover the lost semantic information. Being able to use poportional fonts for descriptive text and monospaced fonts for code and examples makes documentation easier to read.
• Info documentation looks ugly. Using info as the publicly visible front-end for GNU documentation presents a bare-bones and behind-the-times image for texinfo and GNU generally. This is bad marketing.

It is possible to improve html/DocBook support without deprecating or dropping info format support. However, that has its own problems:

• Installing both info files and html files wastes disk space.
• Having two primary formats for documentation is likely to lead to inconsistencies and other problems. What if one package only installs html, another package only installs info, and a third installs both? We would need more complex and brittle installation directory and search path standards.
• Which format should Emacs info prefer? If you accept what I wrote above, clearly “hinfo” rather than “info”. But in that case, why continue to install info files, or (longer-term) maintain tooling for them?

XHTML as an Info (format) replacement

The obvious replacement for Info is some variant of HTML or XML.

The format should follow the recommendations for Polyglot markup. This means documents are well-formed as both HTML and XML.

If hinfo is well-formed XML then various processing tools (such as XSLT) can be used to analyze or transform the output. For that to be useful, it is a goal that hinfo contain all or most of the semantic information from the texinfo file. Specifically, it should include all the information currently produced by makeinfo --xml or makeinfo --docbook. That can be done with class and other attributes. It is hoped hinfo can make at least makeinfo --xml obsolete.

EPUB uses the epub:type attribute to optionally indicate semantics. Texinfo could do the same.

Note the html currently generated by makeinfo -html is rather poorly structured, and it should be cleaned up. See this thread for discussion on this topic.

The Info UI in a plain browser

It would be useful to have info keyboard shortcuts when reading an hinfo file in a vanilla web browser. Most of the navigation would be trivial to implement using JavaScript. This message discusses a proof of concept.

JavaScript can also add a navigation sidebar, using frames, either <iframe> or old-fashioned framesets. (Using an iframe for the sidebar has the advantage that you can have cleaner URLs visible in the location bar.)

A navigation sidebar makes use of a makeinfo-generated table-of-contents-file, which is just a nested HTML list. (This is the ToC format used by EPUB3.) Depending on user preference, it is trivial for JavaScript to load the ToC in an <iframe>, without cluttering up the content files.

Even better is a reduced navigation sidebar, which only shows ancestor, sibling, and child links. This makes for a less overwhelming sidebar.

For Kawa I implemented JavaScript for a reduced navigation sidebar, using either <iframe> or framesets. This could form the basis of a similar feature for hinfo navigation.

Emacs Info mode

For reading of hinfo file in Emacs we want something with the user interface of traditional info mode, but able to read hinfo files. (It does not need to process the JavaScript in an hinfo file, since elisp can be used instead,)

For the html-reading it makes sense to use eww mode. An “hinfo mode” would be a hybrid of the existing info and eww modes, with the file handling and layout mosting using eww mode, while the keymap and user interface would come from info mode.

The standalone Info program

The standalone info program needs to be able to read hinfo files. There are multiple web-browsers that work in a terminal; one of these can be used.

However, it seems to make more sense to just use emacs in terminal (-nw) mode. We might add an option to Emacs to leave off the menubar and other undesired “decoration”.

There is special case when the terminal emulator is DomTerm, since DomTerm is built on web technologies: In that case we could have DomTerm create an <iframe> and load the html file into it.

Recommendation: Independently of any switch to hinfo, we should replace the standalone info program with a thin wrapper that invokes emacs -nw. Emacs does a better job than the info program.

Searching and chunking

Info mode and the info program allow you to “search for a sequence of characters throughout an entire Info file”. This is difficult to do in JavaScript if the “hinfo” file is actually multiple html files. The challenge is searching the other html pages besides the current one. There are ways to do, for example by loading the other pages in internal <iframe>. However, it seems complicated, and browser security limitations complicate communication between sub-frames.

One can avoid the problem by not splitting a document into multiple html files, and just using a single large html page. JavaScript can be used to only display one chapter at a time. This would speed up navigation, but a single large html file can be pretty big.

Recommendation: Searching will only be supported using the emacs info mode (and the info program based on it). The JavaScript info-based UI will not support searching, at least not initially.

Installation of hinfo

There is standard for installing info files (possibly compressed) in a central location so info mode can find just given the name of a manual. The existing standard installs all info files in the same directory.

For hinfo, I think a better structure would be to have a separate directory for each manual. For example:

/usr/share/hinfo
  emacs
    index.html
    Search.html
    ...
  kawa
    index.html
    Tutorial.html
    screenshot-1.png
  ...

Using epub for packaging

To save disk space, it is desirable to compress each manual. The epub format is a standard for electronic books, and it satisfies texinfo’s need pretty well. An epub file is essentially a zip archive with web pages (xhtml), images, a table of contents, and resources like css styling. There are many epub-reading devices, programs, and browser plugins.

For example the Kawa binary distribution (see final section) ships the texinfo-derived manual in epub format. Kawa includes a --browse-manual option that works by starting a mini-webserver that reads and uncompresses the epub manual, and then displays it in a browser.

Emacs can already process zip archives, including epub files. So it shouldn’t be difficult enhance info mode to deal with epub files.

Recommendation: Change the preferred output format of makeinfo be an epub file. “Installing” an hinfo file would involve copying the epub to a system location. For example:

/usr/share/hinfo
  emacs.epub
  kawa.epub
  ...

If someone wants to publish a manual on the web, they can just unzip the epub file into a server directory.

Caveat

This is a proposed road-map and plan of action. There is no timeline or commitment from the author or anyone else to implement it. I (Per Bothner) believe myself to be very qualified to do most of the needed work, and would consider doing so if sponsorship were found. I will also be happy to advise volunteers.