1
.. -*- coding: utf-8 -*-
3
========================================
4
Emacs Support for reStructuredText
5
========================================
7
:Author: Martin Blais <blais@furius.ca>
8
:Date: $Date: 2005-11-18 05:26:30 +0100 (Fri, 18 Nov 2005) $
11
High-level description of the existing emacs support for editing
12
reStructuredText text documents. Suggested setup code and usage
13
instructions are provided.
21
reStructuredText_ is a series of conventions that allows a
22
toolset--docutils--to extract generic document structure from simple
23
text files. For people who use Emacs_, there is a package that adds
24
some support for the conventions that reStructuredText_ specifies:
27
This document describes the most important features that it provides,
28
how to setup your emacs to use them and how to invoke them.
34
The emacs support is completely provided by the ``rst.el`` emacs
35
package. In order to use these features, you need to put the file in
36
your emacs load-path, and to load it with::
38
(require 'rst) ;; or (load "rst")
40
Additional configuration variables can be customized and can be found
41
by browsing the source code for ``rst.el``.
43
Then you will want to bind keys to the most common commands it
44
provides. A standard text-mode hook function is maintained and
45
provided by the package for this use, set it up like this::
47
(add-hook 'text-mode-hook 'rst-text-mode-bindings)
49
A prefix map is defined for all the ``rst.el`` commands. By default,
50
it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``.
53
Section Decoration Adjustment
54
=============================
56
The rst package does not completely parse all the reStructuredText_
57
constructs, but it contains the ability to recognize the section
58
decorations and to build the hierarchy of the document. What we call
59
section decorations or adornments are the underlines or under- and
60
overlines used to mark a section title.
62
There is a function that helps a great deal to maintain these
63
decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
64
``C-=`` by default). This function is a Swiss army knife that can be
65
invoked repeatedly and whose behaviour depends on context:
67
#. If there is an incomplete underline, e.g.::
72
Invocation will complete the section title. You can simply enter a
73
few characters of the title and invoke the function to complete it.
74
It can also be used to adjust the length of the existing decoration
75
when you need to edit the title.
77
#. If there is no section decoration, a decoration one level under the
78
last encountered section level is added;
80
#. If there is already a section decoration, it is promoted to the
81
next level. You can invoke it like this repeatedly to cycle the
82
title through the hierarchy of existing decorations.
84
Invoking the function with a negative prefix argument, e.g. ``C--
85
C-=``, will effectively reverse the direction of decoration cycling.
86
To alternate between underline-only and over-and-under styles, you can
87
use a regular prefix argument, e.g. ``C-u C-=``. See the
88
documentation of ``rst-adjust`` for more description of the prefix
89
arguments to alter the behaviour of the function.
92
Promoting and Demoting Many Sections
93
------------------------------------
95
When you are re-organizing the structure of a document, it can be
96
useful to change the level of a number of section titles. The same
97
key binding can be used to do that: if the region is active when the
98
binding is invoked, all the section titles that are within the region
99
are promoted accordingly (or demoted, with negative prefix arg).
105
You can set the variable ``rst-preferred-decorations`` to a list of
106
the decorations that you like to use for documents. Everyone has
107
their preference. ``rst-default-indent`` can be set to the number of
108
indent spaces preferred for the over-and-under decoration style.
111
Viewing the Hierarchy of Section Decorations
112
============================================
114
You can visualize the hierarchy of the section decorations in the
115
current buffer by invoking ``rst-display-decorations-hierarchy``,
116
bound on ``C-c p h``. A temporary buffer will appear with fake
117
section titles rendered in the style of the current document. This
118
can be useful when editing other people's documents to find out which
119
section decorations correspond to which levels.
125
When you are editing long documents, it can be a bit difficult to
126
orient yourself in the structure of your text. To that effect, a
127
function is provided that quickly parses the document and presents a
128
hierarchically indented table of contents of the document in a
129
temporary buffer, in which you can navigate and press ``Return`` to go
130
to a specific section.
132
Invoke this function (``rst-toc``) with ``C-c p t``. It should
133
present a temporary buffer that looks something like this::
136
Debugging Meta-Techniques
138
Debugging Solution Patterns
139
Recognize That a Bug Exists
140
Subdivide and Isolate
141
Identify and Verify Assumptions
142
Use a Tool for Introspection
143
Change one thing at a time
144
Learn about the System
146
The Basic Steps in Debugging
152
When you select a section title, the temporary buffer disappears and
153
you are left with the cursor positioned at the chosen section.
156
Inserting a Table of Contents
157
-----------------------------
159
Oftentimes in long text documents that are meant to be read directly,
160
a Table of Contents is inserted at the beginning of the text. This is
161
the case for most internet FAQs, for example. In reStructuredText_
162
documents, since the table of contents is automatically generated by
163
the parser with the ``.. contents::`` directive, people generally have
164
not been adding a text table of contents to their source documents,
165
and partly because it is too much trouble to edit and maintain.
167
The emacs support for reStructuredText_ provides a function to insert
168
such a table of contents in your document. Since it is not meant to
169
be part of the document text, you should place such a table of
170
contents within a comment, so that it is ignored by the parser. This
171
is the favoured usage::
176
2 Debugging Solution Patterns
177
2.1 Recognize That a Bug Exists
178
2.2 Subdivide and Isolate
179
2.3 Identify and Verify Assumptions
180
2.4 Use a Tool for Introspection
181
2.5 Change one thing at a time
182
2.6 Learn about the System
183
3 Understanding a bug
184
4 The Basic Steps in Debugging
190
Just place the cursor at the top-left corner where you want to insert
191
the TOC and invoke the function with ``C-c p i``. The table of
192
contents will display all the section titles that are under the
193
location where the insertion occurs. This way you can insert local
194
table of contents by placing them in the appropriate location.
196
If you have deep nesting of sections, you can use a numeric prefix
197
argument to limit the depth of rendering of the TOC.
199
You can also customize the look of the TOC by setting the values of
200
the following variables:: ``rst-toc-indent``,
201
``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
204
Maintaining the Table of Contents Up-to-date
205
--------------------------------------------
207
One issue is that you will probably want to maintain the inserted
208
table of contents up-to-date. There is a function that will
209
automatically look for the inserted TOC (``rst-toc-insert-update``)
210
and it can be added to a hook on the section decoration adjustment
211
function, so that every time you adjust a section title, the TOC is
212
updated. Add this functionality with the following emacs
215
(add-hook 'rst-adjust-hook 'rst-toc-insert-update)
217
You can invoke the update on the current buffer with ``C-c p u``.
220
Navigating Between the Section Titles
221
=====================================
223
You can move the cursor between the different sections by using the
224
``rst-backward-section`` and ``rst-forward-section`` functions, by
225
default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c
226
C-p`` and ``C-c C-n``).
229
Shifting Bullet List Levels
230
===========================
232
Due to the nature of reStructuredText_, bullet lists are always
233
indented by two characters (unless they are part of a blockquote),
247
To this effect, when re-organizing bullet lists, it can be useful to
248
shift regions of text by indents of two characters. You can use the
249
``C-c C-r`` and ``C-c C-l`` to shift the current region. These
250
bindings are similar to the ones provided by python-mode for editing
251
python code and behave similarly.
254
Major Mode for Editing reStructuredText Documents
255
=================================================
257
There is a major mode available for editing and syntax highlighting
258
reStructuredText_ constructs. This mode was written by Stefan Merten
259
[#]_. It mostly provides lazy syntax coloring for many of the
260
constructs that reStructuredText_ prescribes.
262
To enable this mode, type ``M-x rst-mode`` or you can set up an
263
``auto-mode-alist`` to automatically turn it on whenever you visit
264
reStructuredText_ documents::
266
(add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
268
If have local variables enabled (see ``enable-local-variables`` in the
269
Emacs manual), you can also add the following at the top of your
270
documents to trigger rst-mode::
274
Or add this at the end of your documents::
281
By default, the font-lock colouring is performed lazily. If you don't
282
like this, you can turn this off by setting the value of
283
``rst-mode-lazy``. You can also change the various colours (see the
284
source file for the whole list of customizable faces).
286
.. [#] This mode used to be provided by the file ``rst-mode.el`` and
287
has now been integrated with the rest of the emacs code.
290
Converting Documents from Emacs
291
===============================
293
At the moment there is minimal support for calling the conversion
294
tools from within Emacs. You can add a key binding like this to
297
(local-set-key [(control c)(?9)] 'rst-compile)
299
This function basically creates a compilation command with the correct
300
output name for the current buffer and then invokes Emacs' compile
301
function. It also looks for the presence of a ``docutils.conf``
302
configuration file in the parent directories and adds it to the
303
cmdline options. You can customize which tool is used to perform the
304
conversion and some standard options to always be added as well.
306
Invocation uses the toolset indicated by
307
``rst-compile-primary-toolset`` (default is ``'html``). Invocation
308
with a prefix argument uses ``rst-compile-secondary-toolset`` (default
313
In general it is preferred to use a Makefile to automate the
314
conversion of many documents or a hierarchy of documents. The
315
functionality presented above is meant to be convenient for use on
319
Other / External Useful Emacs Settings
320
======================================
322
This section covers general emacs text-mode settings that are useful
323
in the context of reStructuredText_ conventions. These are not
324
provided by ``rst.el`` but you may find them useful specifically for
325
reStructuredText_ documents.
328
Settings for Filling Lists
329
--------------------------
331
One problem with the default text-mode settings is that *filling* long
332
lines in bullet and enumerated lists that do not have an empty line
333
between them merges them together, e.g.::
336
- One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
341
- Bananas; One Apple a day keeps the doctor away, and eating more
342
- keeps the pirates at bay; Oranges;
344
This is usually not what you want. What you want is this::
347
- One Apple a day keeps the doctor away, and eating more keeps
351
The problem is that emacs does not recognize the various consecutive
352
items as forming paragraph boundaries. You can fix this easily by
353
changing the global value of the parapraph boundary detection to
354
recognize such lists, using the ``rst-set-paragraph-separation``
357
(add-hook 'text-mode-hook 'rst-set-paragraph-separation)
360
``text-mode`` Settings
361
----------------------
363
Consult the Emacs manual for more text-mode customizations. In
364
particular, you may be interested in setting the following variables,
365
functions and modes that pertain somewhat to text-mode:
374
Editing Tables: Emacs table mode
375
--------------------------------
377
You may want to check out `Emacs table mode`_ to create an edit
378
tables, it allows creating ascii tables compatible with
381
.. _Emacs table mode: http://table.sourceforge.net/
387
Since reStructuredText punts on the issue of character processing,
388
here are some useful resources for Emacs users in the Unicode world:
390
* `xmlunicode.el and unichars.el from Norman Walsh
391
<http://nwalsh.com/emacs/xmlchars/index.html>`__
393
* `An essay by Tim Bray, with example code
394
<http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
396
* For Emacs users on Mac OS X, here are some useful useful additions
399
- To get direct keyboard input of non-ASCII characters (like
400
"option-e e" resulting in "é" [eacute]), first enable the option
401
key by setting the command key as your meta key::
403
(setq mac-command-key-is-meta t) ;; nil for option key
405
Next, use one of these lines::
407
(set-keyboard-coding-system 'mac-roman)
408
(setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
410
I prefer the first line, because it enables non-Latin-1 characters
411
as well (em-dash, curly quotes, etc.).
413
- To enable the display of all characters in the Mac-Roman charset,
414
first create a fontset listing the fonts to use for each range of
415
characters using charsets that Emacs understands::
417
(create-fontset-from-fontset-spec
418
"-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
419
ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
420
latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
421
mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
423
Latin-1 doesn't cover characters like em-dash and curly quotes, so
424
"mule-unicode-0100-24ff" is needed.
426
Next, use that fontset::
428
(set-frame-font "fontset-monaco")
430
- To enable cooperation between the system clipboard and the Emacs
431
kill ring, add this line::
433
(set-clipboard-coding-system 'mac-roman)
435
Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
436
FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
438
No matter what platform (or editor) you're using, I recommend the
439
ProFont__ programmer's font. It's monospaced, small but readable,
440
similar characters are visually distinctive (like "I1l|", "0O", "ao",
441
and ".,:;"), and free.
443
__ http://www.tobias-jung.de/seekingprofont/
449
- The automatic section adjustment and table of contents features were
450
written by Martin Blais;
451
- ``rst-mode`` and its syntax highlighting was implemented by Stefan
453
- Various other functions were implemented by David Goodger.
459
On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and
460
``rst-mode.el`` were merged to form the new ``rst.el``. You can
461
consider the old files obsolete and remove them.
467
Here are some features and ideas that will be worked on in the future,
468
in those frenzied mornings of excitement over the virtues of the
469
one-true-way kitchen sink of editors:
471
- It would be nice to differentiate between text files using
472
reStructuredText_ and other general text files. If we had a
473
function to automatically guess whether a .txt file is following the
474
reStructuredText_ conventions, we could trigger rst-mode without
475
having to hard-code this in every text file, nor forcing the user to
476
add a local mode variable at the top of the file.
478
We could perform this guessing by searching for a valid decoration
479
at the top of the document or searching for reStructuredText_
480
directives further on.
482
- The suggested decorations when adjusting should not have to cycle
483
below one below the last section decoration level preceding the
484
cursor. We need to fix that.
487
.. _Emacs: http://www.gnu.org/software/emacs/emacs.html
488
.. _reStructuredText: http://docutils.sf.net/rst.html
494
indent-tabs-mode: nil
495
sentence-end-double-space: t
added
removed
docs/user/emacs.txt
