Add documentation for Texinfo builder

doc/faq.rst

@@ -148,3 +148,112 @@ some notes:
 .. _Calibre: http://calibre-ebook.com/
 .. _FBreader: http://www.fbreader.org/
 .. _Bookworm: http://bookworm.oreilly.com/
+
+
+.. _texinfo-faq:
+
+Texinfo info
+------------
+
+The Texinfo builder is currently in an experimental stage but has
+successfully been used to build the documentation for both Sphinx and
+Python.  The intended use of this builder is to generate Texinfo that
+is then processed into Info files.
+
+There are two main programs for reading Info files, ``info`` and GNU
+Emacs.  The ``info`` program has less features but is available in
+most Unix environments and can be quickly accessed from the terminal.
+Emacs provides better font and color display and supports extensive
+customization (of course).
+
+.. _texinfo-links:
+
+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:
+
+    :ref:`texinfo-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 Sphinx-based
+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 Sphinx 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
+                                          sphinx-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 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"
+                 (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'
+
+  It is possible to change this behavior using the Texinfo command
+  ``@definfoenclose``.  For example, to make inline markup more
+  closely resemble reST, add the following to your :file:`conf.py`::
+
+      texinfo_elements = {'preamble': """\
+      @definfoenclose strong,**,**
+      @definfoenclose emph,*,*
+      @definfoenclose code,`@w{}`,`@w{}`
+      """}