| Author: | Martin Blais <blais@furius.ca> |
|---|---|
| Date: | 2007-12-03 |
Abstract
High-level description of the existing emacs support for editing reStructuredText text documents. Suggested setup code and usage instructions are provided.
Contents
reStructuredText is a series of conventions that allows a toolset--docutils--to extract generic document structure from simple text files. For people who use Emacs, there is a package that adds a major mode that supports editing in the conventions 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.
The emacs support is implemented as an Emacs major mode (rst-mode) provided by the rst.el emacs package. In order to use rst-mode, you need to put the rst.el in a directory located in your emacs load-path, and to load it with:
(require 'rst)
To enable rst-mode, simple type M-x rst-mode. Alternatively, you can 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))
If have local variables enabled (see enable-local-variables in the Emacs manual), 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:
rst-mode automatically binds several keys for invoking special handy functions for editing ReStructuredText. As is the custom for Emacs major modes, most keys are bound to C-c C-LETTER.
If you insert an inline table-of-contents at the top of the document, you may want to add a hook to automatically update it everytime you adjust a section title:
(add-hook 'rst-adjust-hook 'rst-toc-update)
The Debian python-docutils package automatically sets up a suitable configuration.
Additional configuration variables can be customized and can be found by browsing the source code for rst.el.
The rst package does not completely parse all the reStructuredText constructs, but it contains the ability to recognize the section decorations and to build the hierarchy of the document. What we call section decorations or adornments are the underlines or under- and overlines used to mark a section title.
There is a function that helps a great deal to maintain these decorations: rst-adjust (bound to C-c C-a, or C-= by default). This function is a Swiss army knife that can be invoked repeatedly and whose behaviour depends on context:
If there is an incomplete underline, e.g.:
My Section Title ^^
Invocation will complete the section title. You can simply enter a few characters of the title and invoke the function to complete it. It can also be used to adjust the length of the existing decoration when you need to edit the title.
If there is no section decoration, a decoration one level under the last encountered section level is added;
If there is already a section decoration, it is promoted to the next level. You can invoke it like this repeatedly to cycle the title through the hierarchy of existing decorations.
Invoking the function with a negative prefix argument, e.g. C-- C-=, will effectively reverse the direction of decoration 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 behaviour of the function.
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 arg).
If you open someone else's file and the decorations it contains are unfamiliar, you may want to readjust them to fit your own preferred hierarchy of decorations. This can be difficult to perform by hand. However, you can do this easily by invoking rst-straighten-decorations (C-c C-s), which operates on the entire buffer.
You can set the variable rst-preferred-decorations to a list of the decorations that you like to use for documents. Everyone has their preference. rst-default-indent can be set to the number of indent spaces preferred for the over-and-under decoration style.
You can visualize the hierarchy of the section decorations in the current buffer by invoking rst-display-decorations-hierarchy, bound on C-c C-h. 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 decorations correspond to which levels.
You can move the cursor between the different section titles by using the rst-backward-section and rst-forward-section functions, by default bound to the C-c C-p and C-c C-n keys.
To mark the section that cursor lies in, use rst-mark-section (C-c C-m).
Due to the nature of reStructuredText, lists are indented by two or three characters, e.g. bulleted lists use two chars:
- Fruits - Bananas - Apples - Oranges - Veggies - Zucchini - Chick Peas
while enumerated lists are indented by 3 or more characters
9. Apples
Oranges are tasty.
10. Oranges
Oranges are zesty.
To this effect, when shifting ./usr/share/doc/python-docutils/docs/user/emacs.html 0000644 0000000 0000000 00000107475 11357423530 021443 0 ustar root root
| Author: | Martin Blais <blais@furius.ca> |
|---|---|
| Date: | 2007-12-03 |
Abstract
High-level description of the existing emacs support for editing reStructuredText text documents. Suggested setup code and usage instructions are provided.
Contents
reStructuredText is a series of conventions that allows a toolset--docutils--to extract generic document structure from simple text files. For people who use Emacs, there is a package that adds a major mode that supports editing in the conventions 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.
The emacs support is implemented as an Emacs major mode (rst-mode) provided by the rst.el emacs package. In order to use rst-mode, you need to put the rst.el in a directory located in your emacs load-path, and to load it with:
(require 'rst)
To enable rst-mode, simple type M-x rst-mode. Alternatively, you can 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))
If have local variables enabled (see enable-local-variables in the Emacs manual), 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:
rst-mode automatically binds several keys for invoking special handy functions for editing ReStructuredText. As is the custom for Emacs major modes, most keys are bound to C-c C-LETTER.
If you insert an inline table-of-contents at the top of the document, you may want to add a hook to automatically update it everytime you adjust a section title:
(add-hook 'rst-adjust-hook 'rst-toc-update)
The Debian python-docutils package automatically sets up a suitable configuration.
Additional configuration variables can be customized and can be found by browsing the source code for rst.el.
The rst package does not completely parse all the reStructuredText constructs, but it contains the ability to recognize the section decorations and to build the hierarchy of the document. What we call section decorations or adornments are the underlines or under- and overlines used to mark a section title.
There is a function that helps a great deal to maintain these decorations: rst-adjust (bound to C-c C-a, or C-= by default). This function is a Swiss army knife that can be invoked repeatedly and whose behaviour depends on context:
If there is an incomplete underline, e.g.:
My Section Title ^^
Invocation will complete the section title. You can simply enter a few characters of the title and invoke the function to complete it. It can also be used to adjust the length of the existing decoration when you need to edit the title.
If there is no section decoration, a decoration one level under the last encountered section level is added;
If there is already a section decoration, it is promoted to the next level. You can invoke it like this repeatedly to cycle the title through the hierarchy of existing decorations.
Invoking the function with a negative prefix argument, e.g. C-- C-=, will effectively reverse the direction of decoration 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 behaviour of the function.
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 arg).
If you open someone else's file and the decorations it contains are unfamiliar, you may want to readjust them to fit your own preferred hierarchy of decorations. This can be difficult to perform by hand. However, you can do this easily by invoking rst-straighten-decorations (C-c C-s), which operates on the entire buffer.
You can set the variable rst-preferred-decorations to a list of the decorations that you like to use for documents. Everyone has their preference. rst-default-indent can be set to the number of indent spaces preferred for the over-and-under decoration style.
You can visualize the hierarchy of the section decorations in the current buffer by invoking rst-display-decorations-hierarchy, bound on C-c C-h. 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 decorations correspond to which levels.
You can move the cursor between the different section titles by using the rst-backward-section and rst-forward-section functions, by default bound to the C-c C-p and C-c C-n keys.
To mark the section that cursor lies in, use rst-mark-section (C-c C-m).
Due to the nature of reStructuredText, lists are indented by two or three characters, e.g. bulleted lists use two chars:
- Fruits - Bananas - Apples - Oranges - Veggies - Zucchini - Chick Peas
while enumerated lists are indented by 3 or more characters
9. Apples
Oranges are tasty.
10. Oranges
Oranges are zesty.
To this effect, when shifting ./usr/share/doc/python-docutils/docs/user/emacs.html 0000644 0000000 0000000 00000107475 11357423530 021443 0 ustar root root
| Author: | Martin Blais <blais@furius.ca> |
|---|---|
| Date: | 2007-12-03 |
Abstract
High-level description of the existing emacs support for editing reStructuredText text documents. Suggested setup code and usage instructions are provided.