| blob | 6e0562f4a4bf5fb0fe948d2e51dbf75ab45009ba |
1 ;;; rst.el --- Mode for viewing and editing reStructuredText-documents.
3 ;; Copyright (C) 2003-2012 Free Software Foundation, Inc.
5 ;; Maintainer: Stefan Merten <smerten@oekonux.de>
6 ;; Author: Stefan Merten <smerten@oekonux.de>,
7 ;; Martin Blais <blais@furius.ca>,
8 ;; David Goodger <goodger@python.org>,
9 ;; Wei-Wei Guo <wwguocn@gmail.com>
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 ;;; Commentary:
28 ;; This package provides major mode rst-mode, which supports documents marked
29 ;; up using the reStructuredText format. Support includes font locking as well
30 ;; as a lot of convenience functions for editing. It does this by defining a
31 ;; Emacs major mode: rst-mode (ReST). This mode is derived from text-mode.
32 ;; This package also contains:
33 ;;
34 ;; - Functions to automatically adjust and cycle the section underline
35 ;; adornments;
36 ;; - A mode that displays the table of contents and allows you to jump anywhere
37 ;; from it;
38 ;; - Functions to insert and automatically update a TOC in your source
39 ;; document;
40 ;; - Function to insert list, processing item bullets and enumerations
41 ;; automatically;
42 ;; - Font-lock highlighting of most reStructuredText structures;
43 ;; - Indentation and filling according to reStructuredText syntax;
44 ;; - Cursor movement according to reStructuredText syntax;
45 ;; - Some other convenience functions.
46 ;;
47 ;; See the accompanying document in the docutils documentation about
48 ;; the contents of this package and how to use it.
49 ;;
50 ;; For more information about reStructuredText, see
51 ;; http://docutils.sourceforge.net/rst.html
52 ;;
53 ;; For full details on how to use the contents of this file, see
54 ;; http://docutils.sourceforge.net/docs/user/emacs.html
55 ;;
56 ;;
57 ;; There are a number of convenient key bindings provided by rst-mode.
58 ;; For more on bindings, see rst-mode-map below. There are also many variables
59 ;; that can be customized, look for defcustom in this file.
60 ;;
61 ;; If you use the table-of-contents feature, you may want to add a hook to
62 ;; update the TOC automatically every time you adjust a section title::
63 ;;
64 ;; (add-hook 'rst-adjust-hook 'rst-toc-update)
65 ;;
66 ;; Syntax highlighting: font-lock is enabled by default. If you want to turn
67 ;; off syntax highlighting to rst-mode, you can use the following::
68 ;;
69 ;; (setq font-lock-global-modes '(not rst-mode ...))
70 ;;
71 ;;
72 ;;
73 ;; Customization is done by customizable variables contained in customization
74 ;; group "rst" and subgroups. Group "rst" is contained in the "wp" group.
75 ;;
77 ;;; DOWNLOAD
79 ;; The latest release of this file lies in the docutils source code repository:
80 ;; http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils/tools/editors/emacs/rst.el
82 ;;; INSTALLATION
84 ;; Add the following lines to your `.emacs' file:
85 ;;
86 ;; (require 'rst)
87 ;;
88 ;; If you are using `.txt' as a standard extension for reST files as
89 ;; http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file
90 ;; suggests you may use one of the `Local Variables in Files' mechanism Emacs
91 ;; provides to set the major mode automatically. For instance you may use::
92 ;;
93 ;; .. -*- mode: rst -*-
94 ;;
95 ;; in the very first line of your file. The following code is useful if you
96 ;; want automatically enter rst-mode from any file with compatible extensions:
97 ;;
98 ;; (setq auto-mode-alist
99 ;; (append '(("\\.txt\\'" . rst-mode)
100 ;; ("\\.rst\\'" . rst-mode)
101 ;; ("\\.rest\\'" . rst-mode)) auto-mode-alist))
102 ;;
104 ;;; Code:
106 ;; FIXME: When 24.1 is common place remove use of `lexical-let' and put "-*-
107 ;; lexical-binding: t -*-" in the first line.
109 ;; Only use of macros is allowed - may be replaced by `cl-lib' some time.
113 ;; Redefine some functions from `cl.el' in a proper namespace until they may be
114 ;; used from there.
117 "Return 1 if X is positive, -1 if negative, 0 if zero."
124 "Return non-nil if any element of SEQ yields non-nil when PRED is applied.
125 Apply PRED to each element of list SEQ until the first non-nil
126 result is yielded and return this result. PRED defaults to
127 `identity'."
137 "Return position of first element satisfying PRED in list SEQ or nil."
146 "Return position of ELEM in list SEQ or nil.
147 Comparison done with `equal'."
148 ;; Create a closure containing `elem' so the `lambda' always sees our
149 ;; parameter instead of an `elem' which may be in dynamic scope at the time
150 ;; of execution of the `lambda'.
154 seq)))
156 ;; FIXME: Embed complicated `defconst's in `eval-when-compile'.
158 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
159 ;; Versions
162 "Extract the version from a variable according to the given regexes.
163 Return the version after regex DELIM-RE and HEAD-RE matching RE
164 and before TAIL-RE and DELIM-RE in VAR or DEFAULT for no match."
167 var)
169 default))
171 ;; Use CVSHeader to really get information from CVS and not other version
172 ;; control systems.
185 ;; Use LastChanged... to really get information from SVN.
189 "The SVN revision of this file.
196 ;; Maintained by the release process.
208 rst-official-version
210 rst-cvs-rev rst-cvs-timestamp))
211 "The version string.
212 Starts with the current official version. For developer versions
224 rst-version))
229 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
230 ;; Initialize customization
232 \f
238 \f
239 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
240 ;; Facilities for regular expressions used everywhere
242 ;; The trailing numbers in the names give the number of referenceable regex
243 ;; groups contained in the regex.
245 ;; Used to be customizable but really is not customizable but fixed by the reST
246 ;; syntax.
248 ;; Sorted so they can form a character class when concatenated.
259 ;; Sorted so they can form a character class when concatenated.
263 ?-)
267 1000
271 ;; `*-beg' matches * at the beginning of a line.
272 ;; `*-end' matches * at the end of a line.
273 ;; `*-prt' matches a part of *.
274 ;; `*-tag' matches *.
275 ;; `*-sta' matches the start of * which may be followed by respective content.
276 ;; `*-pfx' matches the delimiter left of *.
277 ;; `*-sfx' matches the delimiter right of *.
278 ;; `*-hlp' helper for *.
279 ;;
280 ;; A trailing number says how many referenceable groups are contained.
281 `(
283 ;; Horizontal white space (`hws')
288 ;; Lines (`lin')
293 ;; Various tags and parts
304 ;; Block lead in (`bli')
306 ; immediate content.
308 ;; Various starts
311 ;; Explicit markup tag (`exm')
316 ;; Counters in enumerations (`cnt')
320 ;; Enumerator (`enm')
327 ; enumerator.
334 ; at the beginning of a line.
336 ;; Items may be enumerated or bulleted (`itm')
339 ; is the item tag.
341 ; beginning of a line, group is the
342 ; item tag.
344 ;; Inline markup (`ilm')
348 ;; Inline markup content (`ilc')
353 ; definition.
356 ; definition.
362 (:seq ilcsgl-tag
363 ilcast-prt ilcrep-hlp
366 (:seq ilcsgl-tag
367 ilcbkq-prt ilcrep-hlp
370 (:seq ilcsgl-tag
371 ilcbkqdef-prt ilcrep-hlp
374 (:seq ilcsgl-tag
375 ilcbar-prt ilcrep-hlp
378 (:seq ilcsgl-tag
379 ilcbardef-prt ilcrep-hlp
382 ;; Fields (`fld')
387 ;; Options (`opt')
394 ;; Footnotes and citations (`fnc')
400 ; tag. First group is the explicit markup
401 ; start, second group is the footnote /
402 ; citation tag.
404 ; definition. First group is the explicit
405 ; markup start, second group is the
406 ; footnote / citation tag.
408 ;; Substitutions (`sub')
411 ; tag.
413 ;; Symbol (`sym')
417 ;; URIs (`uri')
420 ;; Adornment (`ado')
423 ; otherwise explicit markup start would be
424 ; recognized.
426 ; characters is matched differently.
429 ; adornment character and MUST be the FIRST
430 ; group in the whole expression.
433 ; adornment character and MUST be the
434 ; SECOND group in the whole expression.
437 ; adornment and MUST be the FIRST group in the whole
438 ; expression; second group is the first adornment
439 ; character.
441 ;; Titles (`ttl')
445 ;; Directives and substitution definitions (`dir')
449 ; tag. First group is explicit markup
450 ; start, second group is a possibly
451 ; empty substitution tag, third group is
452 ; the directive tag including the double
453 ; colon.
455 ; definition. Groups are as in dir-tag-3.
457 ;; Literal block (`lit')
460 ; any text before the double colon tag which
461 ; may not exist, second group is the double
462 ; colon tag.
464 ;; Comments (`cmt')
468 ; start.
470 ;; Paragraphs (`par')
473 ; certain cases.
474 )
475 "Definition alist of relevant regexes.
476 Each entry consists of the symbol naming the regex and an
481 ;; FIXME: Use `sregex` or `rx` instead of re-inventing the wheel.
483 "Interpret ARGS as regular expressions and return a regex string.
484 Each element of ARGS may be one of the following:
486 A string which is inserted unchanged.
488 A character which is resolved to a quoted regex.
490 A symbol which is resolved to a string using `rst-re-alist-def'.
492 A list with a keyword in the car. Each element of the cdr of such
493 a list is recursively interpreted as ARGS. The results of this
494 interpretation are concatenated according to the keyword.
496 For the keyword `:seq' the results are simply concatenated.
498 For the keyword `:shy' the results are concatenated and
504 For the keyword `:grp' the results are concatenated and form a
507 After interpretation of ARGS the results are concatenated as for
508 `:seq'."
514 re)
537 args)))
539 ;; FIXME: Remove circular dependency between `rst-re' and `rst-re-alist'.
542 ;; Shadow global value we are just defining so we can construct it step by
543 ;; step.
551 \f
552 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
553 ;; Mode definition
556 "Bind like `define-key' but add deprecated key definitions.
557 KEYMAP, KEY, and DEF are as in `define-key'. DEPRECATED key
558 definitions should be in vector notation. These are defined as
559 well but give an additional message."
571 ;; Key bindings.
575 ;; \C-c is the general keymap.
578 ;;
579 ;; Section Adornments
580 ;;
581 ;; The adjustment function that adorns or rotates a section title.
585 ;; \C-c \C-a is the keymap for adornments.
587 ;; Display the hierarchy of adornments implied by the current document
588 ;; contents.
590 ;; Homogenize the adornments in the document.
594 ;;
595 ;; Section Movement and Selection
596 ;;
597 ;; Mark the subsection where the cursor is.
599 ;; Same as mark-defun sgml-mark-current-element.
601 ;; Move backward/forward between section titles.
602 ;; FIXME: Also bind similar to outline mode.
604 ;; Same as beginning-of-defun.
607 ;; Same as end-of-defun.
610 ;;
611 ;; Operating on regions
612 ;;
613 ;; \C-c \C-r is the keymap for regions.
615 ;; Makes region a line-block.
618 ;; Shift region left or right according to tabs.
622 ;;
623 ;; Operating on lists
624 ;;
625 ;; \C-c \C-l is the keymap for lists.
627 ;; Makes paragraphs in region as a bullet list.
630 ;; Makes paragraphs in region as a enumeration.
633 ;; Converts bullets to an enumeration.
636 ;; Make sure that all the bullets in the region are consistent.
639 ;; Insert a list item.
642 ;;
643 ;; Table-of-Contents Features
644 ;;
645 ;; \C-c \C-t is the keymap for table of contents.
647 ;; Enter a TOC buffer to view and move to a specific section.
649 ;; Insert a TOC here.
652 ;; Update the document's TOC (without changing the cursor position).
655 ;; Go to the section under the cursor (cursor must be in TOC).
659 ;;
660 ;; Converting Documents from Emacs
661 ;;
662 ;; \C-c \C-c is the keymap for compilation.
664 ;; Run one of two pre-configured toolset commands on the document.
669 ;; Convert the active region to pseudo-xml using the docutils tools.
672 ;; Convert the current document to PDF and launch a viewer on the results.
675 ;; Convert the current document to S5 slides and view in a web browser.
679 map)
680 "Keymap for reStructuredText mode commands.
684 ;; Abbrevs.
692 ;; FIXME: Add footnotes, links, and more.
693 ))
697 ;; Syntax table.
721 st)
726 "Hook run when `rst-mode' is turned on.
727 The hook for `text-mode' is run before this one."
731 ;; Pull in variable definitions silencing byte-compiler.
734 ;; Use rst-mode for *.rst and *.rest files. Many ReStructured-Text files
735 ;; use *.txt, but this is too generic to be set as a default.
736 ;;;###autoload (add-to-list 'auto-mode-alist (purecopy '("\\.re?st\\'" . rst-mode)))
737 ;;;###autoload
739 "Major mode for editing reStructuredText documents.
742 Turning on `rst-mode' calls the normal hooks `text-mode-hook'
743 and `rst-mode-hook'. This mode also supports font-lock
744 highlighting.
747 :abbrev-table rst-mode-abbrev-table
748 :syntax-table rst-mode-syntax-table
751 ;; Paragraph recognition.
755 lin-end)))
759 lin-end
762 ;; Indenting and filling.
770 ;; Comments.
777 ;; reStructuredText has not really a comment ender but nil is not really a
778 ;; permissible value.
782 ;; Commenting in reStructuredText is very special so use our own set of
783 ;; functions.
795 ;; Font lock.
798 t nil nil nil
803 ;; Text after a changed line may need new fontification.
806 ;;;###autoload
808 "Toggle ReST minor mode.
809 With a prefix argument ARG, enable ReST minor mode if ARG is
810 positive, and disable it otherwise. If called from Lisp, enable
811 the mode if ARG is omitted or nil.
813 When ReST minor mode is enabled, the ReST mode keybindings
814 are installed on top of the major mode bindings. Use this
815 for modes derived from Text mode, like Mail mode."
816 ;; The initial value.
817 nil
818 ;; The indicator for the mode line.
819 " ReST"
820 ;; The minor mode bindings.
821 rst-mode-map
824 ;; FIXME: can I somehow install these too?
825 ;; :abbrev-table rst-mode-abbrev-table
826 ;; :syntax-table rst-mode-syntax-table
828 \f
829 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
830 ;; Section Adornment Adjustment
831 ;; ============================
832 ;;
833 ;; The following functions implement a smart automatic title sectioning feature.
834 ;; The idea is that with the cursor sitting on a section title, we try to get as
835 ;; much information from context and try to do the best thing automatically.
836 ;; This function can be invoked many times and/or with prefix argument to rotate
837 ;; between the various sectioning adornments.
838 ;;
839 ;; Definitions: the two forms of sectioning define semantically separate section
840 ;; levels. A sectioning ADORNMENT consists in:
841 ;;
842 ;; - a CHARACTER
843 ;;
844 ;; - a STYLE which can be either of 'simple' or 'over-and-under'.
845 ;;
846 ;; - an INDENT (meaningful for the over-and-under style only) which determines
847 ;; how many characters and over-and-under style is hanging outside of the
848 ;; title at the beginning and ending.
849 ;;
850 ;; Here are two examples of adornments (| represents the window border, column
851 ;; 0):
852 ;;
853 ;; |
854 ;; 1. char: '-' e |Some Title
855 ;; style: simple |----------
856 ;; |
857 ;; 2. char: '=' |==============
858 ;; style: over-and-under | Some Title
859 ;; indent: 2 |==============
860 ;; |
861 ;;
862 ;; Some notes:
863 ;;
864 ;; - The underlining character that is used depends on context. The file is
865 ;; scanned to find other sections and an appropriate character is selected.
866 ;; If the function is invoked on a section that is complete, the character is
867 ;; rotated among the existing section adornments.
868 ;;
869 ;; Note that when rotating the characters, if we come to the end of the
870 ;; hierarchy of adornments, the variable rst-preferred-adornments is
871 ;; consulted to propose a new underline adornment, and if continued, we cycle
872 ;; the adornments all over again. Set this variable to nil if you want to
873 ;; limit the underlining character propositions to the existing adornments in
874 ;; the file.
875 ;;
876 ;; - An underline/overline that is not extended to the column at which it should
877 ;; be hanging is dubbed INCOMPLETE. For example::
878 ;;
879 ;; |Some Title
880 ;; |-------
881 ;;
882 ;; Examples of default invocation:
883 ;;
884 ;; |Some Title ---> |Some Title
885 ;; | |----------
886 ;;
887 ;; |Some Title ---> |Some Title
888 ;; |----- |----------
889 ;;
890 ;; | |------------
891 ;; | Some Title ---> | Some Title
892 ;; | |------------
893 ;;
894 ;; In over-and-under style, when alternating the style, a variable is
895 ;; available to select how much default indent to use (it can be zero). Note
896 ;; that if the current section adornment already has an indent, we don't
897 ;; adjust it to the default, we rather use the current indent that is already
898 ;; there for adjustment (unless we cycle, in which case we use the indent
899 ;; that has been found previously).
902 "Settings for adjustment and cycling of section title adornments."
916 "Preferred hierarchy of section title adornments.
918 A list consisting of lists of the form (CHARACTER STYLE INDENT).
919 CHARACTER is the character used. STYLE is one of the symbols
920 OVER-AND-UNDER or SIMPLE. INDENT is an integer giving the wanted
921 indentation for STYLE OVER-AND-UNDER. CHARACTER and STYLE are
922 always used when a section adornment is described. In other
923 places t instead of a list stands for a transition.
925 This sequence is consulted to offer a new adornment suggestion
926 when we rotate the underlines at the end of the existing
927 hierarchy of characters, or when there is no existing section
928 title in the file.
930 Set this to an empty list to use only the adornment found in the
931 file."
939 rst-adornment-chars))
947 "Number of characters to indent the section title.
949 This is used for when toggling adornment styles, when switching
950 from a simple adornment style to a over-and-under adornment
951 style."
957 "Compare adornments.
958 Return true if both ADO1 and ADO2 adornments are equal,
959 according to restructured text semantics (only the character and
960 the style are compared, the indentation does not matter)."
966 "Return the index (level) in hierarchy HIER of adornment ADO.
967 This basically just searches for the item using the appropriate
968 comparison and returns the index. Return nil if the item is
969 not found."
973 cur))
977 "Suggest a new, different adornment from all that have been seen.
979 ALLADOS is the set of all adornments, including the line numbers.
980 PREV is the optional previous adornment, in order to suggest a
981 better match."
983 ;; For all the preferred adornments...
985 ;; If 'prev' is given, reorder the list to start searching after the
986 ;; match.
990 ;; List of candidates to search.
993 ;; For all the adornments...
995 found)
998 ;; Found it!
1001 found)
1008 "Delete the entire current line without using the `kill-ring'."
1013 "Unconditionally update the style of a section adornment.
1015 Do this using the given character CHAR, with STYLE 'simple
1016 or 'over-and-under, and with indent INDENT. If the STYLE
1017 is 'simple, whitespace before the title is removed (indent
1018 is always assumed to be 0).
1020 If there are existing overline and/or underline from the
1021 existing adornment, they are removed before adding the
1022 requested adornment."
1025 len)
1027 ;; Fixup whitespace at the beginning and end of the line.
1037 ;; Set the current column, we're at the end of the title line.
1040 ;; Remove previous line if it is an adornment.
1044 ;; Avoid removing the underline of a title right above us.
1049 ;; Remove following line if it is an adornment.
1054 ;; Add a newline if we're at the end of the buffer, for the subsequence
1055 ;; inserting of the underline.
1059 ;; Insert overline.
1066 ;; Insert underline.
1073 ))
1076 "Classify adornment for section titles and transitions.
1077 ADORNMENT is the complete adornment string as found in the buffer
1078 with optional trailing whitespace. END is the point after the
1079 last character of ADORNMENT.
1081 Return a list. The first entry is t for a transition or a
1082 cons (CHARACTER . STYLE). Check `rst-preferred-adornments' for
1083 the meaning of CHARACTER and STYLE.
1085 The remaining list forms four match groups as returned by
1086 `match-data'. Match group 0 matches the whole construct. Match
1087 group 1 matches the overline adornment if present. Match group 2
1088 matches the section title text or the transition. Match group 3
1089 matches the underline adornment.
1091 Return nil if no syntactically valid adornment is found."
1134 key beg-ovr end-ovr beg-txt end-txt beg-und end-und)
1137 ;; A transition.
1139 beg-txt beg-pnt
1140 end-txt end-pnt))
1142 ;; An overline with an underline.
1158 ;; An underline.
1160 beg-und beg-pnt
1161 end-und end-pnt)
1166 ;; Invalid adornment.
1172 beg-ovr end-ovr beg-txt end-txt beg-und end-und)))))))
1175 "Find a section title line around point and return its characteristics.
1176 If the point is on an adornment line find the respective title
1177 line. If the point is on an empty line check previous or next
1178 line whether it is a suitable title line and use it if so. If
1179 point is on a suitable title line use it.
1181 If no title line is found return nil.
1183 Otherwise return as `rst-classify-adornment' does. However, if
1184 the title line has no syntactically valid adornment STYLE is nil
1185 in the first element. If there is no adornment around the title
1186 CHARACTER is also nil and match groups for overline and underline
1187 are nil."
1199 ;; Invalid adornment - check whether this is an incomplete overline.
1206 ;; A section title - not a transition.
1207 r))))
1221 ;; Try to use the underline.
1227 r
1228 ;; No valid adornment found.
1232 ;; The following function and variables are used to maintain information about
1233 ;; current section adornment in a buffer local cache. Thus they can be used for
1234 ;; font-locking and manipulation commands.
1237 "All section adornments in the buffer as found by `rst-find-all-adornments'.
1241 ;; FIXME: If this variable is set to a different value font-locking of section
1242 ;; headers is wrong.
1244 "Section hierarchy in the buffer as determined by `rst-get-hierarchy'.
1245 t when no section adornments were found. Value depends on
1250 "Reset all section cache variables.
1251 Should be called by interactive functions which deal with sections."
1253 rst-section-hierarchy nil))
1256 "Return all the section adornments in the current buffer.
1257 Return a list of (LINE . ADORNMENT) with ascending LINE where
1258 LINE is the line containing the section title. ADORNMENT consists
1259 of a (CHARACTER STYLE INDENT) triple as described for
1260 `rst-preferred-adornments'.
1262 Uses and sets `rst-all-sections'."
1265 ;; Iterate over all the section titles/adornments in the file.
1279 positions)
1284 nil
1285 rst-all-sections))
1288 "Build a hierarchy of adornments using the list of given ADORNMENTS.
1290 ADORNMENTS is a list of (CHARACTER STYLE INDENT) adornment
1291 specifications, in order that they appear in a file, and will
1292 infer a hierarchy of section levels by removing adornments that
1293 have already been seen in a forward traversal of the adornments,
1294 comparing just CHARACTER and STYLE.
1296 Similarly returns a list of (CHARACTER STYLE INDENT), where each
1297 list element should be unique."
1307 "Return the hierarchy of section titles in the file.
1309 Return a list of adornments that represents the hierarchy of
1310 section titles in the file. Each element consists of (CHARACTER
1311 STYLE INDENT) as described for `rst-find-all-adornments'. If the
1312 line number in IGNORE is specified, a possibly adornment found on
1313 that line is not taken into account when building the hierarchy.
1315 Uses and sets `rst-section-hierarchy' unless IGNORE is given."
1318 nil
1319 rst-section-hierarchy)
1323 ignore
1327 ;; Clear cache reflecting that a possible update is not
1328 ;; reflected.
1329 nil
1331 r)))
1334 "Return the adornments around point.
1335 Return a list of the previous and next adornments."
1338 prev next
1341 ;; Search for the adornments around the current line.
1345 ;; 'cur' is the following adornment.
1351 ))
1355 "Return true if the adornment ADO around point is complete."
1356 ;; Note: we assume that the detection of the overline as being the underline
1357 ;; of a preceding title has already been detected, and has been eliminated
1358 ;; from the adornment that is given to us.
1360 ;; There is some sectioning already present, so check if the current
1361 ;; sectioning is complete and correct.
1366 )
1377 ))
1378 ))
1383 "Get the next adornment for CURADO, in given hierarchy HIER.
1384 If suggesting, suggest for new adornment SUGGESTION.
1385 REVERSE-DIRECTION is used to reverse the cycling order."
1391 ;; Build a new list of adornments for the rotation.
1394 ;; Suggest a new adornment.
1396 ;; If nothing to suggest, use first adornment.
1399 ;; Search for next adornment.
1407 cur))
1409 ;; If not found, take the first of all adornments.
1410 suggestion
1411 )))
1414 ;; FIXME: A line "``/`` full" is not accepted as a section title.
1416 "Auto-adjust the adornment around point.
1418 Adjust/rotate the section adornment for the section title around
1419 point or promote/demote the adornments inside the region,
1420 depending on if the region is active. This function is meant to
1421 be invoked possibly multiple times, and can vary its behavior
1422 with a positive PFXARG (toggle style), or with a negative
1423 PFXARG (alternate behavior).
1425 This function is a bit of a swiss knife. It is meant to adjust
1426 the adornments of a section title in reStructuredText. It tries
1427 to deal with all the possible cases gracefully and to do `the
1428 right thing' in all cases.
1430 See the documentations of `rst-adjust-adornment-work' and
1431 `rst-promote-region' for full details.
1433 Prefix Arguments
1434 ================
1436 The method can take either (but not both) of
1438 a. a (non-negative) prefix argument, which means to toggle the
1439 adornment style. Invoke with a prefix argument for example;
1441 b. a negative numerical argument, which generally inverts the
1442 direction of search in the file or hierarchy. Invoke with C--
1443 prefix for example."
1453 ;; Adjust adornments within region.
1455 ;; Adjust adornment around point.
1458 ;; Run the hooks to run after adjusting.
1461 ;; Make sure to reset the cursor position properly after we're done.
1464 ))
1467 "Hooks to be run after running `rst-adjust'."
1473 "Controls level of new adornment for section headers."
1481 "Call `rst-adjust-adornment-work' interactively.
1483 Keep this for compatibility for older bindings (are there any?).
1484 Argument PFXARG has the same meaning as for `rst-adjust'."
1492 "Adjust/rotate the section adornment for the section title around point.
1494 This function is meant to be invoked possibly multiple times, and
1495 can vary its behavior with a true TOGGLE-STYLE argument, or with
1496 a REVERSE-DIRECTION argument.
1498 General Behavior
1499 ================
1501 The next action it takes depends on context around the point, and
1502 it is meant to be invoked possibly more than once to rotate among
1503 the various possibilities. Basically, this function deals with:
1505 - adding a adornment if the title does not have one;
1507 - adjusting the length of the underline characters to fit a
1508 modified title;
1510 - rotating the adornment in the set of already existing
1511 sectioning adornments used in the file;
1513 - switching between simple and over-and-under styles.
1515 You should normally not have to read all the following, just
1516 invoke the method and it will do the most obvious thing that you
1517 would expect.
1520 Adornment Definitions
1521 =====================
1523 The adornments consist in
1525 1. a CHARACTER
1527 2. a STYLE which can be either of 'simple' or 'over-and-under'.
1529 3. an INDENT (meaningful for the over-and-under style only)
1530 which determines how many characters and over-and-under
1531 style is hanging outside of the title at the beginning and
1532 ending.
1534 See source code for mode details.
1537 Detailed Behavior Description
1538 =============================
1540 Here are the gory details of the algorithm (it seems quite
1541 complicated, but really, it does the most obvious thing in all
1542 the particular cases):
1544 Before applying the adornment change, the cursor is placed on
1545 the closest line that could contain a section title.
1547 Case 1: No Adornment
1548 --------------------
1550 If the current line has no adornment around it,
1552 - search backwards for the last previous adornment, and apply
1553 the adornment one level lower to the current line. If there
1554 is no defined level below this previous adornment, we suggest
1555 the most appropriate of the `rst-preferred-adornments'.
1557 If REVERSE-DIRECTION is true, we simply use the previous
1558 adornment found directly.
1560 - if there is no adornment found in the given direction, we use
1561 the first of `rst-preferred-adornments'.
1563 TOGGLE-STYLE forces a toggle of the prescribed adornment style.
1565 Case 2: Incomplete Adornment
1566 ----------------------------
1568 If the current line does have an existing adornment, but the
1569 adornment is incomplete, that is, the underline/overline does
1570 not extend to exactly the end of the title line (it is either too
1571 short or too long), we simply extend the length of the
1572 underlines/overlines to fit exactly the section title.
1574 If TOGGLE-STYLE we toggle the style of the adornment as well.
1576 REVERSE-DIRECTION has no effect in this case.
1578 Case 3: Complete Existing Adornment
1579 -----------------------------------
1581 If the adornment is complete (i.e. the underline (overline)
1582 length is already adjusted to the end of the title line), we
1583 search/parse the file to establish the hierarchy of all the
1584 adornments (making sure not to include the adornment around
1585 point), and we rotate the current title's adornment from within
1586 that list (by default, going *down* the hierarchy that is present
1587 in the file, i.e. to a lower section level). This is meant to be
1588 used potentially multiple times, until the desired adornment is
1589 found around the title.
1591 If we hit the boundary of the hierarchy, exactly one choice from
1592 the list of preferred adornments is suggested/chosen, the first
1593 of those adornment that has not been seen in the file yet (and
1594 not including the adornment around point), and the next
1595 invocation rolls over to the other end of the hierarchy (i.e. it
1596 cycles). This allows you to avoid having to set which character
1597 to use.
1599 If REVERSE-DIRECTION is true, the effect is to change the
1600 direction of rotation in the hierarchy of adornments, thus
1601 instead going *up* the hierarchy.
1603 However, if TOGGLE-STYLE, we do not rotate the adornment, but
1604 instead simply toggle the style of the current adornment (this
1605 should be the most common way to toggle the style of an existing
1606 complete adornment).
1609 Point Location
1610 ==============
1612 The invocation of this function can be carried out anywhere
1613 within the section title line, on an existing underline or
1614 overline, as well as on an empty line following a section title.
1615 This is meant to be as convenient as possible.
1618 Indented Sections
1619 =================
1621 Indented section titles such as ::
1623 My Title
1624 --------
1626 are invalid in reStructuredText and thus not recognized by the
1627 parser. This code will thus not work in a way that would support
1628 indented sections (it would be ambiguous anyway).
1631 Joint Sections
1632 ==============
1634 Section titles that are right next to each other may not be
1635 treated well. More work might be needed to support those, and
1636 special conditions on the completeness of existing adornments
1637 might be required to make it non-ambiguous.
1639 For now we assume that the adornments are disjoint, that is,
1640 there is at least a single line between the titles/adornment
1641 lines."
1653 char-new style-new indent-new)
1655 ;;-------------------------------------------------------------------
1656 ;; Case 1: No valid adornment
1659 cur
1661 ;; Advance one level down.
1667 prev
1671 ;; Invert the style if requested.
1678 ;;-------------------------------------------------------------------
1679 ;; Case 2: Incomplete Adornment
1681 ;; Invert the style if requested.
1685 style-new style
1686 indent-new indent))
1687 ;;-------------------------------------------------------------------
1688 ;; Case 3: Complete Existing Adornment
1691 ;; Simply switch the style of the current adornment.
1694 indent-new rst-default-indent)
1695 ;; Else, we rotate, ignoring the adornment around the current
1696 ;; line...
1698 ;; Suggestion, in case we need to come up with something new.
1700 hier
1703 curado hier suggestion reverse-direction)))
1704 ;; Indent, if present, always overrides the prescribed indent.
1708 ;; Override indent with present indent!
1712 ;; Correct the position of the cursor to more accurately reflect where
1713 ;; it was located when the function was invoked.
1718 ;; Maintain an alias for compatibility.
1723 "Promote the section titles within the region.
1725 With argument DEMOTE or a prefix argument, demote the section
1726 titles instead. The algorithm used at the boundaries of the
1727 hierarchy is similar to that used by `rst-adjust-adornment-work'."
1737 marker-list
1738 )
1740 ;; Skip the markers that come before the region beginning.
1744 ;; Create a list of markers for all the adornments which are found within
1745 ;; the region.
1754 ;; Apply modifications.
1756 ;; Go to the adornment to promote.
1759 ;; Update the adornment.
1761 ;; Rotate the next adornment.
1765 ;; Clear marker to avoid slowing down the editing after we're done.
1768 )))
1773 "Display the current file's section title adornments hierarchy.
1774 This function expects a list of (CHARACTER STYLE INDENT) triples
1775 in ADORNMENTS."
1789 ))
1790 )))
1793 "Redo all the adornments in the current buffer.
1794 This is done using our preferred set of adornments. This can be
1795 used, for example, when using somebody else's copy of a document,
1796 in order to adapt it to our preferred style."
1811 ;; Go to the appropriate position.
1814 ;; Apply the new style.
1817 ;; Reset the marker to avoid slowing down editing until it gets GC'ed.
1819 )
1820 )))
1823 \f
1824 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1825 ;; Insert list items
1826 ;; =================
1829 ;=================================================
1830 ; Borrowed from a2r.el (version 1.3), by Lawrence Mitchell <wence@gmx.li>.
1831 ; I needed to make some tiny changes to the functions, so I put it here.
1832 ; -- Wei-Wei Guo
1842 "Convert Arabic number NUM to its Roman numeral representation.
1844 Obviously, NUM must be greater than zero. Don't blame me, blame the
1846 apologies to Monty Python).
1847 If optional prefix ARG is non-nil, insert in current buffer."
1849 res)
1856 res))
1859 "Convert STRING of Roman numerals to an Arabic number.
1861 If STRING contains a letter which isn't a valid Roman numeral, the rest
1862 of the string from that point onwards is ignored.
1864 Hence:
1865 MMD == 2500
1866 and
1867 MMDFLXXVI == 2500.
1868 If optional ARG is non-nil, insert in current buffer."
1876 res))
1877 ;=================================================
1880 "Find all the positions of prefixes in region between BEG and END.
1881 This is used to find bullets and enumerated list items. PFX-RE is
1882 a regular expression for matching the lines after indentation
1883 with items. Returns a list of cons cells consisting of the point
1884 and the column of the point."
1901 pfx))
1906 "Arrange relative position of a newly inserted list item of style NEWITEM.
1908 Adding a new list might consider three situations:
1910 (a) Current line is a blank line.
1911 (b) Previous line is a blank line.
1912 (c) Following line is a blank line.
1914 When (a) and (b), just add the new list at current line.
1916 when (a) and not (b), a blank line is added before adding the new list.
1918 When not (a), first forward point to the end of the line, and add two
1919 blank lines, then add the new list.
1921 Other situations are just ignored and left to users themselves."
1933 ;; FIXME: Isn't this a `defconst'?
1942 ;; FIXME: Isn't this a `defconst'?
1948 "Insert a new list item.
1950 User is asked to select the item style first, for example (a), i), +. Use TAB
1951 for completion and choices.
1953 If user selects bullets or #, it's just added with position arranged by
1954 `rst-insert-list-pos'.
1956 If user selects enumerations, a further prompt is given. User need to input a
1957 starting item, for example 'e' for 'A)' style. The position is also arranged by
1958 `rst-insert-list-pos'."
1960 ;; FIXME: Make this comply to `interactive' standards.
1962 "Select preferred item style [#.]: "
1968 ;; FIXME: Make this comply to `interactive' standards.
1993 "List of favorite bullets."
1999 rst-bullets)))
2003 "Insert a list item with list start CURITEM including its indentation level.
2004 If PREFER-ROMAN roman numbering is preferred over using letters."
2011 curitem)
2015 nil nil curitem))
2020 ;; FIXME: Assumes one line list items without separating
2021 ;; empty lines.
2038 t nil curitem))
2042 nil nil curitem)))))
2046 "Insert a list item at the current point.
2048 The command can insert a new list or a continuing list. When it is called at a
2049 non-list line, it will promote to insert new list. When it is called at a list
2050 line, it will insert a list with the same list style.
2052 1. When inserting a new list:
2054 User is asked to select the item style first, for example (a), i), +. Use TAB
2055 for completion and choices.
2057 (a) If user selects bullets or #, it's just added.
2058 (b) If user selects enumerations, a further prompt is given. User needs to
2059 input a starting item, for example 'e' for 'A)' style.
2061 The position of the new list is arranged according to whether or not the
2062 current line and the previous line are blank lines.
2064 2. When continuing a list, one thing need to be noticed:
2066 List style alphabetical list, such as 'a.', and roman numerical list, such as
2067 'i.', have some overlapping items, for example 'v.' The function can deal with
2068 the problem elegantly in most situations. But when those overlapped list are
2069 preceded by a blank line, it is hard to determine which type to use
2070 automatically. The function uses alphabetical list by default. If you want
2071 roman numerical list, just use a prefix to set PREFER-ROMAN."
2079 "Make all the bulleted list items in the region consistent.
2080 The region is specified between BEG and END. You can use this
2081 after you have merged multiple bulleted lists to make them use
2082 the same/correct/consistent bullet characters.
2084 See variable `rst-preferred-bullets' for the list of bullets to
2085 adjust. If bullets are found on levels beyond the
2086 `rst-preferred-bullets' list, they are not modified."
2092 ;; Create a map of levels to list of positions.
2098 levtable)))
2100 ;; Sort this map and create a new map of prefix char and list of positions.
2107 ;; Apply the characters.
2114 \f
2115 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2116 ;; Table of contents
2117 ;; =================
2120 "Return the line at cursor, stripped from whitespace."
2126 "Get the hierarchical tree of section titles.
2128 Returns a hierarchical tree of the sections titles in the
2129 document. This can be used to generate a table of contents for
2130 the document. The top node will always be a nil node, with the
2131 top level titles as children (there may potentially be more than
2132 one).
2134 Each section title consists in a cons of the stripped title
2135 string and a marker to the section in the original text document.
2137 If there are missing section levels, the section titles are
2138 inserted automatically, and the title string is set to nil, and
2139 the marker set to the first non-nil child of itself.
2140 Conceptually, the nil nodes--i.e.\ those which have no title--are
2141 to be considered as being the same line as their first non-nil
2142 child. This has advantages later in processing the graph."
2146 lines)
2150 ;; Compare just the character and indent in the hash table.
2154 ;; Create a list of lines that contains (text, level, marker) for each
2155 ;; adornment.
2172 "Recursive guts of the section tree construction.
2173 ADOS is a cons cell whose cdr is the remaining list of
2174 adornments, and we change it as we consume them. LEV is
2175 the current level of that node. This function returns a
2176 pair of the subtree that was built. This treats the ADOS
2177 list destructively."
2180 node
2181 children)
2183 ;; If the next adornment matches our level.
2185 ;; Pop the next adornment and create the current node with it.
2188 ;; Else we let the node title/marker be unset.
2190 ;; Build the child nodes.
2194 children)))
2197 ;; If node is still unset, we use the marker of the first child.
2201 ;; Return this node with its children.
2203 ))
2207 "Find tree node at point.
2208 Given a computed and valid section tree in NODE and a point
2209 POINT (default being the current point in the current buffer),
2210 find and return the node within the section tree where the cursor
2211 lives.
2213 Return values: a pair of (parent path, container subtree).
2214 The parent path is simply a list of the nodes above the
2215 container subtree node that we're returning."
2221 ;; Check if we are before the current node.
2224 ;; Iterate all the children, looking for one that might contain the
2225 ;; current section.
2227 last)
2239 )))
2241 ))
2245 "Settings for reStructuredText table of contents."
2250 "Indentation for table-of-contents display.
2251 Also used for formatting insertion, when numbering is disabled."
2255 "Insertion style for table-of-contents.
2256 Set this to one of the following values to determine numbering and
2257 indentation style:
2258 - plain: no numbering (fixed indentation)
2259 - fixed: numbering, but fixed indentation
2260 - aligned: numbering, titles aligned under each other
2261 - listed: numbering, with dashes like list items (EXPERIMENTAL)"
2265 "Separator that goes between the TOC number and the title."
2268 ;; This is used to avoid having to change the user's mode.
2272 map)
2276 "If non-nil, maximum depth of the inserted TOC."
2281 "Insert a simple text rendering of the table of contents.
2282 By default the top level is ignored if there is only one, because
2283 we assume that the document will have a single title.
2285 If a numeric prefix argument PFXARG is given, insert the TOC up
2286 to the specified level.
2288 The TOC is inserted indented at the current column."
2296 ;; Get the section tree for the current cursor point.
2301 ;; Figure out initial indent.
2308 ;; Fixup for the first line.
2311 ;; Delete the last newline added.
2313 )))
2316 "Insert tree node NODE in table-of-contents.
2317 Recursive function that does printing of the inserted toc.
2318 LEVEL is the depth level of the sections in the tree.
2319 INDENT is the indentation string. PFX is the prefix numbering,
2320 that includes the alignment necessary for all the children of
2321 level to align."
2323 ;; Note: we do child numbering from the parent, so we start number the
2324 ;; children one level before we print them.
2333 ;; Add properties to the text, even though in normal text mode it
2334 ;; won't be doing anything for now. Not sure that I want to change
2335 ;; mode stuff. At least the highlighting gives the idea that this
2336 ;; is generated automatically.
2341 )
2344 ;; Prepare indent for children.
2359 ))
2360 )
2365 fmt)
2368 ;; Add a separating dot if there is already a prefix.
2373 ;; Calculate the amount of space that the prefix will require
2374 ;; for the numbers.
2379 ))
2384 indent
2389 )))
2393 "Automatically find the contents section of a document and update.
2394 Updates the inserted TOC if present. You can use this in your
2395 file-write hook to always make it up-to-date automatically."
2398 ;; Find and delete an existing comment after the first contents directive.
2399 ;; Delete that region.
2401 ;; We look for the following and the following only (in other words, if your
2402 ;; syntax differs, this won't work.).
2403 ;;
2404 ;; .. contents:: [...anything here...]
2405 ;; [:field: value]...
2406 ;; ..
2407 ;; XXXXXXXX
2408 ;; XXXXXXXX
2409 ;; [more lines]
2413 last-real)
2415 ;; Look for the first line that starts at the first column.
2432 ;; Note: always return nil, because this may be used as a hook.
2433 nil)
2435 ;; Note: we cannot bind the TOC update on file write because it messes with
2436 ;; undo. If we disable undo, since it adds and removes characters, the
2437 ;; positions in the undo list are not making sense anymore. Dunno what to do
2438 ;; with this, it would be nice to update when saving.
2439 ;;
2440 ;; (add-hook 'write-contents-hooks 'rst-toc-update-fun)
2441 ;; (defun rst-toc-update-fun ()
2442 ;; ;; Disable undo for the write file hook.
2443 ;; (let ((buffer-undo-list t)) (rst-toc-update) ))
2447 ;;------------------------------------------------------------------------------
2450 "Recursive function that does insert NODE at LEVEL in the table-of-contents."
2454 ;; Insert line text.
2458 ;; Highlight lines.
2461 ;; Add link on lines.
2465 ))
2471 "Count the number of lines from NODE to the TARGET-NODE node.
2472 This recursive function returns a cons of the number of
2473 additional lines that have been counted for its node and
2474 children, and t if the node has been found."
2477 found)
2496 "Display a table-of-contents.
2497 Finds all the section titles and their adornments in the
2498 file, and displays a hierarchically-organized list of the
2499 titles, which is essentially a table-of-contents of the
2500 document.
2502 The Emacs buffer can be navigated, and selecting a section
2503 brings the cursor in that section."
2510 line
2512 ;; Create a temporary buffer.
2514 )
2525 ;; Count the lines to our found node.
2528 ))
2532 ;; Save the buffer to return to.
2535 ;; Move the cursor near the right section in the TOC.
2538 ))
2542 "Get the section from text property at point."
2548 pos))
2550 ;; FIXME: Cursor before or behind the list must be handled properly; before the
2551 ;; list should jump to the top and behind the list to the last normal
2552 ;; paragraph.
2554 "Go to the section the current line describes.
2555 If KILL a toc buffer is destroyed."
2559 ;; FIXME: This should rather go to `rst-toc-mode-goto-section'.
2564 ;; FIXME: make the recentering conditional on scroll.
2568 "Go to the section the current line describes and kill the TOC buffer."
2573 "In `rst-toc' mode, go to the occurrence whose line you click on.
2574 EVENT is the input event."
2586 "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well.
2587 EVENT is the input event."
2593 "Leave the current TOC buffer."
2607 map)
2612 ;; Could inherit from the new `special-mode'.
2617 ;; Note: use occur-mode (replace.el) as a good example to complete missing
2618 ;; features.
2620 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2621 ;; Section movement commands
2622 ;; =========================
2625 "Skip to the next reStructuredText section title.
2626 OFFSET specifies how many titles to skip. Use a negative OFFSET to move
2627 backwards in the file (default is to use 1)."
2633 ;; Get all the adornments in the file, with their line numbers.
2636 ;; Get the current line.
2641 )
2643 ;; Find the index of the "next" adornment w.r.t. to the current line.
2647 ;; 'cur' is the adornment on or following the current line.
2652 ;; Find the final index.
2656 ;; If the index is positive, goto the line, otherwise go to the buffer
2657 ;; boundaries.
2663 ))
2666 "Like `rst-forward-section', except move back one title."
2670 ;; FIXME: What is `allow-extend' for?
2672 "Select COUNT sections around point.
2673 Mark following sections for positive COUNT or preceding sections
2674 for negative COUNT."
2675 ;; Cloned from mark-paragraph.
2693 \f
2694 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2695 ;; Functions to work on item lists (e.g. indent/dedent, enumerate), which are
2696 ;; always 2 or 3 characters apart horizontally with rest.
2699 "Return the leftmost column in region BEG to END."
2710 mincol))
2712 ;; FIXME: This definition is old and deprecated. We need to move to the newer
2713 ;; version below.
2716 ;; FIXME: The following comment is pretty useless.
2717 "Call FUN at the beginning of each line, with an argument that
2718 specifies whether we are at the first line of a paragraph that
2719 starts at the leftmost column of the given region BEG and END.
2720 Set FIRST-ONLY to true if you want to callback on the first line
2721 of each paragraph only."
2739 )
2744 valid)
2745 ,body-consequent
2748 ))))
2750 ;; FIXME: This needs to be refactored. Probably this is simply a function
2751 ;; applying BODY rather than a macro.
2753 "Evaluate BODY for each line in region defined by BEG END.
2754 LEFTMOST is set to true if the line is one of the leftmost of the
2755 entire paragraph. PARABEGIN is set to true if the line is the
2756 first of a paragraph."
2782 )
2787 )))))
2789 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2790 ;; Indentation
2792 ;; FIXME: At the moment only block comments with leading empty comment line are
2793 ;; supported. Comment lines with leading comment markup should be also
2794 ;; supported. May be a customizable option could control which style to
2795 ;; prefer.
2799 In reStructuredText indentation points are usually determined by
2800 preceding lines. Sometimes the syntax allows arbitrary
2801 indentation points such as where to start the first line
2802 following a directive. These indentation widths can be customized
2803 here."
2810 "Indentation when there is no more indentation point given."
2815 "Indentation for first line after a field or 0 to always indent for content."
2820 "Default indentation for literal block after a markup on an own line."
2825 "Default indentation for literal block after a minimized markup."
2830 "Default indentation for first line of a comment."
2834 ;; FIXME: Must consider other tabs:
2835 ;; * Line blocks
2836 ;; * Definition lists
2837 ;; * Option lists
2839 "Return tabs of the current line or nil for no tab.
2840 The list is sorted so the tab where writing continues most likely
2841 is the first one. Each tab is of the form (COLUMN . INNER).
2842 COLUMN is the column of the tab. INNER is non-nil if this is an
2843 inner tab. I.e. a tab which does come from the basic indentation
2844 and not from inner alignment points."
2850 ;; Current indentation is always the least likely tab.
2852 ;; Push inner tabs more likely to continue writing.
2854 ;; Item.
2858 ;; Field.
2869 ;; Directive.
2876 ;; Footnote or citation definition.
2881 ;; Comment.
2884 ;; Start of literal block.
2890 rst-indent-literal-minimized
2891 rst-indent-literal-normal))
2896 tabs))))))
2899 "Build the list of possible tabs for all lines above.
2900 Search backwards from point PT to build the list of possible
2901 tabs. Return a list of tabs sorted by likeliness to continue
2902 writing like `rst-line-tabs'. Nearer lines have generally a
2903 higher likeliness than farther lines. Return nil if no tab is found
2904 in the text above."
2908 innermost ; Leftmost column for inner tab.
2909 tablist)
2916 ;; Consider only lines indented less or same if not INNERMOST.
2934 leftcol
2935 innermost))
2940 "Indent current line to next best reStructuredText tab.
2941 The next best tab is taken from the tab list returned by
2942 `rst-compute-tabs' which is used in a cyclic manner. If the
2943 current indentation does not end on a tab use the first one. If
2944 the current indentation is on a tab use the next tab. This allows
2946 possible tabs. If no indentation is possible return `noindent' or
2947 use DFLT. Return the indentation indented to. When point is in
2948 indentation it ends up at its end. Otherwise the point is kept
2949 relative to the content."
2955 ind)
2957 'noindent
2970 ind)))
2973 "Shift region BEG to END by CNT tabs.
2974 Shift by one tab to the right (CNT > 0) or left (CNT < 0) or
2975 remove all indentation (CNT = 0). A tab is taken from the text
2976 above. If no suitable tab is found `rst-indent-width' is used."
2981 ;; Apply the indent.
2983 beg end
2986 ;; Find the next tab after the leftmost column.
2992 ;; Get the position of the first tab beyond leftmostcol.
2997 tabs)))
2998 ;; Virtual position of tab.
3001 ;; Tab exists - use it.
3003 ;; Column needs to be computed.
3005 ;; Base on last known column.
3007 dir ; Direction to take.
3008 rst-indent-width))))
3012 ;; FIXME: A paragraph with an (incorrectly) indented second line is not filled
3013 ;; correctly::
3014 ;;
3015 ;; Some start
3016 ;; continued wrong
3018 "Return fill prefix found at point.
3019 Value for `adaptive-fill-function'."
3024 ;; An non-comment prefix is fine.
3025 fnd
3026 ;; Matches a comment - return whitespace instead.
3035 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3036 ;; Comments
3039 "Break line and indent, continuing reStructuredText comment if within one.
3040 Value for `comment-line-break-function'. If SOFT use soft
3041 newlines as mandated by `comment-line-break-function'."
3054 "Return indentation for current comment line."
3058 "Insert a comment in the current line."
3063 "Comment or uncomment the current region.
3064 Region is from from BEG to END. Uncomment if ARG."
3070 bol)
3080 "Uncomment the current region.
3081 Region is from BEG to END. ARG is ignored"
3092 ;;------------------------------------------------------------------------------
3094 ;; FIXME: These next functions should become part of a larger effort to redo
3095 ;; the bullets in bulleted lists. The enumerate would just be one of
3096 ;; the possible outputs.
3097 ;;
3098 ;; FIXME: We need to do the enumeration removal as well.
3101 "Add enumeration to all the leftmost paragraphs in the given region.
3102 The region is specified between BEG and END. With ALL,
3103 do all lines instead of just paragraphs."
3113 )))
3116 "Add bullets to all the leftmost paragraphs in the given region.
3117 The region is specified between BEG and END. With ALL,
3118 do all lines instead of just paragraphs."
3124 ))
3126 ;; FIXME: Does not deal with a varying number of digits appropriately.
3127 ;; FIXME: Does not deal with multiple levels independently.
3128 ;; FIXME: Does not indent a multiline item correctly.
3130 "Convert the bulleted and enumerated items in the region to enumerated lists.
3131 Renumber as necessary. Region is from BEG to END."
3140 )
3147 ))
3148 ))
3152 ;;------------------------------------------------------------------------------
3155 "Toggle line block prefixes for a region.
3156 Region is from RBEG to REND. With PFXARG set the empty lines too."
3171 \f
3172 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3173 ;; Font lock
3174 ;; =========
3178 ;; FIXME: The obsolete variables need to disappear.
3180 ;; The following versions have been done inside Emacs and should not be
3181 ;; replaced by `:package-version' attributes until a change.
3189 "Face used for all syntax marking up a special block."
3194 "All syntax marking up a special block."
3199 "customize the face `rst-block' instead."
3203 "Face used for field names and interpreted text."
3208 "Field names and interpreted text."
3213 "customize the face `rst-external' instead."
3217 "Face used for all other defining constructs."
3222 "All other defining constructs."
3227 "customize the face `rst-definition' instead."
3230 ;; XEmacs compatibility (?).
3234 "Face used for directives and roles."
3239 "Directives and roles."
3243 "customize the face `rst-directive' instead."
3247 "Face used for comments."
3252 "Comments."
3257 "customize the face `rst-comment' instead."
3261 "Face used for simple emphasis."
3266 "Simple emphasis."
3271 "customize the face `rst-emphasis1' instead."
3275 "Face used for double emphasis."
3280 "Double emphasis."
3284 "customize the face `rst-emphasis2' instead."
3288 "Face used for literal text."
3293 "Literal text."
3298 "customize the face `rst-literal' instead."
3302 "Face used for references to a definition."
3307 "References to a definition."
3312 "customize the face `rst-reference' instead."
3316 "Face used for a transition."
3321 "Face used for the adornment of a section header."
3325 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3327 ;; FIXME LEVEL-FACE: May be this complicated mechanism should be replaced
3328 ;; simply by a number of customizable faces `rst-header-%d'
3329 ;; which by default are set properly for dark and light
3330 ;; background. Initialization should come from the old
3331 ;; variables if they exist. A maximum level of 6 should
3332 ;; suffice - after that the last level should be repeated.
3333 ;; Only `rst-adornment-faces-alist' is needed outside this
3334 ;; block. Would also fix docutils-Bugs-3479594.
3337 "Values used to generate default faces for section titles on all levels.
3338 Tweak these if you are content with how section title faces are built in
3339 general but you do not like the details."
3344 "Set custom variable SYM affecting section title text face.
3345 Recompute the faces. VAL is the value to set."
3347 ;; Also defines the faces initially when all values are available.
3356 ;; Faces for displaying items on several levels. These definitions define
3357 ;; different shades of gray where the lightest one (i.e. least contrasting on a
3358 ;; light background) is used for level 1.
3360 "Maximum depth of levels for which section title faces are defined."
3364 ;; FIXME: It should be possible to give "#RRGGBB" type of color values.
3365 ;; Together with a `rst-level-face-end-light' this could be used for
3366 ;; computing steps.
3367 ;; FIXME: This variable should be combined with `rst-level-face-format-light'
3368 ;; to a single string.
3370 "Base name of the color for creating background colors in section title faces."
3374 ;; FIXME LEVEL-FACE: This needs to be done differently: The faces must specify
3375 ;; how they behave for dark and light background using the
3376 ;; relevant options explained in `defface'.
3379 15
3381 "The lightness factor for the base color. This value is used for level 1.
3382 The default depends on whether the value of `frame-background-mode' is
3383 `dark' or not."
3388 "The format for the lightness factor appended to the base name of the color.
3389 This value is expanded by `format' with an integer."
3393 ;; FIXME LEVEL-FACE: This needs to be done differently: The faces must specify
3394 ;; how they behave for dark and light background using the
3395 ;; relevant options explained in `defface'.
3396 ;; FIXME: Alternatively there could be a customizable variable
3397 ;; `rst-level-face-end-light' which defines the end value and steps are
3398 ;; computed
3401 7
3403 "The step width to use for the next color.
3404 The formula
3406 `rst-level-face-base-light'
3407 + (`rst-level-face-max' - 1) * `rst-level-face-step-light'
3409 must result in a color level which appended to `rst-level-face-base-color'
3410 using `rst-level-face-format-light' results in a valid color such as `grey50'.
3411 This color is used as background for section title text on level
3412 `rst-level-face-max'."
3418 ;; FIXME LEVEL-FACE: Must be redone if `rst-level-face-max' is changed
3423 ;; FIXME: why not `push'?
3426 alist)
3427 "Faces for the various adornment types.
3428 Key is a number (for the section title text of that level
3429 starting with 1), t (for transitions) or nil (for section title
3430 adornment). If you generally do not like how section title text
3431 faces are set up tweak here. If the general idea is ok for you
3432 but you do not like the details check the Rst Faces Defaults
3433 group."
3436 :key-type
3445 "Define the faces for the section title text faces from the values."
3446 ;; All variables used here must be checked in `rst-set-level-default'.
3451 This symbol is *not* meant for customization but modified if a
3452 variable of the `rst-faces-defaults' group is customized. Use
3455 rst-level-face-base-color
3457 rst-level-face-base-light))))
3464 ;; FIXME LEVEL-FACE: This is probably superfluous since it is done by the
3465 ;; customization / `rst-set-level-default'.
3468 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3471 ;; The reST-links in the comments below all relate to sections in
3472 ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
3474 ;; start.
3476 ;; Simple `Body Elements`_
3477 ;; `Bullet Lists`_
3478 ;; FIXME: A bullet directly after a field name is not recognized.
3481 ;; `Enumerated Lists`_
3484 ;; `Definition Lists`_
3485 ;; FIXME: missing.
3486 ;; `Field Lists`_
3489 ;; `Option Lists`_
3493 ;; `Line Blocks`_
3494 ;; Only for lines containing no more bar - to distinguish from tables.
3498 ;; `Tables`_
3499 ;; FIXME: missing
3501 ;; All the `Explicit Markup Blocks`_
3502 ;; `Footnotes`_ / `Citations`_
3506 ;; `Directives`_ / `Substitution Definitions`_
3511 ;; `Hyperlink Targets`_
3521 ;; All `Inline Markup`_
3522 ;; Most of them may be multiline though this is uninteresting.
3524 ;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented
3525 ;; `Strong Emphasis`_.
3528 ;; `Emphasis`_
3531 ;; `Inline Literals`_
3534 ;; `Inline Internal Targets`_
3537 ;; `Hyperlink References`_
3538 ;; FIXME: `Embedded URIs`_ not considered.
3539 ;; FIXME: Directly adjacent marked up words are not fontified correctly
3540 ;; unless they are not separated by two spaces: foo_ bar_.
3545 ;; `Interpreted Text`_
3552 ;; `Footnote References`_ / `Citation References`_
3555 ;; `Substitution References`_
3556 ;; FIXME: References substitutions like |this|_ or |this|__ are not
3557 ;; fontified correctly.
3560 ;; `Standalone Hyperlinks`_
3561 ;; FIXME: This takes it easy by using a whitespace as delimiter.
3567 ;; Do all block fontification as late as possible so 'append works.
3569 ;; Sections_ / Transitions_
3570 ;; For sections this is multiline.
3575 nil
3581 ;; FIXME: FACESPEC could be used instead of ordinary faces to set
3582 ;; properties on comments and literal blocks so they are *not*
3583 ;; inline fontified. See (elisp)Search-based Fontification.
3585 ;; FIXME: And / or use `syntax-propertize` functions as in `octave-mod.el`
3586 ;; and other V24 modes. May make `font-lock-extend-region`
3587 ;; superfluous.
3589 ;; `Comments`_
3590 ;; This is multiline.
3595 nil
3602 nil
3605 ;; FIXME: This is not rendered as comment::
3606 ;; .. .. list-table::
3607 ;; :stub-columns: 1
3608 ;; :header-rows: 1
3610 ;; FIXME: This is rendered wrong::
3611 ;;
3612 ;; xxx yyy::
3613 ;;
3614 ;; ----|> KKKKK <|----
3615 ;; / \
3616 ;; -|> AAAAAAAAAAPPPPPP <|- -|> AAAAAAAAAABBBBBBB <|-
3617 ;; | | | |
3618 ;; | | | |
3619 ;; PPPPPP PPPPPPDDDDDDD BBBBBBB PPPPPPBBBBBBB
3620 ;;
3621 ;; Indentation needs to be taken from the line with the ``::`` and not from
3622 ;; the first content line.
3624 ;; `Indented Literal Blocks`_
3625 ;; This is multiline.
3630 nil
3633 ;; FIXME: `Quoted Literal Blocks`_ missing.
3634 ;; This is multiline.
3636 ;; `Doctest Blocks`_
3637 ;; FIXME: This is wrong according to the specification:
3638 ;;
3639 ;; Doctest blocks are text blocks which begin with ">>> ", the Python
3640 ;; interactive interpreter main prompt, and end with a blank line.
3641 ;; Doctest blocks are treated as a special case of literal blocks,
3642 ;; without requiring the literal block syntax. If both are present, the
3643 ;; literal block syntax takes priority over Doctest block syntax:
3644 ;;
3645 ;; This is an ordinary paragraph.
3646 ;;
3647 ;; >>> print 'this is a Doctest block'
3648 ;; this is a Doctest block
3649 ;;
3650 ;; The following is a literal block::
3651 ;;
3652 ;; >>> This is not recognized as a doctest block by
3653 ;; reStructuredText. It *will* be recognized by the doctest
3654 ;; module, though!
3655 ;;
3656 ;; Indentation is not required for doctest blocks.
3660 )
3667 "Extend the font-lock region if it might be in a multi-line construct.
3668 Return non-nil if so. Font-lock region is from `font-lock-beg'
3669 to `font-lock-end'."
3674 t)))
3677 "Check the region BEG / END for being in the middle of a multi-line construct.
3678 Return nil if not or a cons with new values for BEG / END"
3685 "Like `forward-line' but always end up in column 0 and return accordingly.
3686 Move N lines forward just as `forward-line'."
3689 moved
3693 ;; FIXME: If a single line is made a section header by `rst-adjust' the header
3694 ;; is not always fontified immediately.
3696 "Extend the region starting at point PT and extending in direction DIR.
3697 Return extended point or nil if not moved."
3698 ;; There are many potential multiline constructs but there are two groups
3699 ;; which are really relevant. The first group consists of
3700 ;;
3701 ;; * comment lines without leading explicit markup tag and
3702 ;;
3703 ;; * literal blocks following "::"
3704 ;;
3705 ;; which are both indented. Thus indentation is the first thing recognized
3706 ;; here. The second criteria is an explicit markup tag which may be a comment
3707 ;; or a double colon at the end of a line.
3708 ;;
3709 ;; The second group consists of the adornment cases.
3711 ;; Move only if we don't start inside a multiline construct already.
3714 ;; block tag.
3718 ;; The comments below are for dir == -1 / dir == 1.
3724 ; line if it exists.
3726 ; overline.
3729 ; underline / overline
3730 ; found.
3734 ; overline /
3735 ; underline.
3737 ; / adornment.
3744 ; underline.
3749 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3750 ;; Indented blocks
3753 "Move forward across one indented block.
3754 Find the next non-empty line which is not indented at least to COLUMN (defaults
3755 to the column of the point). Moves point to first character of this line or the
3756 first empty line immediately before it and returns that position. If there is
3757 no such line before LIMIT (defaults to the end of the buffer) returns nil and
3758 point is not moved."
3762 fnd beg cand)
3773 ;; FIXME: No indentation [(zerop clm)] must be handled in some
3774 ;; useful way - though it is not clear what this should mean
3775 ;; at all.
3782 fnd))
3788 "End of the match as determined by `rst-font-lock-find-unindented-line-limit'.
3789 Also used as a trigger for
3793 "Find the next unindented line relative to indentation at IND-PNT.
3794 Return this point, the end of the buffer or nil if nothing found.
3795 If IND-PNT is `next' take the indentation from the next line if
3796 this is not empty and indented more than the current one. If
3797 IND-PNT is non-nil but not a number take the indentation from the
3798 next non-empty line if this is indented more than the current
3799 one."
3804 ;; Find indentation point in next line if any.
3806 ;; FIXME: Should be refactored to two different functions
3807 ;; giving their result to this function, may be
3808 ;; integrated in caller.
3814 ;; Not at EOF.
3819 ;; Use end of indentation if non-empty line.
3822 ;; Skip until non-empty line or EOF.
3827 ;; Not at EOF.
3831 ;; Indentation bigger than line of departure.
3840 "Set the match found earlier if match were found.
3841 Match has been found by
3842 `rst-font-lock-find-unindented-line-limit' the first time called
3843 or no match is found. Return non-nil if match was found. LIMIT
3844 is not used but mandated by the caller."
3848 rst-font-lock-find-unindented-line-end))
3850 rst-font-lock-find-unindented-line-end
3852 ;; Make sure this is called only once.
3854 t))
3856 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3857 ;; Adornments
3860 "Storage for `rst-font-lock-handle-adornment-matcher'.
3864 "Return section level for adornment KEY.
3865 KEY is the first element of the return list of
3866 `rst-classify-adornment'. If KEY is not a cons return it. If KEY is found
3867 in the hierarchy return its level. Otherwise return a level one
3868 beyond the existing hierarchy."
3870 key
3883 "Storage for match for current adornment.
3884 Set by `rst-font-lock-handle-adornment-pre-match-form'. Also used
3888 "Determine limit for adornments.
3889 Determine all things necessary for font-locking section titles
3890 and transitions and put the result to
3891 `rst-font-lock-adornment-match' and
3892 `rst-font-lock-adornment-level'. ADO is the complete adornment
3893 matched. ADO-END is the point where ADO ends. Return the point
3894 where the whole adorned construct ends.
3896 Called as a PRE-MATCH-FORM in the sense of `font-lock-keywords'."
3900 rst-font-lock-adornment-match nil)
3908 "Set the match found earlier if match were found.
3909 Match has been found by
3910 `rst-font-lock-handle-adornment-pre-match-form' the first time
3911 called or no match is found. Return non-nil if match was found.
3913 Called as a MATCHER in the sense of `font-lock-keywords'.
3914 LIMIT is not used but mandated by the caller."
3916 ;; May run only once - enforce this.
3923 t)))
3925 \f
3926 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3927 ;; Compilation
3930 "Settings for support of conversion of reStructuredText
3952 "Table describing the command to use for each tool-set.
3953 An association list of the tool-set to a list of the (command to use,
3954 extension of produced filename, options to the tool (nil or a
3955 string)) to be used for converting the document."
3956 ;; FIXME: These are not options but symbols which may be referenced by
3957 ;; `rst-compile-*-toolset` below.
3959 :key-type symbol
3969 ;; FIXME: Must be `defcustom`.
3973 ;; FIXME: Must be `defcustom`.
3978 "Look for the configuration file in the parents of the current path."
3982 ;; Move up in the dir hierarchy till we find a change log file.
3987 nil)
3989 ;; Move up to the parent dir and try again.
3994 )
3996 )))
4002 "Compile command to convert reST document into some output file.
4003 Attempts to find configuration file, if it can, overrides the
4004 options. There are two commands to choose from, with USE-ALT,
4005 select the alternative tool-set."
4007 ;; Note: maybe we want to check if there is a Makefile too and not do anything
4008 ;; if that is the case. I dunno.
4010 rst-compile-secondary-toolset
4011 rst-compile-primary-toolset)
4012 rst-compile-toolsets)))
4020 ;; Set compile-command before invocation of compile.
4032 ;; Invoke the compile command.
4036 ))
4039 "Compile command with the alternative tool-set."
4044 "Show pseudo-XML rendering.
4045 Rendering is done of the current active region, or of the entire
4046 buffer, if the region is not selected."
4047 ;; FIXME: The region should be given interactively.
4054 standard-output)))
4056 ;; FIXME: Should be `defcustom`.
4061 "Convert the document to a PDF file and launch a preview program."
4066 buffer-file-name tmp-filename
4067 rst-pdf-program tmp-filename tmp-filename)))
4069 ;; Note: you could also use (compile command) to view the compilation
4070 ;; output.
4071 ))
4073 ;; FIXME: Should be `defcustom` or use something like `browse-url`.
4078 "Convert the document to an S5 slide presentation and launch a preview program."
4083 buffer-file-name tmp-filename
4084 rst-slides-program tmp-filename tmp-filename)))
4086 ;; Note: you could also use (compile command) to view the compilation
4087 ;; output.
4088 ))
4090 \f
4091 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
4092 ;; Generic text functions that are more convenient than the defaults.
4094 ;; FIXME: Unbound command - should be bound or removed.
4096 "Replace flush-left lines of FROMCHAR with equal-length lines of TOCHAR."
4098 cSearch for flush-left lines of char:
4111 ;; FIXME: Unbound command - should be bound or removed.
4113 "Join lines in current paragraph into one line, removing end-of-lines."
4118 ;; FIXME: Unbound command - should be bound or removed.
4120 "Fill paragraph at point, first joining the paragraph's lines into one.
4121 This is useful for filling list item paragraphs."
4127 ;; FIXME: Unbound command - should be bound or removed.
4128 ;; Generic character repeater function.
4129 ;; For sections, better to use the specialized function above, but this can
4130 ;; be useful for creating separators.
4132 "Fill the current line using the last character on the current line.
4133 Fill up to the length of the preceding line or up to
4134 `fill-column' if preceding line is empty.
4136 If USE-NEXT, use the next line rather than the preceding line.
4138 If the current line is longer than the desired length, shave the characters off
4139 the current line to fit the desired length.
4141 As an added convenience, if the command is repeated immediately, the alternative
4142 column is used (fill-column vs. end of previous/next line)."
4149 fill-column
4161 )) )
4164 ;; Shave characters off the end.
4168 ;; Fill with last characters.
4171 ))
4175 "Return non-nil if the mark is active.
4176 This is a portable function."
4182 \f
4184 ;; LocalWords: docutils http sourceforge rst html wp svn svnroot txt reST regex
4185 ;; LocalWords: regexes alist seq alt grp keymap abbrev overline overlines toc
4186 ;; LocalWords: XML PNT propertized
4188 ;; Local Variables:
4189 ;; sentence-end-double-space: t
4190 ;; End:
4194 ;;; rst.el ends here