From 9fc8faf24c698bdc8511e1c415ee6158d9169ead Mon Sep 17 00:00:00 2001 From: smerten Date: Sat, 3 Aug 2013 11:16:24 +0000 Subject: [PATCH] Revised tutorial to match ``rst.el`` V1.4.0. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7712 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/user/emacs.txt | 1605 +++++++++++++++++++++++------------------- 1 file changed, 895 insertions(+), 710 deletions(-) rewrite docutils/docs/user/emacs.txt (68%) diff --git a/docutils/docs/user/emacs.txt b/docutils/docs/user/emacs.txt dissimilarity index 68% index 6a7503f82..072b8cdfe 100644 --- a/docutils/docs/user/emacs.txt +++ b/docutils/docs/user/emacs.txt @@ -1,710 +1,895 @@ -.. -*- coding: utf-8 -*- - -======================================== - Emacs Support for reStructuredText -======================================== - -:Author: Martin Blais -:Date: $Date$ -:Abstract: - - High-level description of the existing emacs support for editing - reStructuredText text documents. Suggested setup code and usage - instructions are provided. - -.. contents:: -.. - 1 Introduction - 2 Installation - 3 Section Decorations - 3.1 Adjusting a Section Title - 3.2 Promoting and Demoting Many Sections - 3.3 Redoing All the Decorations to Your Taste - 3.4 Customizations for Decorations - 3.5 Viewing the Hierarchy of Section Decorations - 4 Section Movement and Selection - 5 Operating on Blocks of Text - 5.1 Shifting Text Horizontally Intelligently - 5.2 Bulleting and Enumerating Lists - 5.2.1 Straightening Existing Bullet List Hierarchies - 5.3 Creating and Removing Line Blocks - 5.4 Commenting a Region of Text - 6 Converting Documents from Emacs - 7 Table-of-Contents Features - 7.1 Inserting a Table of Contents - 7.2 Maintaining the Table of Contents Up-to-date - 8 Syntax Highlighting via Font-Lock - 8.1 Face Customization - 8.1.1 Default Fonts - 9 Other Useful Settings - 9.1 ``text-mode`` Settings - 9.2 Editing Tables: Emacs table mode - 9.3 Character Processing - 10 Credits - 10.1 Obsolete Files - 11 Future Work - - -Introduction -============ - -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. - - -Installation -============ - -Emacs support for reStructuredText is implemented as an Emacs major -mode (``rst-mode``) provided by the ``rst.el`` emacs package. - -For recent versions of Emacs, there's no need to install anything to -get reST support; ``rst-mode`` is already available. So:: - - M-x rst-mode - -will work out of the box. If this works for you, please skip to the -Usage_ section. - -For older versions of Emacs, ``rst.el`` can be found in the -``tools/editors/emacs/`` directory of the Docutils snapshot or -repository. `A copy can also be downloaded here. -`__ - -In order to use ``rst-mode``, you need to put the ``rst.el`` in a -directory located in your emacs ``load-path`` (use ``C-h v load-path`` -to check). - - -Usage -===== - -Load rst-mode with:: - - (require 'rst) - -To enable ``rst-mode``, simply 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) - -Additional configuration variables can be customized and can be found -by browsing the source code for ``rst.el``. - - -Section Decorations -=================== - -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. - - -Adjusting 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. - -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 arg). - -Redoing All the Decorations to Your Taste ------------------------------------------ - -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. - -Customizations for Decorations ------------------------------- - -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. - -Viewing the Hierarchy of Section Decorations --------------------------------------------- - -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. - - -Section Movement and Selection -============================== - -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``). - - - -Operating on Blocks of Text -=========================== - -Shifting Text Horizontally Intelligently ----------------------------------------- - -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 text, it can be useful to have functions -which understand which indent to use by using the context around the -region. Those functions are ``rst-shift-region-right`` and -``rst-shift-region-left``. - -You can use ``C-c C-r`` and ``C-c C-l`` to shift the active region. -These bindings are similar to the ones provided by python-mode for -editing python code and behave similarly. They automatically inspect -the lines of text before the currently selected region to determine -what the appropriate column positions are. - - -Bulleting and Enumerating Lists -------------------------------- - -Sometimes it can be useful to insert bullet list markers enumeration -number before a number of lines or paragraphs. You can do this easily -by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the -following:: - - Apples - - Oranges - - Bananas - -becomes:: - - 1. Apples - - 2. Oranges - - 3. Bananas - -``rst-listify-region`` (``C-c C-b``) does the same, but only adds -bullet list markers, e.g.:: - - Apples - - Oranges - - Bananas - -becomes:: - - - 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-w), the -existing bullets in the highlighted 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 -the input file, for example, if all of the top-level bullet items use -the character ``-``, and all of the 2nd level items use ``*``, etc. - - -Creating and Removing Line Blocks ---------------------------------- - -To create line blocks, first select the region to convert and invoke -``rst-toggle-line-block`` with ``C-c C-d``, 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 ---------------------------- - -If you use the Emacs ``comment-region`` function (bound to ``C-c -C-c``), the appropriate comment syntax will be added to the active -block of text:: - - Apples - Oranges - Bananas - -becomes:: - - .. Apples - .. Oranges - .. Bananas - - - -Converting Documents from Emacs -=============================== - -The major mode provides a number of functions for running documents -being edited through the docutils tools. - -The main generic function is ``rst-compile`` (``C-c 1``). This -function basically creates 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 -cmdline options. There is also an alternative function in case you -often need run your document in a second toolset (``C-c 2``). - -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 3``): 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 4``): Convert the current - document to PDF and launch a viewer on the results. - -- ``rst-compile-slides-preview`` (``C-c 5``): Convert the current - document to S5 slides and view in a web browser. - - -Table-of-Contents Features -========================== - -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 quickly parses the document and 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 this function (``rst-toc``) with ``C-c C-t``. It should -present 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 select a section title (press ``RET``), the temporary buffer -disappears and you are left with the cursor positioned at the chosen -section. - - -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. This is -the case for most internet FAQs, for example. In reStructuredText_ -documents, since the table of contents is automatically generated by -the parser with the ``.. contents::`` directive, people generally have -not been adding a text 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 favoured 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 with ``C-c 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. - -If you have deep nesting of sections, you can use a numeric prefix -argument to limit the depth of rendering of the TOC. - -You can also 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``. - -.. note:: - - The table-of-contents inserted by ``rst-mode`` has text properties - added to it so that if you type ``C-c C-f`` while the cursor is on - one of its entries, the cursor will jump to the corresponding - section in the document. - - -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. There is a function that will -automatically look for the inserted TOC (``rst-toc-update``) -and it can be added to a hook on the section decoration adjustment -function, so that every time you adjust a section title, the TOC is -updated. Add this functionality with the following emacs -configuration:: - - (add-hook 'rst-adjust-hook 'rst-toc-update) - -You can invoke the update on the current buffer with ``C-c C-u``. - - -Syntax Highlighting via Font-Lock -================================= - -``rst-mode`` also provides syntax highlighting to reStructuredText_ -constructs. (This mode was written by Stefan Merten.) - -Lazy syntax coloring is implemented for many of the constructs that -reStructuredText_ prescribes. By default, the font-lock colouring is -performed lazily. If you don't like this, you can turn this off by -setting the value of ``rst-mode-lazy``. You can also change the -various colours (see the source file for the whole list of -customizable faces). - -``font-lock`` syntax highlighting is enabled by default. If you prefer -to turn off syntax highlighting (on some machines it can slow down -editing a little bit), you can use the following in your Emacs -configuration:: - - (setq font-lock-global-modes '(not rst-mode)) - - -Face Customization ------------------- - -The ``rst-faces`` group contains all necessary for customizing -fonts. The default settings use standard ``font-lock-*-face`` so if -you set these to your liking they are probably good in rst-mode also. - -The group is contained in the faces group as well as in the rst group. - - -Default Fonts -~~~~~~~~~~~~~ - -The ``rst-faces-defaults`` group contains all necessary for -customizing the default fonts used for section title faces. - -The general idea for section title faces is to have a non-default -background but do not change the background. The section level is -shown by the lightness of the background color. If you like this -general idea of generating faces for section titles but do not like -the details this group is the point where you can customize the -details. If you do not like the general idea, however, you should -customize the faces used in ``rst-adornment-faces-alist``. - -Note: If you are using a dark background please make sure the variable -``frame-background-mode`` is set to the symbol dark. This triggers -some default values which are probably right for you. - -The group is contained in the ``rst-faces`` group. - -All customizable features have a comment explaining their -meaning. Refer to the customization of your Emacs (try ``M-x -customize``). - - - -Other Useful Settings -===================== - -This section covers general emacs text-mode settings that are useful -in the context of reStructuredText_ conventions. These are not -provided by ``rst.el`` but you may find them useful specifically for -reStructuredText_ documents. - -``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 -- auto-fill-mode -- auto-mode-alist -- fill-region - -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 - `__ - -* `An essay by Tim Bray, with example code - `__ - -* 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 `__. - -No matter what platform (or editor) you're using, I recommend the -ProFont__ programmer's font. It's monospaced, small but readable, -similar characters are visually distinctive (like "I1l|", "0O", "ao", -and ".,:;"), and free. - -__ http://www.tobias-jung.de/seekingprofont/ - - - -Credits -======= - -- The automatic section adjustment and table of contents features were - written by Martin Blais; -- Syntax highlighting was implemented by Stefan Merten; -- Various other functions were implemented by David Goodger. - -Obsolete Files --------------- - -On 2005-10-30, ``rst.el`` integrated and replaced the contents of the -following files: - -- ``restructuredtext.el`` -- ``rst-html.el`` -- ``rst-mode.el`` - - - -.. _Emacs: http://www.gnu.org/software/emacs/emacs.html -.. _reStructuredText: http://docutils.sf.net/rst.html - - -.. - Local Variables: - mode: rst - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: +.. -*- coding: utf-8 -*- + +======================================== + Emacs Support for reStructuredText +======================================== + +:Authors: Stefan Merten , Martin Blais + +:Version: ``rst.el`` V1.4.0 +: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. This version of ``rst.el`` has the internal version +V1.4.0. + +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 included version of ``rst.el`` 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://docutils.sourceforge.net/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 + sInit File Examples + +#. 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-``. 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 ``??``. The old bindings may 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, 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. + +#. 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. +``rst-default-indent`` can be set to the number of indent spaces +preferred for the over-and-under adornment style. + +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 rst-indent`` 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 + + @ + +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``. + +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. + +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``, the temporary buffer disappears and you are left with the +cursor positioned at the chosen section. 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 locate an inserted table of contents following a +``.. contents::`` directive. + +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-grouprst + +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. + +The title text of over-and-under adornments may be indented. +``rst-default-indent`` tells ``rst-mode`` how many positions a +over-and-under adornment should be indented. + +Finally if you create a completely new section adornment by +``rst-adjust`` the question is on what level the new section adornment +should be. ``rst-new-adornment-down`` can be used to create one level +lower adornments than the previous section title. By default the new +section title is on the same level as the previous one. + +Please note, that normally the given adornments of a buffer are +preferred over your preferences, however. See `Redoing All the +Adornments to Your Taste`_ for a method to change this for the whole +buffer. + +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. + +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 + `__ + +* `An essay by Tim Bray, with example code + `__ + +* 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 `__. + +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 + +.. + Local Variables: + mode: rst + indent-tabs-mode: nil + fill-column: 70 + End: +.. 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 -- 2.11.4.GIT