"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "docutils-0.5/docs/user/emacs.txt" of archive docutils-0.5.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 .. -*- coding: utf-8 -*-
2
3 ========================================
4 Emacs Support for reStructuredText
5 ========================================
6
7 :Author: Martin Blais <blais@furius.ca>
8 :Date: 2007-12-03
9 :Abstract:
10
11 High-level description of the existing emacs support for editing
12 reStructuredText text documents. Suggested setup code and usage
13 instructions are provided.
14
15 .. contents::
16 ..
17 1 Introduction
18 2 Installation
19 3 Section Decorations
20 3.1 Adjusting a Section Title
21 3.2 Promoting and Demoting Many Sections
22 3.3 Redoing All the Decorations to Your Taste
23 3.4 Customizations for Decorations
24 3.5 Viewing the Hierarchy of Section Decorations
25 4 Section Movement and Selection
26 5 Operating on Blocks of Text
27 5.1 Shifting Text Horizontally Intelligently
28 5.2 Bulleting and Enumerating Lists
29 5.2.1 Straightening Existing Bullet List Hierarchies
30 5.3 Creating and Removing Line Blocks
31 5.4 Commenting a Region of Text
32 6 Converting Documents from Emacs
33 7 Table-of-Contents Features
34 7.1 Inserting a Table of Contents
35 7.2 Maintaining the Table of Contents Up-to-date
36 8 Syntax Highlighting via Font-Lock
37 8.1 Face Customization
38 8.1.1 Default Fonts
39 9 Other Useful Settings
40 9.1 ``text-mode`` Settings
41 9.2 Editing Tables: Emacs table mode
42 9.3 Character Processing
43 10 Credits
44 10.1 Obsolete Files
45 11 Future Work
46
47
48 Introduction
49 ============
50
51 reStructuredText_ is a series of conventions that allows a
52 toolset--docutils--to extract generic document structure from simple
53 text files. For people who use Emacs_, there is a package that adds a
54 major mode that supports editing in the conventions of
55 reStructuredText_: ``rst.el``. This document describes the features it
56 provides, and how to setup your emacs to use them and how to invoke
57 them.
58
59
60 Installation
61 ============
62
63 The emacs support is implemented as an Emacs major mode (``rst-mode``)
64 provided by the ``rst.el`` emacs package. In order to use
65 ``rst-mode``, you need to put the ``rst.el`` in a directory located in
66 your emacs ``load-path``, and to load it with::
67
68 (require 'rst)
69
70 To enable ``rst-mode``, simple type ``M-x rst-mode``. Alternatively,
71 you can modify ``auto-mode-alist`` to automatically turn it on
72 whenever you visit reStructuredText_ documents::
73
74 (setq auto-mode-alist
75 (append '(("\\.txt$" . rst-mode)
76 ("\\.rst$" . rst-mode)
77 ("\\.rest$" . rst-mode)) auto-mode-alist))
78
79 If have local variables enabled (see ``enable-local-variables`` in the
80 Emacs manual), you can also add the following at the top of your
81 documents to trigger rst-mode::
82
83 .. -*- mode: rst -*-
84
85 Or this at the end of your documents::
86
87 ..
88 Local Variables:
89 mode: rst
90 End:
91
92 ``rst-mode`` automatically binds several keys for invoking special
93 handy functions for editing ReStructuredText. As is the custom for
94 Emacs major modes, most keys are bound to ``C-c C-LETTER``.
95
96 If you insert an inline table-of-contents at the top of the document,
97 you may want to add a hook to automatically update it everytime you
98 adjust a section title::
99
100 (add-hook 'rst-adjust-hook 'rst-toc-update)
101
102 Additional configuration variables can be customized and can be found
103 by browsing the source code for ``rst.el``.
104
105
106 Section Decorations
107 ===================
108
109 The rst package does not completely parse all the reStructuredText_
110 constructs, but it contains the ability to recognize the section
111 decorations and to build the hierarchy of the document. What we call
112 section decorations or adornments are the underlines or under- and
113 overlines used to mark a section title.
114
115 Adjusting a Section Title
116 -------------------------
117
118 There is a function that helps a great deal to maintain these
119 decorations: ``rst-adjust`` (bound to ``C-c C-a``, or ``C-=`` by
120 default). This function is a Swiss army knife that can be invoked
121 repeatedly and whose behaviour depends on context:
122
123 #. If there is an incomplete underline, e.g.::
124
125 My Section Title
126 ^^
127
128 Invocation will complete the section title. You can simply enter a
129 few characters of the title and invoke the function to complete it.
130 It can also be used to adjust the length of the existing decoration
131 when you need to edit the title.
132
133 #. If there is no section decoration, a decoration one level under the
134 last encountered section level is added;
135
136 #. If there is already a section decoration, it is promoted to the
137 next level. You can invoke it like this repeatedly to cycle the
138 title through the hierarchy of existing decorations.
139
140 Invoking the function with a negative prefix argument, e.g. ``C--
141 C-=``, will effectively reverse the direction of decoration cycling.
142 To alternate between underline-only and over-and-under styles, you can
143 use a regular prefix argument, e.g. ``C-u C-=``. See the
144 documentation of ``rst-adjust`` for more description of the prefix
145 arguments to alter the behaviour of the function.
146
147 Promoting and Demoting Many Sections
148 ------------------------------------
149
150 When you are re-organizing the structure of a document, it can be
151 useful to change the level of a number of section titles. The same
152 key binding can be used to do that: if the region is active when the
153 binding is invoked, all the section titles that are within the region
154 are promoted accordingly (or demoted, with negative prefix arg).
155
156 Redoing All the Decorations to Your Taste
157 -----------------------------------------
158
159 If you open someone else's file and the decorations it contains are
160 unfamiliar, you may want to readjust them to fit your own preferred
161 hierarchy of decorations. This can be difficult to perform by hand.
162 However, you can do this easily by invoking
163 ``rst-straighten-decorations`` (``C-c C-s``), which operates on the
164 entire buffer.
165
166 Customizations for Decorations
167 ------------------------------
168
169 You can set the variable ``rst-preferred-decorations`` to a list of
170 the decorations that you like to use for documents. Everyone has
171 their preference. ``rst-default-indent`` can be set to the number of
172 indent spaces preferred for the over-and-under decoration style.
173
174 Viewing the Hierarchy of Section Decorations
175 --------------------------------------------
176
177 You can visualize the hierarchy of the section decorations in the
178 current buffer by invoking ``rst-display-decorations-hierarchy``,
179 bound on ``C-c C-h``. A temporary buffer will appear with fake
180 section titles rendered in the style of the current document. This
181 can be useful when editing other people's documents to find out which
182 section decorations correspond to which levels.
183
184
185 Section Movement and Selection
186 ==============================
187
188 You can move the cursor between the different section titles by using
189 the ``rst-backward-section`` and ``rst-forward-section`` functions, by
190 default bound to the ``C-c C-p`` and ``C-c C-n`` keys.
191
192 To mark the section that cursor lies in, use ``rst-mark-section``
193 (``C-c C-m``).
194
195
196
197 Operating on Blocks of Text
198 ===========================
199
200 Shifting Text Horizontally Intelligently
201 ----------------------------------------
202
203 Due to the nature of reStructuredText_, lists are indented by two or
204 three characters, e.g. bulleted lists use two chars::
205
206 - Fruits
207
208 - Bananas
209 - Apples
210 - Oranges
211
212 - Veggies
213
214 - Zucchini
215 - Chick Peas
216
217 while enumerated lists are indented by 3 or more characters ::
218
219 9. Apples
220
221 Oranges are tasty.
222
223 10. Oranges
224
225 Oranges are zesty.
226
227 To this effect, when shifting text, it can be useful to have functions
228 which understand which indent to use by using the context around the
229 region. Those functions are ``rst-shift-region-right`` and
230 ``rst-shift-region-left``.
231
232 You can use ``C-c C-r`` and ``C-c C-l`` to shift the active region.
233 These bindings are similar to the ones provided by python-mode for
234 editing python code and behave similarly. They automatically inspect
235 the lines of text before the currently selected region to determine
236 what the appropriate column positions are.
237
238
239 Bulleting and Enumerating Lists
240 -------------------------------
241
242 Sometimes it can be useful to insert bullet list markers enumeration
243 number before a number of lines or paragraphs. You can do this easily
244 by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the
245 following::
246
247 Apples
248
249 Oranges
250
251 Bananas
252
253 becomes::
254
255 1. Apples
256
257 2. Oranges
258
259 3. Bananas
260
261 ``rst-listify-region`` (``C-c C-b``) does the same, but only adds
262 bullet list markers, e.g.::
263
264 Apples
265
266 Oranges
267
268 Bananas
269
270 becomes::
271
272 - Apples
273
274 - Oranges
275
276 - Bananas
277
278
279 By default, each paragraph starting on the leftmost line in the
280 highlighted region will be taken to be a single list or enumeration
281 item, for example, enumerating the following::
282
283 An apple a day
284 keeps the doctor away.
285
286 But oranges
287 are tastier than apples.
288
289 If you preferred bananas
290 you may be
291 a monkey.
292
293 Will result in::
294
295 1. An apple a day
296 keeps the doctor away.
297
298 2. But oranges
299 are tastier than apples.
300
301 3. If you preferred bananas
302 you may be
303 a monkey.
304
305 If you would like to enumerate each of the lines, use a prefix
306 argument on the preceding commands, e.g.::
307
308 Apples
309 Oranges
310 Bananas
311
312 becomes::
313
314 - Apples
315 - Oranges
316 - Bananas
317
318 Straightening Existing Bullet List Hierarchies
319 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
320
321 If you invoke ``rst-straighten-bullets-region`` (C-c C-w), the
322 existing bullets in the highlighted region will be replaced to reflect
323 their respective level. This does not make a difference in the
324 document structure that reStructuredText_ defines, but looks better in
325 the input file, for example, if all of the top-level bullet items use
326 the character ``-``, and all of the 2nd level items use ``*``, etc.
327
328
329 Creating and Removing Line Blocks
330 ---------------------------------
331
332 To create line blocks, first select the region to convert and invoke
333 ``rst-toggle-line-block`` with ``C-c C-d``, for example, the
334 following::
335
336 Apples
337 Oranges
338 Bananas
339
340 becomes::
341
342 | Apples
343 | Oranges
344 | Bananas
345
346 This works even if the region is indented. To remove line blocks,
347 select a region and invoke with a prefix argument.
348
349
350 Commenting a Region of Text
351 ---------------------------
352
353 If you use the Emacs ``comment-region`` function (bound to ``C-c
354 C-c``), the appropriate comment syntax will be added to the active
355 block of text::
356
357 Apples
358 Oranges
359 Bananas
360
361 becomes::
362
363 .. Apples
364 .. Oranges
365 .. Bananas
366
367
368
369 Converting Documents from Emacs
370 ===============================
371
372 The major mode provides a number of functions for running documents
373 being edited through the docutils tools.
374
375 The main generic function is ``rst-compile`` (``C-c 1``). This
376 function basically creates a compilation command with the correct
377 output name for the current buffer and then invokes Emacs' compile
378 function. It also looks for the presence of a ``docutils.conf``
379 configuration file in the parent directories and adds it to the
380 cmdline options. There is also an alternative function in case you
381 often need run your document in a second toolset (``C-c 2``).
382
383 You can customize the commands being used by setting
384 ``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``.
385
386 Other commands are available for other formats:
387
388 - ``rst-compile-pseudo-region`` (``C-c 3``): When crafting documents,
389 it is often convenient to view which data structures docutils will
390 parse them into. You can use to run the active region through
391 ``rst2pseudoxml.py`` and have the output automatically be displayed
392 in a new buffer.
393
394 - ``rst-compile-pdf-preview`` (``C-c 4``): Convert the current
395 document to PDF and launch a viewer on the results.
396
397 - ``rst-compile-slides-preview`` (``C-c 5``): Convert the current
398 document to S5 slides and view in a web browser.
399
400
401 Table-of-Contents Features
402 ==========================
403
404 When you are editing long documents, it can be a bit difficult to
405 orient yourself in the structure of your text. To that effect, a
406 function is provided that quickly parses the document and presents a
407 hierarchically indented table of contents of the document in a
408 temporary buffer, in which you can navigate and press ``Return`` to go
409 to a specific section.
410
411 Invoke this function (``rst-toc``) with ``C-c C-t``. It should
412 present a temporary buffer that looks something like this::
413
414 Table of Contents:
415 Debugging Meta-Techniques
416 Introduction
417 Debugging Solution Patterns
418 Recognize That a Bug Exists
419 Subdivide and Isolate
420 Identify and Verify Assumptions
421 Use a Tool for Introspection
422 Change one thing at a time
423 Learn about the System
424 Understanding a bug
425 The Basic Steps in Debugging
426 Attitude
427 Bad Feelings
428 Good Feelings
429 References
430
431 When you select a section title (press ``RET``), the temporary buffer
432 disappears and you are left with the cursor positioned at the chosen
433 section.
434
435
436 Inserting a Table of Contents
437 -----------------------------
438
439 Oftentimes in long text documents that are meant to be read directly,
440 a Table of Contents is inserted at the beginning of the text. This is
441 the case for most internet FAQs, for example. In reStructuredText_
442 documents, since the table of contents is automatically generated by
443 the parser with the ``.. contents::`` directive, people generally have
444 not been adding a text table of contents to their source documents,
445 and partly because it is too much trouble to edit and maintain.
446
447 The emacs support for reStructuredText_ provides a function to insert
448 such a table of contents in your document. Since it is not meant to
449 be part of the document text, you should place such a table of
450 contents within a comment, so that it is ignored by the parser. This
451 is the favoured usage::
452
453 .. contents::
454 ..
455 1 Introduction
456 2 Debugging Solution Patterns
457 2.1 Recognize That a Bug Exists
458 2.2 Subdivide and Isolate
459 2.3 Identify and Verify Assumptions
460 2.4 Use a Tool for Introspection
461 2.5 Change one thing at a time
462 2.6 Learn about the System
463 3 Understanding a bug
464 4 The Basic Steps in Debugging
465 5 Attitude
466 5.1 Bad Feelings
467 5.2 Good Feelings
468 6 References
469
470 Just place the cursor at the top-left corner where you want to insert
471 the TOC and invoke the function with ``C-c C-i``. The table of
472 contents will display all the section titles that are under the
473 location where the insertion occurs. This way you can insert local
474 table of contents by placing them in the appropriate location.
475
476 If you have deep nesting of sections, you can use a numeric prefix
477 argument to limit the depth of rendering of the TOC.
478
479 You can also customize the look of the TOC by setting the values of
480 the following variables:: ``rst-toc-indent``,
481 ``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
482
483 .. note::
484
485 The table-of-contents inserted by ``rst-mode`` has text properties
486 added to it so that if you type ``C-c C-f`` while the cursor is on
487 one of its entries, the cursor will jump to the corresponding
488 section in the document.
489
490
491 Maintaining the Table of Contents Up-to-date
492 --------------------------------------------
493
494 One issue is that you will probably want to maintain the inserted
495 table of contents up-to-date. There is a function that will
496 automatically look for the inserted TOC (``rst-toc-update``)
497 and it can be added to a hook on the section decoration adjustment
498 function, so that every time you adjust a section title, the TOC is
499 updated. Add this functionality with the following emacs
500 configuration::
501
502 (add-hook 'rst-adjust-hook 'rst-toc-update)
503
504 You can invoke the update on the current buffer with ``C-c C-u``.
505
506
507 Syntax Highlighting via Font-Lock
508 =================================
509
510 ``rst-mode`` also provides syntax highlighting to reStructuredText_
511 constructs. (This mode was written by Stefan Merten.)
512
513 Lazy syntax coloring is implemented for many of the constructs that
514 reStructuredText_ prescribes. By default, the font-lock colouring is
515 performed lazily. If you don't like this, you can turn this off by
516 setting the value of ``rst-mode-lazy``. You can also change the
517 various colours (see the source file for the whole list of
518 customizable faces).
519
520 ``font-lock`` syntax highlighting is enabled by default. If you prefer
521 to turn off syntax highlighting (on some machines it can slow down
522 editing a little bit), you can use the following in your Emacs
523 configuration::
524
525 (setq font-lock-global-modes '(not rst-mode))
526
527
528 Face Customization
529 ------------------
530
531 The ``rst-faces`` group contains all necessary for customizing
532 fonts. The default settings use standard ``font-lock-*-face`` so if
533 you set these to your liking they are probably good in rst-mode also.
534
535 The group is contained in the faces group as well as in the rst group.
536
537
538 Default Fonts
539 ~~~~~~~~~~~~~
540
541 The ``rst-faces-defaults`` group contains all necessary for
542 customizing the default fonts used for section title faces.
543
544 The general idea for section title faces is to have a non-default
545 background but do not change the background. The section level is
546 shown by the lightness of the background color. If you like this
547 general idea of generating faces for section titles but do not like
548 the details this group is the point where you can customize the
549 details. If you do not like the general idea, however, you should
550 customize the faces used in ``rst-adornment-faces-alist``.
551
552 Note: If you are using a dark background please make sure the variable
553 ``frame-background-mode`` is set to the symbol dark. This triggers
554 some default values which are probably right for you.
555
556 The group is contained in the ``rst-faces`` group.
557
558 All customizable features have a comment explaining their
559 meaning. Refer to the customization of your Emacs (try ``M-x
560 customize``).
561
562
563
564 Other Useful Settings
565 =====================
566
567 This section covers general emacs text-mode settings that are useful
568 in the context of reStructuredText_ conventions. These are not
569 provided by ``rst.el`` but you may find them useful specifically for
570 reStructuredText_ documents.
571
572 ``text-mode`` Settings
573 ----------------------
574
575 Consult the Emacs manual for more text-mode customizations. In
576 particular, you may be interested in setting the following variables,
577 functions and modes that pertain somewhat to text-mode:
578
579 - indent-tabs-mode
580 - colon-double-space
581 - auto-fill-mode
582 - auto-mode-alist
583 - fill-region
584
585 Editing Tables: Emacs table mode
586 --------------------------------
587
588 You may want to check out `Emacs table mode`_ to create an edit
589 tables, it allows creating ascii tables compatible with
590 reStructuredText_.
591
592 .. _Emacs table mode: http://table.sourceforge.net/
593
594
595 Character Processing
596 --------------------
597
598 Since reStructuredText punts on the issue of character processing,
599 here are some useful resources for Emacs users in the Unicode world:
600
601 * `xmlunicode.el and unichars.el from Norman Walsh
602 <http://nwalsh.com/emacs/xmlchars/index.html>`__
603
604 * `An essay by Tim Bray, with example code
605 <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
606
607 * For Emacs users on Mac OS X, here are some useful useful additions
608 to your .emacs file.
609
610 - To get direct keyboard input of non-ASCII characters (like
611 "option-e e" resulting in "é" [eacute]), first enable the option
612 key by setting the command key as your meta key::
613
614 (setq mac-command-key-is-meta t) ;; nil for option key
615
616 Next, use one of these lines::
617
618 (set-keyboard-coding-system 'mac-roman)
619 (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
620
621 I prefer the first line, because it enables non-Latin-1 characters
622 as well (em-dash, curly quotes, etc.).
623
624 - To enable the display of all characters in the Mac-Roman charset,
625 first create a fontset listing the fonts to use for each range of
626 characters using charsets that Emacs understands::
627
628 (create-fontset-from-fontset-spec
629 "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
630 ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
631 latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
632 mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
633
634 Latin-1 doesn't cover characters like em-dash and curly quotes, so
635 "mule-unicode-0100-24ff" is needed.
636
637 Next, use that fontset::
638
639 (set-frame-font "fontset-monaco")
640
641 - To enable cooperation between the system clipboard and the Emacs
642 kill ring, add this line::
643
644 (set-clipboard-coding-system 'mac-roman)
645
646 Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
647 FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
648
649 No matter what platform (or editor) you're using, I recommend the
650 ProFont__ programmer's font. It's monospaced, small but readable,
651 similar characters are visually distinctive (like "I1l|", "0O", "ao",
652 and ".,:;"), and free.
653
654 __ http://www.tobias-jung.de/seekingprofont/
655
656
657
658 Credits
659 =======
660
661 - The automatic section adjustment and table of contents features were
662 written by Martin Blais;
663 - Syntax highlighting was implemented by Stefan Merten;
664 - Various other functions were implemented by David Goodger.
665
666 Obsolete Files
667 --------------
668
669 On 2005-10-30, ``rst.el`` integrated and replaced the contents of the
670 following files:
671
672 - ``restructuredtext.el``
673 - ``rst-html.el``
674 - ``rst-mode.el``
675
676
677
678 .. _Emacs: http://www.gnu.org/software/emacs/emacs.html
679 .. _reStructuredText: http://docutils.sf.net/rst.html
680
681
682 ..
683 Local Variables:
684 mode: rst
685 indent-tabs-mode: nil
686 sentence-end-double-space: t
687 fill-column: 70
688 End: