sandbox/texinfo-writer/README.txt

   1
   2 rst2texinfo
   3 ***********
   4
   5 :Author: Jon Waltman
   6 :Contact: jonathan.waltman@gmail.com
   7
   8 ``rst2texinfo`` is an extension of the Docutils text processing system
   9 which adds support for generating Texinfo files from reStructuredText.
  10
  11
  12 Introduction
  13 ============
  14
  15 The purpose of this program is to generate Info files from
  16 reStructuredText documents.  Info is the underlying format of the
  17 on-line help system used by the GNU Project.  This system provides a
  18 useful and convenient method for reading manuals from the terminal or
  19 within the Emacs text editor.  Although, the focus of this program is
  20 to produce Info output, Texinfo can also be used to generate a variety
  21 of different formats, including HTML, Latex, and plain text.  More
  22 information on Texinfo can be found at
  23 http://www.gnu.org/software/texinfo/.
  24
  25 rst2texinfo uses the following components:
  26
  27 * Python  (tested using v2.6) -- http://www.python.org/
  28 * Docutils (tested using v0.6) -- http://docutils.sourceforge.net/
  29
  30 To create Info files, you will need the "makeinfo" program which is
  31 part of the Texinfo project.
  32
  33
  34 Install
  35 =======
  36
  37 ::
  38
  39     python setup.py install
  40
  41
  42 Invoking rst2texinfo
  43 ====================
  44
  45 ::
  46
  47     rst2texinfo.py [options] [<source> [<destination>]]
  48
  49 Reads reStructuredText from ``source`` and writes Texinfo to
  50 ``destination``.
  51
  52 .. rubric:: Texinfo Specific Options
  53
  54 In addition to the general options provided by Docutils, the following
  55 options affect the output of rst2texinfo.
  56
  57 --texinfo-filename=<file>
  58    Specify the name of the Info file that would be created after
  59    running ``makeinfo`` on the generated Texinfo file.  Default
  60    behavior is to use the base name of the input source.
  61
  62 --texinfo-dir-entry=<name>
  63    Specify the name of the entry to create in the top level ``DIR``
  64    menu file.
  65
  66    To create this entry, run ``install-info`` on the generated Info
  67    file.
  68
  69 --texinfo-dir-description=<desc>
  70    Descriptive text to appear in the top-level ``DIR`` menu file.
  71
  72 --texinfo-dir-category=<category>
  73    Specifies the section which this entry will appear in the top-level
  74    ``DIR`` menu file.
  75
  76
  77 Converting Texinfo to Info
  78 ==========================
  79
  80 After converting your reStructuredText document to Texinfo, the next
  81 step is to convert the Texinfo file to Info.  To do this, you will
  82 need to use the ``makeinfo`` program.  Refer to the documentation for
  83 more details but its general usage is::
  84
  85     makeinfo --no-split FILENAME.texi
  86
  87 This should create a file named FILENAME.info which can then be read
  88 using an "Info reader".
  89
  90
  91 Reading Info Files
  92 ==================
  93
  94 There are two main programs for reading Info files, ``info`` and GNU
  95 Emacs.  The ``info`` program has less features but is available on
  96 most \*nix environments and can be quickly accessed at the terminal.
  97 Emacs provides better font color displays and supports extensive
  98 customization (of course).
  99
 100
 101 Issues
 102 ======
 103
 104 The conversion of reST to Texinfo is not a seamless transition.  Info
 105 is not as sophisticated as HTML which creates several issues since
 106 most reST documents are geared for HTML output.  The following sections
 107 describe some of these issues.
 108
 109
 110 Displaying Links
 111 ----------------
 112
 113 One noticeable problem you may encounter with the generated Info files
 114 is how references are displayed.  If you read the source of an Info
 115 file, a reference to this section would look like::
 116
 117     * note Displaying Links: target-id
 118
 119 In the stand-alone reader, ``info``, references are displayed just as
 120 they appear in the source.  Emacs, on the other-hand, will by default
 121 replace ``\*note:`` with ``see`` and hide the ``target-id``.  For
 122 example:
 123
 124     `Displaying Links`_
 125
 126 The exact behavior of how Emacs displays references is dependent on
 127 the variable ``Info-hide-note-references``.  If set to the value of
 128 ``hide``, Emacs will hide both the ``\*note:`` part and the
 129 ``target-id``.  This is generally the best way to view reST documents
 130 since they often make frequent use of links and do not take this
 131 limitation into account.  However, changing this variable affects how
 132 all Info documents are displayed and most due take this behavior into
 133 account.
 134
 135 If you want Emacs to display Info files produced by rst2texinfo using the
 136 value ``hide`` for ``Info-hide-note-references`` and the default value
 137 for all other Info files, try adding the following Emacs Lisp code to
 138 your start-up file, ``~/.emacs.d/init.el``.
 139
 140 ::
 141
 142     (defadvice info-insert-file-contents (after
 143                                           docutils-info-insert-file-contents
 144                                           activate)
 145       "Hack to make `Info-hide-note-references' buffer-local and
 146     automatically set to `hide' iff it can be determined that this file
 147     was created from a Texinfo file generated by Docutils or Sphinx."
 148       (set (make-local-variable 'Info-hide-note-references)
 149            (default-value 'Info-hide-note-references))
 150       (save-excursion
 151         (save-restriction
 152           (widen) (goto-char (point-min))
 153           (when (re-search-forward
 154                  "^Generated by \\(Sphinx\\|Docutils\\)"
 155                  (save-excursion (search-forward "\x1f" nil t)) t)
 156             (set (make-local-variable 'Info-hide-note-references)
 157                  'hide)))))
 158
 159
 160 Notes
 161 =====
 162
 163 The following notes may be helpful if you want to create Texinfo
 164 files:
 165
 166 - Each section corresponds to a different ``node`` in the Info file.
 167
 168 - Some characters cannot be properly escaped in menu entries and
 169   xrefs.  The following characters are replaced by spaces in these
 170   contexts: ``@``, ``{``, ``}``, ``.``, ``,``, and ``:``.
 171
 172 - In the HTML and Tex output, the word ``see`` is automatically
 173   inserted before all xrefs.
 174
 175 - Links to external Info files can be created using the somewhat
 176   official URI scheme ``info``.  For example::
 177
 178       info:Texinfo#makeinfo_options
 179
 180   which produces:
 181
 182       info:Texinfo#makeinfo_options
 183
 184 - Inline markup appears as follows in Info:
 185
 186   * strong -- \*strong\*
 187   * emphasis -- _emphasis_
 188   * literal -- \`literal'
 189
 190
 191 Copyright
 192 =========
 193
 194 rst2texinfo and this documentation should have the same license as the
 195 Docutils project.
 196
 197 Copyright © 2010  Jon Waltman. All rights reserved.