diff options
Diffstat (limited to 'doc/faq.rst')
| -rw-r--r-- | doc/faq.rst | 121 |
1 files changed, 59 insertions, 62 deletions
diff --git a/doc/faq.rst b/doc/faq.rst index bd516a5f..0c2d2c4f 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -155,92 +155,89 @@ some notes: 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. +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). -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:: +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: +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 +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``. +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 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))))) + (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 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: +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 ``:``. +- 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. +- 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:: +- Links to external Info files can be created using the somewhat official URI + scheme ``info``. For example:: - info:Texinfo#makeinfo_options + info:Texinfo#makeinfo_options which produces: - info:Texinfo#makeinfo_options + info:Texinfo#makeinfo_options - Inline markup appears as follows in Info: @@ -249,11 +246,11 @@ files: * 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{}` - """} + ``@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{}` + """} |