rst2texinfo

Author:: Jon Waltman
Contact:: jonathan.waltman@gmail.com

rst2texinfo is an extension of the Docutils text processing system which adds support for generating Texinfo files from reStructuredText.

Introduction

The purpose of this program is to generate Info files from reStructuredText documents. Info is the underlying format of the on-line help system used by the GNU Project. This system provides a useful and convenient method for reading manuals from the terminal or within the Emacs text editor. Although, the focus of this program is to produce Info output, Texinfo can also be used to generate a variety of different formats, including HTML, Latex, and plain text. More information on Texinfo can be found at http://www.gnu.org/software/texinfo/.

rst2texinfo uses the following components:

Python (tested using v2.6) -- http://www.python.org/
Docutils (tested using v0.6) -- http://docutils.sourceforge.net/

To create Info files, you will need the "makeinfo" program which is part of the Texinfo project.

Install

python setup.py install

Invoking rst2texinfo

rst2texinfo.py [options] [<source> [<destination>]]

Reads reStructuredText from source and writes Texinfo to destination.

Texinfo Specific Options

In addition to the general options provided by Docutils, the following options affect the output of rst2texinfo.

--texinfo-filename=<file>

Specify the name of the Info file that would be created after running makeinfo on the generated Texinfo file. Default behavior is to use the base name of the input source.

--texinfo-dir-entry=<name>

Specify the name of the entry to create in the top level DIR menu file.

To create this entry, run install-info on the generated Info file.

--texinfo-dir-description=<desc>

Descriptive text to appear in the top-level DIR menu file.

--texinfo-dir-category=<category>

Specifies the section which this entry will appear in the top-level DIR menu file.

Converting Texinfo to Info

After converting your reStructuredText document to Texinfo, the next step is to convert the Texinfo file to Info. To do this, you will need to use the makeinfo program. Refer to the documentation for more details but its general usage is:

makeinfo --no-split FILENAME.texi

This should create a file named FILENAME.info which can then be read using an "Info reader".

Reading Info Files

There are two main programs for reading Info files, info and GNU Emacs. The info program has less features but is available on most *nix environments and can be quickly accessed at the terminal. Emacs provides better font color displays and supports extensive customization (of course).

Issues

The conversion of reST to Texinfo is not a seamless transition. Info is not as sophisticated as HTML which creates several issues since most reST documents are geared for HTML output. The following sections describe some of these issues.

Displaying Links

One noticeable problem you may encounter with the generated Info files is how references are displayed. If you read the source of an Info file, a reference to this section would look like:

* note Displaying Links: target-id

In the stand-alone reader, info, references are displayed just as they appear in the source. Emacs, on the other-hand, will by default replace \*note: with see and hide the target-id. For example:

Displaying Links

The exact behavior of how Emacs displays references is dependent on the variable Info-hide-note-references. If set to the value of hide, Emacs will hide both the \*note: part and the target-id. This is generally the best way to view reST documents since they often make frequent use of links and do not take this limitation into account. However, changing this variable affects how all Info documents are displayed and most due take this behavior into account.

If you want Emacs to display Info files produced by rst2texinfo using the value hide for Info-hide-note-references and the default value for all other Info files, try adding the following Emacs Lisp code to your start-up file, ~/.emacs.d/init.el.

(defadvice info-insert-file-contents (after
                                      docutils-info-insert-file-contents
                                      activate)
  "Hack to make `Info-hide-note-references' buffer-local and
automatically set to `hide' iff it can be determined that this file
was created from a Texinfo file generated by Docutils or Sphinx."
  (set (make-local-variable 'Info-hide-note-references)
       (default-value 'Info-hide-note-references))
  (save-excursion
    (save-restriction
      (widen) (goto-char (point-min))
      (when (re-search-forward
             "^Generated by \\(Sphinx\\|Docutils\\)"
             (save-excursion (search-forward "" nil t)) t)
        (set (make-local-variable 'Info-hide-note-references)
             'hide)))))

Notes

The following notes may be helpful if you want to create Texinfo files:

Each section corresponds to a different node in the Info file.
Some characters cannot be properly escaped in menu entries and xrefs. The following characters are replaced by spaces in these contexts: @, {, }, ., ,, and :.
In the HTML and Tex output, the word see is automatically inserted before all xrefs.
Links to external Info files can be created using the somewhat official URI scheme info. For example:
```
info:Texinfo#makeinfo_options
```
which produces:

info:Texinfo#makeinfo_options
Inline markup appears as follows in Info:
- strong -- *strong*
- emphasis -- _emphasis_
- literal -- `literal'

Copyright

rst2texinfo and this documentation should have the same license as the Docutils project.