NAME

rst-mode.el --- Mode for viewing and editing reStructuredText-documents.


SYNOPSIS

Add the following lines to your .emacs file:

  (autoload 'rst-mode "rst-mode" "mode for editing reStructuredText documents" t)
  (setq auto-mode-alist
        (append '(("\\.rst$" . rst-mode)
                  ("\\.rest$" . rst-mode)) auto-mode-alist))

If you are using .txt as a standard extension for reST files as http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file suggests you may use one of the Local Variables in Files mechanism Emacs provides to set the major mode automatically. For instance you may use

  .. -*- mode: rst -*-

in the very first line of your file. However, because this is a major security breach you or your administrator may have chosen to switch that feature off. See Local Variables in Files in the Emacs documentation for a more complete discussion.


DESCRIPTION

This package provides support for documents marked up using the reStructuredText format. Support includes font locking as well as some convenience functions for editing. It does this by defining a Emacs major mode.

The package is based on text-mode and inherits some things from it. Particularly text-mode-hook is run before rst-mode-hook.


OPTIONS

There are a number of things which can be customized using the standard Emacs customization features. There are two customization groups for this mode.

rst

This group contains some general customizable features.

The group is contained in the wp group.

rst-faces

This group contains all necessary for customizing fonts. The default settings use standard font-lock-*-faces 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.

rst-faces-defaults

This 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).


SEE ALSO

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html


AUTHOR

Stefan Merten <smerten AT oekonux.de>


LICENSE

This program is licensed under the terms of the GPL. See

  http://www.gnu.org/licenses/gpl.txt


AVAILABILITY

See

  http://www.merten-home.de/FreeSoftware/rst-mode/