|
|
.. -*- coding: utf-8 -*- |
|
|
|
|
|
======================================== |
|
|
Emacs Support for reStructuredText |
|
|
======================================== |
|
|
|
|
|
:Authors: Stefan Merten <stefan@merten-home.de>, Martin Blais |
|
|
<blais@furius.ca> |
|
|
:Version: ``rst.el`` V1.4.1 |
|
|
:Abstract: |
|
|
|
|
|
High-level description of the existing Emacs_ support for editing |
|
|
reStructuredText_ text documents. Suggested setup code and usage |
|
|
instructions are provided. |
|
|
|
|
|
.. contents:: |
|
|
|
|
|
Introduction |
|
|
============ |
|
|
|
|
|
reStructuredText_ is a syntax for simple text files that allows a |
|
|
tool set - docutils_ - to extract generic document structure. For |
|
|
people who use Emacs_, there is a package that adds a major mode that |
|
|
supports editing the syntax of reStructuredText_: ``rst.el``. This |
|
|
document describes the features it provides, and how to setup your |
|
|
Emacs_ to use them and how to invoke them. |
|
|
|
|
|
Installation |
|
|
============ |
|
|
|
|
|
Emacs_ support for reStructuredText_ is implemented as an Emacs_ major |
|
|
mode (``rst-mode``) provided by the ``rst.el`` Emacs_ package. |
|
|
|
|
|
Emacs_ distributions contain ``rst.el`` since version V23.1. However, |
|
|
a significantly updated version of ``rst.el`` is contained in Emacs_ |
|
|
V24.3. This document describes the version of ``rst.el`` contained in |
|
|
Emacs_ V24.3 and later versions. This version of ``rst.el`` has the |
|
|
internal version V1.4.1. |
|
|
|
|
|
If you have Emacs_ V24.3 or later you do not need to install anything |
|
|
to get reST support. If you have an Emacs_ between V23.1 and V24.2 you |
|
|
may use the version of ``rst.el`` installed with Emacs_ or install a |
|
|
more recent one locally_ (recommended). In other cases you need to |
|
|
install ``rst.el`` locally_ to get reST support. |
|
|
|
|
|
Checking situation |
|
|
------------------ |
|
|
|
|
|
Here are some steps to check your situation: |
|
|
|
|
|
#. In Emacs_ switch to an empty buffer and try :: |
|
|
|
|
|
M-x rst-mode |
|
|
|
|
|
If this works you have ``rst.el`` installed somewhere. You can see |
|
|
that it works if you find a string ``ReST`` in Emacs' modeline of |
|
|
the current buffer. If this doesn't work you need to install |
|
|
``rst.el`` yourself locally_. |
|
|
|
|
|
#. In the buffer you just switched to ``rst-mode`` try :: |
|
|
|
|
|
C-h v rst-version |
|
|
|
|
|
If this fails you have a version of ``rst.el`` older than |
|
|
V1.1.0. Either you have an old ``rst.el`` locally or you are using |
|
|
an Emacs_ between V23.1 and V24.2. In this case it is recommended |
|
|
that you install a more recent version of ``rst.el`` locally_. |
|
|
|
|
|
You may also try :: |
|
|
|
|
|
C-h v emacs-version |
|
|
|
|
|
to find out your Emacs_ version. |
|
|
|
|
|
#. Check the version of ``rst.el`` |
|
|
|
|
|
The content of ``rst-version`` gives you the internal version of |
|
|
``rst.el``. The version contained in Emacs_ V24.3 and described here |
|
|
is V1.4.0. If you have an older version you may or may not install |
|
|
a more recent version of ``rst.el`` locally_. |
|
|
|
|
|
.. _locally: |
|
|
|
|
|
Local installation |
|
|
------------------ |
|
|
|
|
|
If you decided to install locally please follow these steps. |
|
|
|
|
|
#. Download ``rst.el`` |
|
|
|
|
|
Download the most recent published version of ``rst.el`` from |
|
|
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/tools/editors/emacs/rst.el |
|
|
|
|
|
#. Put ``rst.el`` to a directory in ``load-path`` |
|
|
|
|
|
Use :: |
|
|
|
|
|
C-h v load-path |
|
|
|
|
|
If in the resulting list you find a directory in your home |
|
|
directory put ``rst.el`` in this directory. |
|
|
|
|
|
Make sure the directory is one of the first entries in |
|
|
``load-path``. Otherwise a version of ``rst.el`` which came with |
|
|
Emacs_ may be found before your local version. |
|
|
|
|
|
In Emacs_ see the info node ``Init File Examples`` for more |
|
|
information on how to set up your Emacs_ initialization |
|
|
machinery. Try :: |
|
|
|
|
|
C-h i |
|
|
mEmacs<Return> |
|
|
sInit File Examples<Return> |
|
|
|
|
|
#. Enable ``rst-mode`` |
|
|
|
|
|
Add the following to your Emacs_ initialization setup :: |
|
|
|
|
|
(require 'rst) |
|
|
|
|
|
After you restarted Emacs_ ``rst.el`` is loaded and ready to be |
|
|
used. |
|
|
|
|
|
Switching ``rst-mode`` on |
|
|
------------------------- |
|
|
|
|
|
By default ``rst-mode`` is switched on for files ending in ``.rst`` or |
|
|
``.rest``. If in a buffer you want to switch ``rst-mode`` on manually |
|
|
use :: |
|
|
|
|
|
M-x rst-mode |
|
|
|
|
|
If you want to use ``rst-mode`` in files with other extensions modify |
|
|
``auto-mode-alist`` to automatically turn it on whenever you visit |
|
|
reStructuredText_ documents:: |
|
|
|
|
|
(setq auto-mode-alist |
|
|
(append '(("\\.txt\\'" . rst-mode) |
|
|
("\\.rst\\'" . rst-mode) |
|
|
("\\.rest\\'" . rst-mode)) auto-mode-alist)) |
|
|
|
|
|
Put the extensions you want in the correct place in the example |
|
|
above. Add more lines if needed. |
|
|
|
|
|
If have local variables enabled (try ``C-h v enable-local-variables`` |
|
|
to find out), you can also add the following at the top of your |
|
|
documents to trigger rst-mode:: |
|
|
|
|
|
.. -*- mode: rst -*- |
|
|
|
|
|
Or this at the end of your documents:: |
|
|
|
|
|
.. |
|
|
Local Variables: |
|
|
mode: rst |
|
|
End: |
|
|
|
|
|
Key bindings |
|
|
============ |
|
|
|
|
|
``rst-mode`` automatically binds several keys for invoking special |
|
|
functions for editing reStructuredText_. Since ``rst-mode`` contains a |
|
|
lot of functionality most key bindings consist of three |
|
|
keystrokes. |
|
|
|
|
|
Following the Emacs_ conventions for major modes the key bindings of |
|
|
``rst-mode`` start with ``C-c C-<letter>``. The second key stroke |
|
|
selects a group of key bindings: |
|
|
|
|
|
C-c C-a |
|
|
Commands to adjust the section headers and work with the hierarchy |
|
|
they build. |
|
|
|
|
|
C-c C-c |
|
|
Commands to compile the current reStructuredText_ document to |
|
|
various output formats. |
|
|
|
|
|
C-c C-l |
|
|
Commands to work with lists of various kinds. |
|
|
|
|
|
C-c C-r |
|
|
Commands to manipulate the current region. |
|
|
|
|
|
C-c C-t |
|
|
Commands to create and manipulate a table of contents. |
|
|
|
|
|
At any stage of typing you may use ``C-h`` to get help on the |
|
|
available key bindings. I.e. ``C-c C-h`` gives you help on all key |
|
|
bindings while ``C-c C-r C-h`` gives you help on the commands for |
|
|
regions. This is handy if you forgot a certain key binding. |
|
|
|
|
|
Additional key bindings which have a certain meaning in other Emacs_ |
|
|
modes are reused in ``rst-mode`` so you don't have to learn a |
|
|
different set of key bindings for editing reStructuredText_. |
|
|
|
|
|
In ``rst-mode`` try :: |
|
|
|
|
|
C-h m |
|
|
|
|
|
to list all mode specific key bindings. Most of the key bindings are |
|
|
described in this tutorial. |
|
|
|
|
|
.. note:: The key bindings have been completely revamped in ``rst.el`` |
|
|
V1.0.0. This was necessary to make room for new |
|
|
functionality. Some of the old bindings still work but give |
|
|
a warning to use the new binding. In the output of ``C-h m`` |
|
|
these bindings show up as ``rst-deprecated-...``. The old |
|
|
bindings will be removed completely in a later version. |
|
|
|
|
|
Section Adornments |
|
|
================== |
|
|
|
|
|
``rst-mode`` recognizes the section adornments building the section |
|
|
hierarchy of the document. Section adornments are the underlines or |
|
|
under- and overlines used to mark a section title. There are a couple |
|
|
of commands to work with section adornments. These commands are bound |
|
|
to key bindings starting with ``C-c C-a``. |
|
|
|
|
|
Adjusting a Section Title |
|
|
------------------------- |
|
|
|
|
|
There is a function that helps a great deal to maintain these |
|
|
adornments: ``rst-adjust`` (bound to ``C-c C-a C-a``, ``C-c C-=``, and |
|
|
``C-=``). This function is a Swiss army knife that can be invoked |
|
|
repeatedly and whose behavior depends on context: |
|
|
|
|
|
#. If there is an incomplete adornment, e.g. :: |
|
|
|
|
|
My Section Title |
|
|
== |
|
|
|
|
|
invocation will complete the adornment. It can also be used to |
|
|
adjust the length of the existing adornment when you need to edit |
|
|
the title. |
|
|
|
|
|
#. If there is no section adornment at all, by default an adornment of |
|
|
the same level as the last encountered section level is added. You |
|
|
can simply enter a few characters of the title and invoke the |
|
|
function to create the section adornment. |
|
|
|
|
|
The variable ``rst-new-adornment-down`` can be customized to create |
|
|
one level lower adornments than the previous section title instead |
|
|
of keeping the level. |
|
|
|
|
|
#. If there is already a section adornment, it is promoted one level |
|
|
up. You can invoke it like this repeatedly to cycle the title |
|
|
through the hierarchy of existing adornments. |
|
|
|
|
|
Invoking the function with a negative prefix argument, e.g. ``C-- |
|
|
C-=``, will effectively reverse the direction of adornment cycling. |
|
|
To alternate between underline-only and over-and-under styles, you can |
|
|
use a regular prefix argument, e.g. ``C-u C-=``. See the |
|
|
documentation of ``rst-adjust`` for more description of the prefix |
|
|
arguments to alter the behavior of the function. |
|
|
|
|
|
Promoting and Demoting Many Sections |
|
|
------------------------------------ |
|
|
|
|
|
When you are re-organizing the structure of a document, it can be |
|
|
useful to change the level of a number of section titles. The same |
|
|
key binding can be used to do that: if the region is active when the |
|
|
binding is invoked, all the section titles that are within the region |
|
|
are promoted accordingly (or demoted, with negative prefix argument). |
|
|
|
|
|
Redoing All the Adornments to Your Taste |
|
|
---------------------------------------- |
|
|
|
|
|
If you open someone else's file and the adornments it contains are |
|
|
unfamiliar, you may want to readjust them to fit your own preferred |
|
|
hierarchy of adornments. This can be difficult to perform by hand. |
|
|
However, you can do this easily by invoking |
|
|
``rst-straighten-adornments`` (``C-c C-a C-s``), which operates on the |
|
|
entire buffer. |
|
|
|
|
|
Customizations for Adornments |
|
|
----------------------------- |
|
|
|
|
|
You can customize the variable ``rst-preferred-adornments`` to a list |
|
|
of the adornments that you like to use for documents. |
|
|
|
|
|
If you prefer adornments according to |
|
|
http://sphinx-doc.org/rest.html#sections you may customize it to end |
|
|
up with a value like this:: |
|
|
|
|
|
((35 over-and-under 0) ; ?# |
|
|
(42 over-and-under 0) ; ?* |
|
|
(61 simple 0) ; ?= |
|
|
(45 simple 0) ; ?- |
|
|
(94 simple 0) ; ?^ |
|
|
(34 simple 0)) ; ?" |
|
|
|
|
|
This will become the default in a later version of ``rst.el``. |
|
|
|
|
|
If you set ``rst-preferred-adornments`` to nil resembling the empty |
|
|
list only the section adornment found in the buffer will be used. |
|
|
|
|
|
Viewing the Hierarchy of Section Adornments |
|
|
------------------------------------------- |
|
|
|
|
|
You can visualize the hierarchy of the section adornments in the |
|
|
current buffer by invoking ``rst-display-adornments-hierarchy``, bound |
|
|
on ``C-c C-a C-d``. A temporary buffer will appear with fake section |
|
|
titles rendered in the style of the current document. This can be |
|
|
useful when editing other people's documents to find out which section |
|
|
adornments correspond to which levels. |
|
|
|
|
|
Movement and Selection |
|
|
====================== |
|
|
|
|
|
Movement and Selection for Sections |
|
|
----------------------------------- |
|
|
|
|
|
You can move the cursor between the different section titles by using |
|
|
the ``rst-backward-section`` (``C-M-a``) and ``rst-forward-section`` |
|
|
(``C-M-e``). To mark the section that cursor lies in, use |
|
|
``rst-mark-section`` (``C-M-h``). |
|
|
|
|
|
The key bindings are modeled after other modes with similar |
|
|
functionality. |
|
|
|
|
|
Movements and Selection for Text Blocks |
|
|
--------------------------------------- |
|
|
|
|
|
The understanding of reStructuredText_ of ``rst-mode`` is used to set |
|
|
all the variables influencing Emacs' understanding of paragraphs. Thus |
|
|
all operations on paragraphs work as usual. For instance |
|
|
``forward-paragraph`` (``M-}``) works as usual. |
|
|
|
|
|
Indenting and Filling |
|
|
===================== |
|
|
|
|
|
Indentation of text plays a major role in the syntax of |
|
|
reStructuredText_. It is tedious to maintain the indentation |
|
|
manually. ``rst-mode`` understands most of the structure of |
|
|
reStructuredText_ allowing for sophisticated indentation and filling |
|
|
support described in this section. |
|
|
|
|
|
Indenting Text Blocks |
|
|
--------------------- |
|
|
|
|
|
``rst-mode`` supports indentation of text blocks by the command |
|
|
``rst-shift-region`` (``C-c C-r TAB``). Mark a region and use ``C-c |
|
|
C-r TAB`` to indent all blocks one tab to the right. Use ``M-- C-c C-r |
|
|
TAB`` to indent the region one tab to the left. |
|
|
|
|
|
You may use arbitrary prefix arguments such as ``M-2`` or ``M-- 2`` to |
|
|
determine the number of tabs you want to indent. A prefix of ``M-0`` |
|
|
removes all indentation in the active region. |
|
|
|
|
|
A tab is an indentation making sense for the block at hand in |
|
|
reStructuredText_ syntax. In some cases the exact indentation depends |
|
|
on personal taste. You may customize a couple of variables ``M-x |
|
|
customize-group<RET> rst-indent<RET>`` to match your taste. |
|
|
|
|
|
Indenting Lines While Typing |
|
|
---------------------------- |
|
|
|
|
|
In Emacs_ the ``TAB`` key is often used for indenting the current |
|
|
line. ``rst-mode`` implements this for the sophisticated indentation |
|
|
rules of reStructuredText_. Pressing ``TAB`` cycles through the |
|
|
possible tabs for the current line. In the same manner |
|
|
``newline-and-indent`` (``C-j``) indents the new line properly. |
|
|
|
|
|
This is very handy while writing lists. Consider this |
|
|
reStructuredText_ bullet list with the cursor at ``@``:: |
|
|
|
|
|
* Level 1 |
|
|
|
|
|
* Level 2@ |
|
|
|
|
|
Type ``C-j`` twice to get this:: |
|
|
|
|
|
* Level 1 |
|
|
|
|
|
* Level 2 |
|
|
|
|
|
@ |
|
|
|
|
|
Now you an enter text at this level, or start a new list item by |
|
|
typing another ``*``. Or you may type ``TAB`` to reduce the |
|
|
indentation once:: |
|
|
|
|
|
* Level 1 |
|
|
|
|
|
* Level 2 |
|
|
|
|
|
@ |
|
|
|
|
|
Typing another ``TAB`` gets you to the first level:: |
|
|
|
|
|
* Level 1 |
|
|
|
|
|
* Level 2 |
|
|
|
|
|
@ |
|
|
|
|
|
.. note:: Since Emacs_ V24.4 ``electric-indent-mode`` is globally on. |
|
|
This breaks indentation in ``rst-mode`` and renders |
|
|
``rst-mode`` mostly useless. This is fixed in V1.4.1 of |
|
|
``rst-mode``. |
|
|
|
|
|
A quick fix for older versions of ``rst.el`` is to add the |
|
|
following line at the end of the ``(define-derived-mode |
|
|
rst-mode ...`` block in your copy of ``rst.el``:: |
|
|
|
|
|
(setq electric-indent-inhibit t) |
|
|
|
|
|
You may also install V1.4.1 or newer locally_. |
|
|
|
|
|
Filling |
|
|
------- |
|
|
|
|
|
``rst-mode`` understanding the indentation rules of reStructuredText_ |
|
|
also supports filling paragraphs. Just use ``fill-paragraph`` |
|
|
(``M-q``) as you do in other modes. |
|
|
|
|
|
Operating on Lists |
|
|
================== |
|
|
|
|
|
Lists are supported in various flavors in reStructuredText_. |
|
|
``rst-mode`` understands reStructuredText_ lists and offers some |
|
|
support for operating on lists. Key bindings for commands for |
|
|
operating on lists start with ``C-c C-l``. |
|
|
|
|
|
Please note that so far definition lists are not explicitly supported |
|
|
by ``rst-mode``. |
|
|
|
|
|
Bulleted and Enumerated Lists |
|
|
----------------------------- |
|
|
|
|
|
If you have a couple of plain lines you want to turn into an |
|
|
enumerated list you can invoke ``rst-enumerate-region`` (``C-c C-l |
|
|
C-e``). For example, the following region :: |
|
|
|
|
|
Apples |
|
|
|
|
|
Oranges |
|
|
|
|
|
Bananas |
|
|
|
|
|
becomes :: |
|
|
|
|
|
1. Apples |
|
|
|
|
|
2. Oranges |
|
|
|
|
|
3. Bananas |
|
|
|
|
|
``rst-bullet-list-region`` (``C-c C-l C-b``) does the same, but |
|
|
results in a bullet list :: |
|
|
|
|
|
* Apples |
|
|
|
|
|
* Oranges |
|
|
|
|
|
* Bananas |
|
|
|
|
|
By default, each paragraph starting on the leftmost line in the |
|
|
highlighted region will be taken to be a single list or enumeration |
|
|
item, for example, enumerating the following:: |
|
|
|
|
|
An apple a day |
|
|
keeps the doctor away. |
|
|
|
|
|
But oranges |
|
|
are tastier than apples. |
|
|
|
|
|
If you preferred bananas |
|
|
you may be |
|
|
a monkey. |
|
|
|
|
|
Will result in:: |
|
|
|
|
|
1. An apple a day |
|
|
keeps the doctor away. |
|
|
|
|
|
2. But oranges |
|
|
are tastier than apples. |
|
|
|
|
|
3. If you preferred bananas |
|
|
you may be |
|
|
a monkey. |
|
|
|
|
|
If you would like to enumerate each of the lines, use a prefix |
|
|
argument on the preceding commands, e.g.:: |
|
|
|
|
|
Apples |
|
|
Oranges |
|
|
Bananas |
|
|
|
|
|
becomes:: |
|
|
|
|
|
* Apples |
|
|
* Oranges |
|
|
* Bananas |
|
|
|
|
|
Straightening Existing Bullet List Hierarchies |
|
|
---------------------------------------------- |
|
|
|
|
|
If you invoke ``rst-straighten-bullets-region`` (``C-c C-l C-s``), the |
|
|
existing bullets in the active region will be replaced to reflect |
|
|
their respective level. This does not make a difference in the |
|
|
document structure that reStructuredText_ defines, but looks better |
|
|
in, for example, if all of the top-level bullet items use the |
|
|
character ``-``, and all of the 2nd level items use ``*``, etc. |
|
|
|
|
|
Inserting a List Item |
|
|
--------------------- |
|
|
|
|
|
To start a new list you may invoke ``rst-insert-list`` (``C-c C-l |
|
|
C-i``). You may choose from an item style supported by |
|
|
reStructuredText_. |
|
|
|
|
|
You may also invoke ``rst-insert-list`` at the end of a list item. In |
|
|
this case it inserts a new line containing the markup for the a list |
|
|
item on the same level. |
|
|
|
|
|
Operating on Other Text Blocks |
|
|
============================== |
|
|
|
|
|
Creating and Removing Line Blocks |
|
|
--------------------------------- |
|
|
|
|
|
To create line blocks, first select the region to convert and invoke |
|
|
``rst-line-block-region`` ``C-c C-r C-l``. For example, the following |
|
|
:: |
|
|
|
|
|
Apples |
|
|
Oranges |
|
|
Bananas |
|
|
|
|
|
becomes :: |
|
|
|
|
|
| Apples |
|
|
| Oranges |
|
|
| Bananas |
|
|
|
|
|
This works even if the region is indented. To remove line blocks, |
|
|
select a region and invoke with a prefix argument. |
|
|
|
|
|
Commenting a Region of Text |
|
|
--------------------------- |
|
|
|
|
|
``rst-mode`` understands reStructuredText_ comments. Use |
|
|
``comment-dwim`` (``M-;``) to work on comments as usual:: |
|
|
|
|
|
Apples |
|
|
Oranges |
|
|
Bananas |
|
|
|
|
|
becomes:: |
|
|
|
|
|
.. |
|
|
Apples |
|
|
Oranges |
|
|
Bananas |
|
|
|
|
|
To remove a comment you have to tell this to ``comment-dwim`` |
|
|
explicitly by using a prefix argument (``C-u M-;``). |
|
|
|
|
|
Please note that only indented comments are supported properly by the |
|
|
parts of ``comment-dwim`` working on regions. |
|
|
|
|
|
.. _Conversion: |
|
|
|
|
|
Converting Documents from Emacs |
|
|
=============================== |
|
|
|
|
|
``rst-mode`` provides a number of functions for running documents |
|
|
being edited through the docutils tools. The key bindings for these |
|
|
commands start with ``C-c C-c``. |
|
|
|
|
|
The main generic function is ``rst-compile`` (``C-c C-c C-c``). It |
|
|
invokes a compilation command with the correct output name for the |
|
|
current buffer and then invokes Emacs' compile function. It also looks |
|
|
for the presence of a ``docutils.conf`` configuration file in the |
|
|
parent directories and adds it to the command line options. There is also |
|
|
``rst-compile-alt-toolset`` (``C-c C-c C-a``) in case you often need |
|
|
run your document in a second toolset. |
|
|
|
|
|
You can customize the commands being used by setting |
|
|
``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``. |
|
|
|
|
|
Other commands are available for other formats: |
|
|
|
|
|
* ``rst-compile-pseudo-region`` (``C-c C-c C-x``) |
|
|
|
|
|
When crafting documents, it is often convenient to view which data |
|
|
structures docutils will parse them into. You can use to run the |
|
|
active region through ``rst2pseudoxml.py`` and have the output |
|
|
automatically be displayed in a new buffer. |
|
|
|
|
|
* ``rst-compile-pdf-preview`` (``C-c C-c C-p``) |
|
|
|
|
|
Convert the current document to PDF and launch a viewer on the |
|
|
results. |
|
|
|
|
|
* ``rst-compile-slides-preview`` (``C-c C-c C-s``): Convert the |
|
|
current document to S5 slides and view in a web browser. |
|
|
|
|
|
Imenu Support |
|
|
============= |
|
|
|
|
|
Using Imenu |
|
|
----------- |
|
|
|
|
|
Emacs_ has a package called ``imenu``. ``rst-mode`` supports Imenu by |
|
|
adding a function to convert the structure of a reStructuredText_ |
|
|
buffer to an Imenu index. Thus you can use invoke ``imenu`` (``M-x |
|
|
imenu``) to navigate through the section index or invoke |
|
|
``imenu-add-to-menubar`` (``M-x imenu-add-to-menubar``) to add an |
|
|
Imenu menu entry to Emacs' menu bar. |
|
|
|
|
|
Using which function |
|
|
-------------------- |
|
|
|
|
|
As a side effect of Imenu support the ``which-func`` package is also |
|
|
supported. Invoke ``which-function-mode`` (``M-x |
|
|
which-function-mode``) to add the name of the current section to the |
|
|
mode line. This is especially useful if you navigate through documents |
|
|
with long sections which do not fit on a single screen. |
|
|
|
|
|
Using the Table of Contents |
|
|
=========================== |
|
|
|
|
|
The sections in a reStructuredText_ document can be used to form a |
|
|
table of contents. ``rst-mode`` can work with such a table of contents |
|
|
in various forms. Key bindings for these commands start with ``C-c |
|
|
C-t``. |
|
|
|
|
|
Navigating Using the Table of Contents |
|
|
-------------------------------------- |
|
|
|
|
|
When you are editing long documents, it can be a bit difficult to |
|
|
orient yourself in the structure of your text. To that effect, a |
|
|
function is provided that presents a hierarchically indented table of |
|
|
contents of the document in a temporary buffer, in which you can |
|
|
navigate and press ``Return`` to go to a specific section. |
|
|
|
|
|
Invoke ``rst-toc`` (``C-c C-t C-t``). It presents a temporary buffer |
|
|
that looks something like this:: |
|
|
|
|
|
Table of Contents: |
|
|
Debugging Meta-Techniques |
|
|
Introduction |
|
|
Debugging Solution Patterns |
|
|
Recognize That a Bug Exists |
|
|
Subdivide and Isolate |
|
|
Identify and Verify Assumptions |
|
|
Use a Tool for Introspection |
|
|
Change one thing at a time |
|
|
Learn about the System |
|
|
Understanding a bug |
|
|
The Basic Steps in Debugging |
|
|
Attitude |
|
|
Bad Feelings |
|
|
Good Feelings |
|
|
References |
|
|
|
|
|
When you move the cursor to a section title and press ``RET`` or ``f`` |
|
|
or click with ``button1`` on a section title, the temporary buffer |
|
|
disappears and you are left with the cursor positioned at the chosen |
|
|
section. Clicking with ``button2`` jumps to the respective section but |
|
|
keeps the toc buffer. You can use this to look at the various section |
|
|
headers quickly. Use ``q`` in this buffer to just quit it without |
|
|
moving the cursor in the original document. Use ``z`` to zap the |
|
|
buffer altogether. |
|
|
|
|
|
Inserting a Table of Contents |
|
|
----------------------------- |
|
|
|
|
|
Oftentimes in long text documents that are meant to be read directly, |
|
|
a table of contents is inserted at the beginning of the text. In |
|
|
reStructuredText_ documents, since the table of contents is |
|
|
automatically generated by the parser with the ``.. contents::`` |
|
|
directive, people generally have not been adding an explicit table of |
|
|
contents to their source documents, and partly because it is too much |
|
|
trouble to edit and maintain. |
|
|
|
|
|
The Emacs_ support for reStructuredText_ provides a function to insert |
|
|
such a table of contents in your document. Since it is not meant to |
|
|
be part of the document text, you should place such a table of |
|
|
contents within a comment, so that it is ignored by the parser. This |
|
|
is the favored usage:: |
|
|
|
|
|
.. contents:: |
|
|
.. |
|
|
1 Introduction |
|
|
2 Debugging Solution Patterns |
|
|
2.1 Recognize That a Bug Exists |
|
|
2.2 Subdivide and Isolate |
|
|
2.3 Identify and Verify Assumptions |
|
|
2.4 Use a Tool for Introspection |
|
|
2.5 Change one thing at a time |
|
|
2.6 Learn about the System |
|
|
3 Understanding a bug |
|
|
4 The Basic Steps in Debugging |
|
|
5 Attitude |
|
|
5.1 Bad Feelings |
|
|
5.2 Good Feelings |
|
|
6 References |
|
|
|
|
|
Just place the cursor at the top-left corner where you want to insert |
|
|
the TOC and invoke the function ``rst-toc-insert`` with ``C-c C-t |
|
|
C-i``. The table of contents will display all the section titles that |
|
|
are under the location where the insertion occurs. This way you can |
|
|
insert local table of contents by placing them in the appropriate |
|
|
location. |
|
|
|
|
|
You can use a numeric prefix argument to limit the depth of rendering |
|
|
of the TOC. |
|
|
|
|
|
You can customize the look of the TOC by setting the values of the |
|
|
following variables: ``rst-toc-indent``, ``rst-toc-insert-style``, |
|
|
``rst-toc-insert-max-level``. |
|
|
|
|
|
Maintaining the Table of Contents Up-to-date |
|
|
-------------------------------------------- |
|
|
|
|
|
One issue is that you will probably want to maintain the inserted |
|
|
table of contents up-to-date. ``rst-toc-update`` (``C-c C-t C-u``) |
|
|
will automatically update an inserted table of contents following a |
|
|
``.. contents::`` directive laid out like the example above. |
|
|
|
|
|
Syntax Highlighting via Font-Lock |
|
|
================================= |
|
|
|
|
|
``rst-mode`` provides syntax highlighting for nearly all to |
|
|
reStructuredText_ constructs. |
|
|
|
|
|
Use ``customize-group rst-faces`` to customize the faces used for |
|
|
font-locking. |
|
|
|
|
|
Customization |
|
|
============= |
|
|
|
|
|
Some aspects of ``rst-mode`` can be configured through the |
|
|
customization feature of Emacs_. Try :: |
|
|
|
|
|
M-x customize-group<RETURN>rst |
|
|
|
|
|
for all customizations or use the respective menu entry. Those |
|
|
customizations which are useful for many people are described in this |
|
|
section. |
|
|
|
|
|
Customizing Section Title Formatting |
|
|
------------------------------------ |
|
|
|
|
|
For a couple of things the reStructuredText_ syntax offers a choice of |
|
|
options on how to do things exactly. Some of these choices influence |
|
|
the operation of ``rst.el`` and thus can be configured. The |
|
|
customizations are contained in the ``rst-adjust`` group. |
|
|
|
|
|
Among these things is the exact layout of section adornments. In fact |
|
|
reStructuredText_ prescribes only the characters and how these |
|
|
characters must be used but the exact use of concrete adornments may |
|
|
be different in every source file. Using the customization option |
|
|
``rst-preferred-adornments`` you can tell ``rst-mode`` on the exact |
|
|
sequence of adornments you prefer to markup the different levels of |
|
|
sections headers. |
|
|
|
|
|
Finally the title text of over-and-under adornments may be indented in |
|
|
reStructuredText_. ``rst-default-indent`` tells ``rst-mode`` how many |
|
|
positions a over-and-under adornment should be indented when toggling |
|
|
from simple adornment and in case a consistent indentation throughout |
|
|
the whole buffer for such adornment is needed. |
|
|
|
|
|
Customizing Indentation |
|
|
----------------------- |
|
|
|
|
|
reStructuredText_ uses indentation a lot to signify a certain meaning. |
|
|
In some cases the exact amount of indentation is prescribed by the |
|
|
syntax while in some cases the exact indentation is not fixed. The |
|
|
customization group ``rst-indent`` allows to customize the amount of |
|
|
indentation in these cases. |
|
|
|
|
|
In field lists the content of a field needs to be indented relative to |
|
|
the field label. ``rst-indent-field`` tells ``rst-mode`` the amount of |
|
|
indentation to use for field content. A value of zero always indents |
|
|
according to the content after the field label. |
|
|
|
|
|
The indentation of literal blocks is controlled by |
|
|
``rst-indent-literal-normal`` and ``rst-indent-literal-minimized``. |
|
|
The first is used when the leading literal tag (``::``) appears alone |
|
|
on a line. The second is used when the minimized style is used where |
|
|
the literal tag follows some text. |
|
|
|
|
|
The indentation of comments is controlled by ``rst-indent-comment``. |
|
|
Of course this makes only sense for the indented comments of |
|
|
reStructuredText_. |
|
|
|
|
|
Customization option ``rst-indent-width`` gives the default |
|
|
indentation when there are no other hints on what amount of |
|
|
indentation to use. |
|
|
|
|
|
Customizing Faces |
|
|
----------------- |
|
|
|
|
|
The faces used for font-locking can be defined in the ``rst-faces`` |
|
|
customization group. The customization options ending in ``-face`` are |
|
|
only there for backward compatibility so please leave them as they |
|
|
are. |
|
|
|
|
|
reStructuredText_ sets no limit on the nesting of sections. By default |
|
|
there are six levels of fontification defined. Section titles deeper |
|
|
than six level have no special fontification - only the adornments are |
|
|
fontified. The exact mapping from a level to a face is done by by |
|
|
``rst-adornment-faces-alist``, however. So if you need fontification |
|
|
deeper than six levels you may want to customize this option. You may |
|
|
also want to customize it if you like the general idea of section |
|
|
title fontification in ``rst-mode`` but for instance prefer a reversed |
|
|
order. |
|
|
|
|
|
Customizing Conversion |
|
|
---------------------- |
|
|
|
|
|
Conversion_ can be customized by the customization options in the |
|
|
customization group ``rst-compile``. |
|
|
|
|
|
If some conversion does not work as expected please check |
|
|
the variable ``rst-compile-toolsets`` :: |
|
|
|
|
|
M-x customize-option<RETURN>rst-compile-toolsets |
|
|
|
|
|
This variable defines the commands and other details used for |
|
|
conversion. In case of problems please check that the commands are |
|
|
either available or customize them to what is available in your |
|
|
environment. |
|
|
|
|
|
.. note:: There are some options in V1.4.1 of ``rst.el`` which should |
|
|
be customization options but are not yet. Customization |
|
|
support will be added in a later version. |
|
|
|
|
|
.. note:: Please note that there is a package ``rst2pdf`` based on the |
|
|
ReportLab library. Please note that the command of this |
|
|
package requires an additional ``-o`` for naming the output |
|
|
file. This breaks the usual conventions employed by Docutils |
|
|
tools. ``rst-mode`` V1.4.1 does not support this directly. |
|
|
|
|
|
Other Customizations |
|
|
-------------------- |
|
|
|
|
|
``rst-preferred-bullets`` can be customized to hold your preferred set |
|
|
of bullets to use for bulleted lists. |
|
|
|
|
|
``rst-mode-hook`` is a normal major mode hook which may be customized. |
|
|
It is run if you enter ``rst-mode``. |
|
|
|
|
|
Related aspects |
|
|
=============== |
|
|
|
|
|
This section covers some general aspects using Emacs_ for editing |
|
|
reStructuredText_ source. They are not directly related to |
|
|
``rst-mode`` but may enhance your experience. |
|
|
|
|
|
``text-mode`` Settings |
|
|
---------------------- |
|
|
|
|
|
Consult the Emacs_ manual for more ``text-mode`` customizations. In |
|
|
particular, you may be interested in setting the following variables, |
|
|
functions and modes that pertain somewhat to ``text-mode``: |
|
|
|
|
|
* ``indent-tabs-mode`` |
|
|
* ``colon-double-space`` |
|
|
* ``sentence-end-double-space`` |
|
|
* ``auto-fill-mode`` |
|
|
* ``auto-mode-alist`` |
|
|
|
|
|
Editing Tables: Emacs table mode |
|
|
-------------------------------- |
|
|
|
|
|
You may want to check out `Emacs table mode`_ to create an edit |
|
|
tables, it allows creating ASCII tables compatible with |
|
|
reStructuredText_. |
|
|
|
|
|
.. _Emacs table mode: http://table.sourceforge.net/ |
|
|
|
|
|
Character Processing |
|
|
-------------------- |
|
|
|
|
|
Since reStructuredText punts on the issue of character processing, |
|
|
here are some useful resources for Emacs_ users in the Unicode world: |
|
|
|
|
|
* `xmlunicode.el and unichars.el from Norman Walsh |
|
|
<http://nwalsh.com/emacs/xmlchars/index.html>`__ |
|
|
|
|
|
* `An essay by Tim Bray, with example code |
|
|
<http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__ |
|
|
|
|
|
* For Emacs_ users on Mac OS X, here are some useful useful additions |
|
|
to your .emacs file. |
|
|
|
|
|
- To get direct keyboard input of non-ASCII characters (like |
|
|
"option-e e" resulting in "é" [eacute]), first enable the option |
|
|
key by setting the command key as your meta key:: |
|
|
|
|
|
(setq mac-command-key-is-meta t) ;; nil for option key |
|
|
|
|
|
Next, use one of these lines:: |
|
|
|
|
|
(set-keyboard-coding-system 'mac-roman) |
|
|
(setq mac-keyboard-text-encoding kTextEncodingISOLatin1) |
|
|
|
|
|
I prefer the first line, because it enables non-Latin-1 characters |
|
|
as well (em-dash, curly quotes, etc.). |
|
|
|
|
|
- To enable the display of all characters in the Mac-Roman charset, |
|
|
first create a fontset listing the fonts to use for each range of |
|
|
characters using charsets that Emacs_ understands:: |
|
|
|
|
|
(create-fontset-from-fontset-spec |
|
|
"-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco, |
|
|
ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, |
|
|
latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, |
|
|
mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman") |
|
|
|
|
|
Latin-1 doesn't cover characters like em-dash and curly quotes, so |
|
|
"mule-unicode-0100-24ff" is needed. |
|
|
|
|
|
Next, use that fontset:: |
|
|
|
|
|
(set-frame-font "fontset-monaco") |
|
|
|
|
|
- To enable cooperation between the system clipboard and the Emacs_ |
|
|
kill ring, add this line:: |
|
|
|
|
|
(set-clipboard-coding-system 'mac-roman) |
|
|
|
|
|
Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X |
|
|
FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__. |
|
|
|
|
|
Credits |
|
|
======= |
|
|
|
|
|
Part of the original code of ``rst.el`` has been written by Martin |
|
|
Blais and David Goodger and Wei-Wei Guo. The font-locking came from |
|
|
Stefan Merten. |
|
|
|
|
|
Most of the code has been modified, enhanced and extended by Stefan |
|
|
Merten who also is the current maintainer of ``rst.el``. |
|
|
|
|
|
.. _Emacs: http://www.gnu.org/software/emacs/emacs.html |
|
|
.. _reStructuredText: http://docutils.sf.net/rst.html |
|
|
.. _Docutils: http://docutils.sf.net/ |
|
|
|
|
|
|
|
|
|
|
|
.. LocalWords: reST utf Merten Blais rst el docutils modeline emacs |
|
|
.. LocalWords: Init mEmacs sInit alist setq txt overlines RET nd py |
|
|
.. LocalWords: dwim conf toolset pseudoxml pdf Imenu imenu menubar |
|
|
.. LocalWords: func toc xmlunicode unichars eacute charset fontset |
|
|
.. LocalWords: kTextEncodingISOLatin charsets monaco ascii latin |
|
|
.. LocalWords: iso unicode Choi's Goodger Guo |
|
|
|
|
|
.. |
|
|
Local Variables: |
|
|
mode: rst |
|
|
indent-tabs-mode: nil |
|
|
fill-column: 70 |
|
|
End:
|
|
|
|
