| blob | 1a7efd9d6178d65881069c94a498b4ccc78a3a84 |
1 ;;; rst.el --- Mode for viewing and editing reStructuredText-documents.
3 ;; Copyright (C) 2003-2015 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 init 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: Check through major mode conventions again.
108 ;; FIXME: Add proper ";;;###autoload" comments.
110 ;; FIXME: When 24.1 is common place remove use of `lexical-let' and put "-*-
111 ;; lexical-binding: t -*-" in the first line.
113 ;; FIXME: Use `testcover'.
115 ;; FIXME: The adornment classification often called `ado' should be a
116 ;; `defstruct'.
118 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
119 ;; Support for `testcover'
123 ;; Below `lambda' is used in a loop with varying parameters and is thus not
124 ;; 1valued.
130 "Remove all customized variables from `testcover-module-constants'.
131 This seems to be a bug in `testcover': `defcustom' variables are
132 considered constants. Revert it with this function after each `defcustom'."
139 sym))
140 testcover-module-constants)))))
143 "Add FUN to `testcover-compose-functions'."
148 "Add FUN to `testcover-1value-functions'."
152 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
153 ;; Common Lisp stuff
155 ;; Only use of macros is allowed - may be replaced by `cl-lib' some time.
159 ;; Redefine some functions from `cl.el' in a proper namespace until they may be
160 ;; used from there.
163 "Return 1 if X is positive, -1 if negative, 0 if zero."
170 "Return non-nil if any element of SEQ yields non-nil when PRED is applied.
171 Apply PRED to each element of list SEQ until the first non-nil
172 result is yielded and return this result. PRED defaults to
173 `identity'."
183 "Return position of first element satisfying PRED in list SEQ or nil."
192 "Return position of ELEM in list SEQ or nil.
193 Comparison done with `equal'."
194 ;; Create a closure containing `elem' so the `lambda' always sees our
195 ;; parameter instead of an `elem' which may be in dynamic scope at the time
196 ;; of execution of the `lambda'.
200 seq)))
202 ;; FIXME: Embed complicated `defconst's in `eval-when-compile'.
204 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
205 ;; Versions
207 ;; testcover: ok.
209 "Extract the version from a variable according to the given regexes.
210 Return the version after regex DELIM-RE and HEAD-RE matching RE
211 and before TAIL-RE and DELIM-RE in VAR or DEFAULT for no match."
214 var)
216 default))
218 ;; Use CVSHeader to really get information from CVS and not other version
219 ;; control systems.
232 ;; Use LastChanged... to really get information from SVN.
236 "The SVN revision of this file.
243 ;; Maintained by the release process.
255 rst-official-version
257 rst-cvs-rev rst-cvs-timestamp))
258 "The version string.
259 Starts with the current official version. For developer versions
272 ))
276 rst-version))
281 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
282 ;; Initialize customization
284 \f
290 \f
291 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
292 ;; Facilities for regular expressions used everywhere
294 ;; The trailing numbers in the names give the number of referenceable regex
295 ;; groups contained in the regex.
297 ;; Used to be customizable but really is not customizable but fixed by the reST
298 ;; syntax.
300 ;; Sorted so they can form a character class when concatenated.
311 ;; Sorted so they can form a character class when concatenated.
315 ?-)
319 1000
323 ;; `*-beg' matches * at the beginning of a line.
324 ;; `*-end' matches * at the end of a line.
325 ;; `*-prt' matches a part of *.
326 ;; `*-tag' matches *.
327 ;; `*-sta' matches the start of * which may be followed by respective content.
328 ;; `*-pfx' matches the delimiter left of *.
329 ;; `*-sfx' matches the delimiter right of *.
330 ;; `*-hlp' helper for *.
331 ;;
332 ;; A trailing number says how many referenceable groups are contained.
333 `(
335 ;; Horizontal white space (`hws')
340 ;; Lines (`lin')
345 ;; Various tags and parts
356 ;; Block lead in (`bli')
358 ; immediate content.
360 ;; Various starts
363 ;; Explicit markup tag (`exm')
368 ;; Counters in enumerations (`cnt')
372 ;; Enumerator (`enm')
379 ; enumerator.
386 ; at the beginning of a line.
388 ;; Items may be enumerated or bulleted (`itm')
391 ; is the item tag.
393 ; beginning of a line, group is the
394 ; item tag.
396 ;; Inline markup (`ilm')
400 ;; Inline markup content (`ilc')
405 ; definition.
408 ; definition.
414 (:seq ilcsgl-tag
415 ilcast-prt ilcrep-hlp
418 (:seq ilcsgl-tag
419 ilcbkq-prt ilcrep-hlp
422 (:seq ilcsgl-tag
423 ilcbkqdef-prt ilcrep-hlp
426 (:seq ilcsgl-tag
427 ilcbar-prt ilcrep-hlp
430 (:seq ilcsgl-tag
431 ilcbardef-prt ilcrep-hlp
434 ;; Fields (`fld')
439 ;; Options (`opt')
446 ;; Footnotes and citations (`fnc')
452 ; tag. First group is the explicit markup
453 ; start, second group is the footnote /
454 ; citation tag.
456 ; definition. First group is the explicit
457 ; markup start, second group is the
458 ; footnote / citation tag.
460 ;; Substitutions (`sub')
463 ; tag.
465 ;; Symbol (`sym')
469 ;; URIs (`uri')
472 ;; Adornment (`ado')
475 ; otherwise explicit markup start would be
476 ; recognized.
478 ; characters is matched differently.
481 ; adornment character and MUST be the FIRST
482 ; group in the whole expression.
485 ; adornment character and MUST be the
486 ; SECOND group in the whole expression.
489 ; adornment and MUST be the FIRST group in the whole
490 ; expression; second group is the first adornment
491 ; character.
493 ;; Titles (`ttl')
497 ;; Directives and substitution definitions (`dir')
501 ; tag. First group is explicit markup
502 ; start, second group is a possibly
503 ; empty substitution tag, third group is
504 ; the directive tag including the double
505 ; colon.
507 ; definition. Groups are as in dir-tag-3.
509 ;; Literal block (`lit')
512 ; any text before the double colon tag which
513 ; may not exist, second group is the double
514 ; colon tag.
516 ;; Comments (`cmt')
520 ; start.
522 ;; Paragraphs (`par')
525 ; certain cases.
526 )
527 "Definition alist of relevant regexes.
528 Each entry consists of the symbol naming the regex and an
533 ;; FIXME: Use `sregex' or `rx' instead of re-inventing the wheel.
535 ;; testcover: ok.
537 "Interpret ARGS as regular expressions and return a regex string.
538 Each element of ARGS may be one of the following:
540 A string which is inserted unchanged.
542 A character which is resolved to a quoted regex.
544 A symbol which is resolved to a string using `rst-re-alist-def'.
546 A list with a keyword in the car. Each element of the cdr of such
547 a list is recursively interpreted as ARGS. The results of this
548 interpretation are concatenated according to the keyword.
550 For the keyword `:seq' the results are simply concatenated.
552 For the keyword `:shy' the results are concatenated and
558 For the keyword `:grp' the results are concatenated and form a
561 After interpretation of ARGS the results are concatenated as for
562 `:seq'."
568 re)
591 args)))
593 ;; FIXME: Remove circular dependency between `rst-re' and `rst-re-alist'.
596 ;; Shadow global value we are just defining so we can construct it step by
597 ;; step.
605 \f
606 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
607 ;; Mode definition
609 ;; testcover: ok.
611 "Bind like `define-key' but add deprecated key definitions.
612 KEYMAP, KEY, and DEF are as in `define-key'. DEPRECATED key
613 definitions should be in vector notation. These are defined
614 as well but give an additional message."
634 def def)))
637 ;; Key bindings.
641 ;; \C-c is the general keymap.
644 ;;
645 ;; Section Adornments
646 ;;
647 ;; The adjustment function that adorns or rotates a section title.
650 ; on consoles.
652 ;; \C-c \C-a is the keymap for adornments.
654 ;; Another binding which works with all types of input.
656 ;; Display the hierarchy of adornments implied by the current document
657 ;; contents.
659 ;; Homogenize the adornments in the document.
663 ;;
664 ;; Section Movement and Selection
665 ;;
666 ;; Mark the subsection where the cursor is.
668 ;; Same as mark-defun sgml-mark-current-element.
670 ;; Move backward/forward between section titles.
671 ;; FIXME: Also bind similar to outline mode.
673 ;; Same as beginning-of-defun.
676 ;; Same as end-of-defun.
679 ;;
680 ;; Operating on regions
681 ;;
682 ;; \C-c \C-r is the keymap for regions.
684 ;; Makes region a line-block.
687 ;; Shift region left or right according to tabs.
691 ;;
692 ;; Operating on lists
693 ;;
694 ;; \C-c \C-l is the keymap for lists.
696 ;; Makes paragraphs in region as a bullet list.
699 ;; Makes paragraphs in region as a enumeration.
702 ;; Converts bullets to an enumeration.
705 ;; Make sure that all the bullets in the region are consistent.
708 ;; Insert a list item.
711 ;;
712 ;; Table-of-Contents Features
713 ;;
714 ;; \C-c \C-t is the keymap for table of contents.
716 ;; Enter a TOC buffer to view and move to a specific section.
718 ;; Insert a TOC here.
721 ;; Update the document's TOC (without changing the cursor position).
724 ;; Go to the section under the cursor (cursor must be in TOC).
728 ;;
729 ;; Converting Documents from Emacs
730 ;;
731 ;; \C-c \C-c is the keymap for compilation.
733 ;; Run one of two pre-configured toolset commands on the document.
738 ;; Convert the active region to pseudo-xml using the docutils tools.
741 ;; Convert the current document to PDF and launch a viewer on the results.
744 ;; Convert the current document to S5 slides and view in a web browser.
748 map)
749 "Keymap for reStructuredText mode commands.
753 ;; Abbrevs.
761 ;; FIXME: Add footnotes, links, and more.
762 ))
766 ;; Syntax table.
789 st)
793 "Hook run when `rst-mode' is turned on.
794 The hook for `text-mode' is run before this one."
799 ;; Pull in variable definitions silencing byte-compiler.
804 ;; Use rst-mode for *.rst and *.rest files. Many ReStructured-Text files
805 ;; use *.txt, but this is too generic to be set as a default.
806 ;;;###autoload (add-to-list 'auto-mode-alist (purecopy '("\\.re?st\\'" . rst-mode)))
807 ;;;###autoload
809 "Major mode for editing reStructuredText documents.
812 Turning on `rst-mode' calls the normal hooks `text-mode-hook'
813 and `rst-mode-hook'. This mode also supports font-lock
814 highlighting.
817 :abbrev-table rst-mode-abbrev-table
818 :syntax-table rst-mode-syntax-table
821 ;; Paragraph recognition.
825 lin-end)))
829 lin-end
832 ;; Indenting and filling.
840 ;; Comments.
847 ;; reStructuredText has not really a comment ender but nil is not really a
848 ;; permissible value.
852 ;; Commenting in reStructuredText is very special so use our own set of
853 ;; functions.
868 ;; Imenu and which function.
869 ;; FIXME: Check documentation of `which-function' for alternative ways to
870 ;; determine the current function name.
874 ;; Font lock.
877 t nil nil nil
882 ;; Text after a changed line may need new fontification.
885 ;; Indentation is not deterministic.
888 ;;;###autoload
890 "Toggle ReST minor mode.
891 With a prefix argument ARG, enable ReST minor mode if ARG is
892 positive, and disable it otherwise. If called from Lisp, enable
893 the mode if ARG is omitted or nil.
895 When ReST minor mode is enabled, the ReST mode keybindings
896 are installed on top of the major mode bindings. Use this
897 for modes derived from Text mode, like Mail mode."
898 ;; The initial value.
899 nil
900 ;; The indicator for the mode line.
901 " ReST"
902 ;; The minor mode bindings.
903 rst-mode-map
906 ;; FIXME: can I somehow install these too?
907 ;; :abbrev-table rst-mode-abbrev-table
908 ;; :syntax-table rst-mode-syntax-table
910 \f
911 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
912 ;; Section Adornment Adjustment
913 ;; ============================
914 ;;
915 ;; The following functions implement a smart automatic title sectioning feature.
916 ;; The idea is that with the cursor sitting on a section title, we try to get as
917 ;; much information from context and try to do the best thing automatically.
918 ;; This function can be invoked many times and/or with prefix argument to rotate
919 ;; between the various sectioning adornments.
920 ;;
921 ;; Definitions: the two forms of sectioning define semantically separate section
922 ;; levels. A sectioning ADORNMENT consists in:
923 ;;
924 ;; - a CHARACTER
925 ;;
926 ;; - a STYLE which can be either of 'simple' or 'over-and-under'.
927 ;;
928 ;; - an INDENT (meaningful for the over-and-under style only) which determines
929 ;; how many characters and over-and-under style is hanging outside of the
930 ;; title at the beginning and ending.
931 ;;
932 ;; Here are two examples of adornments (| represents the window border, column
933 ;; 0):
934 ;;
935 ;; |
936 ;; 1. char: '-' e |Some Title
937 ;; style: simple |----------
938 ;; |
939 ;; 2. char: '=' |==============
940 ;; style: over-and-under | Some Title
941 ;; indent: 2 |==============
942 ;; |
943 ;;
944 ;; Some notes:
945 ;;
946 ;; - The underlining character that is used depends on context. The file is
947 ;; scanned to find other sections and an appropriate character is selected.
948 ;; If the function is invoked on a section that is complete, the character is
949 ;; rotated among the existing section adornments.
950 ;;
951 ;; Note that when rotating the characters, if we come to the end of the
952 ;; hierarchy of adornments, the variable rst-preferred-adornments is
953 ;; consulted to propose a new underline adornment, and if continued, we cycle
954 ;; the adornments all over again. Set this variable to nil if you want to
955 ;; limit the underlining character propositions to the existing adornments in
956 ;; the file.
957 ;;
958 ;; - An underline/overline that is not extended to the column at which it should
959 ;; be hanging is dubbed INCOMPLETE. For example::
960 ;;
961 ;; |Some Title
962 ;; |-------
963 ;;
964 ;; Examples of default invocation:
965 ;;
966 ;; |Some Title ---> |Some Title
967 ;; | |----------
968 ;;
969 ;; |Some Title ---> |Some Title
970 ;; |----- |----------
971 ;;
972 ;; | |------------
973 ;; | Some Title ---> | Some Title
974 ;; | |------------
975 ;;
976 ;; In over-and-under style, when alternating the style, a variable is
977 ;; available to select how much default indent to use (it can be zero). Note
978 ;; that if the current section adornment already has an indent, we don't
979 ;; adjust it to the default, we rather use the current indent that is already
980 ;; there for adjustment (unless we cycle, in which case we use the indent
981 ;; that has been found previously).
984 "Settings for adjustment and cycling of section title adornments."
998 "Preferred hierarchy of section title adornments.
1000 A list consisting of lists of the form (CHARACTER STYLE INDENT).
1001 CHARACTER is the character used. STYLE is one of the symbols
1002 `over-and-under' or `simple'. INDENT is an integer giving the
1003 wanted indentation for STYLE `over-and-under'. CHARACTER and
1004 STYLE are always used when a section adornment is described.
1005 In other places, t instead of a list stands for a transition.
1007 This sequence is consulted to offer a new adornment suggestion
1008 when we rotate the underlines at the end of the existing
1009 hierarchy of characters, or when there is no existing section
1010 title in the file.
1012 Set this to an empty list to use only the adornment found in the
1013 file."
1021 rst-adornment-chars))
1030 "Number of characters to indent the section title.
1032 This is used for when toggling adornment styles, when switching
1033 from a simple adornment style to a over-and-under adornment
1034 style."
1040 "Compare adornments.
1041 Return true if both ADO1 and ADO2 adornments are equal,
1042 according to restructured text semantics (only the character
1043 and the style are compared, the indentation does not matter)."
1049 "Return the index (level) in hierarchy HIER of adornment ADO.
1050 This basically just searches for the item using the appropriate
1051 comparison and returns the index. Return nil if the item is
1052 not found."
1056 cur))
1058 ;; testcover: FIXME: Test with `rst-preferred-adornments' == nil. Add test
1059 ;; `rst-adjust-no-preference'.
1061 "Suggest a new, different adornment from all that have been seen.
1063 ALLADOS is the set of all adornments, including the line numbers.
1064 PREV is the optional previous adornment, in order to suggest a
1065 better match."
1067 ;; For all the preferred adornments...
1069 ;; If 'prev' is given, reorder the list to start searching after the
1070 ;; match.
1074 ;; List of candidates to search.
1077 ;; For all the adornments...
1079 found)
1082 ;; Found it!
1085 found)
1092 "Delete the entire current line without using the `kill-ring'."
1097 "Unconditionally update the style of a section adornment.
1099 Do this using the given character CHAR, with STYLE `simple'
1100 or `over-and-under', and with indent INDENT. If the STYLE
1101 is `simple', whitespace before the title is removed (indent
1102 is always assumed to be 0).
1104 If there are existing overline and/or underline from the
1105 existing adornment, they are removed before adding the
1106 requested adornment."
1109 len)
1111 ;; Fixup whitespace at the beginning and end of the line.
1121 ;; Set the current column, we're at the end of the title line.
1124 ;; Remove previous line if it is an adornment.
1127 ;; of buffer.
1129 ;; Avoid removing the underline of a title right above us.
1134 ;; Remove following line if it is an adornment.
1137 ;; of buffer.
1140 ;; Add a newline if we're at the end of the buffer, for the subsequence
1141 ;; inserting of the underline.
1145 ;; Insert overline.
1152 ;; Insert underline.
1163 "Classify adornment for section titles and transitions.
1164 ADORNMENT is the complete adornment string as found in the buffer
1165 with optional trailing whitespace. END is the point after the
1166 last character of ADORNMENT.
1168 Return a list. The first entry is t for a transition or a
1169 cons (CHARACTER . STYLE). Check `rst-preferred-adornments' for
1170 the meaning of CHARACTER and STYLE.
1172 The remaining list forms four match groups as returned by
1173 `match-data'. Match group 0 matches the whole construct. Match
1174 group 1 matches the overline adornment if present. Match group 2
1175 matches the section title text or the transition. Match group 3
1176 matches the underline adornment.
1178 Return nil if no syntactically valid adornment is found."
1193 ;; testcover: FIXME: Add test classifying at the end of
1194 ;; buffer.
1204 ;; classifying at the end of
1205 ;; buffer.
1218 ;; classifying at the end of
1219 ;; buffer.
1228 key beg-ovr end-ovr beg-txt end-txt beg-und end-und)
1231 ;; A transition.
1233 beg-txt beg-pnt
1234 end-txt end-pnt))
1236 ;; An overline with an underline.
1252 ;; An underline.
1254 beg-und beg-pnt
1255 end-und end-pnt)
1260 ;; Invalid adornment.
1266 beg-ovr end-ovr beg-txt end-txt beg-und end-und)))))))
1269 "Find a section title line around point and return its characteristics.
1270 If the point is on an adornment line find the respective title
1271 line. If the point is on an empty line check previous or next
1272 line whether it is a suitable title line and use it if so. If
1273 point is on a suitable title line use it.
1275 If no title line is found return nil.
1277 Otherwise return as `rst-classify-adornment' does. However, if
1278 the title line has no syntactically valid adornment, STYLE is nil
1279 in the first element. If there is no adornment around the title,
1280 CHARACTER is also nil and match groups for overline and underline
1281 are nil."
1294 ;; Invalid adornment - check whether this is an incomplete overline.
1301 ;; A section title - not a transition.
1302 r))))
1316 ;; Try to use the underline.
1322 r
1323 ;; No valid adornment found.
1327 ;; The following function and variables are used to maintain information about
1328 ;; current section adornment in a buffer local cache. Thus they can be used for
1329 ;; font-locking and manipulation commands.
1332 "All section adornments in the buffer as found by `rst-find-all-adornments'.
1336 ;; FIXME: If this variable is set to a different value font-locking of section
1337 ;; headers is wrong.
1339 "Section hierarchy in the buffer as determined by `rst-get-hierarchy'.
1340 Set to t when no section adornments were found.
1346 "Reset all section cache variables.
1347 Should be called by interactive functions which deal with sections."
1349 rst-section-hierarchy nil))
1352 "Return all the section adornments in the current buffer.
1353 Return a list of (LINE . ADORNMENT) with ascending LINE where
1354 LINE is the line containing the section title. ADORNMENT consists
1355 of a (CHARACTER STYLE INDENT) triple as described for
1356 `rst-preferred-adornments'.
1358 Uses and sets `rst-all-sections'."
1361 ;; Iterate over all the section titles/adornments in the file.
1375 positions)
1380 nil
1381 rst-all-sections))
1384 "Build a hierarchy of adornments using the list of given ADORNMENTS.
1386 ADORNMENTS is a list of (CHARACTER STYLE INDENT) adornment
1387 specifications, in order that they appear in a file, and will
1388 infer a hierarchy of section levels by removing adornments that
1389 have already been seen in a forward traversal of the adornments,
1390 comparing just CHARACTER and STYLE.
1392 Similarly returns a list of (CHARACTER STYLE INDENT), where each
1393 list element should be unique."
1403 "Return the hierarchy of section titles in the file.
1405 Return a list of adornments that represents the hierarchy of
1406 section titles in the file. Each element consists of (CHARACTER
1407 STYLE INDENT) as described for `rst-find-all-adornments'. If the
1408 line number in IGNORE is specified, a possibly adornment found on
1409 that line is not taken into account when building the hierarchy.
1411 Uses and sets `rst-section-hierarchy' unless IGNORE is given."
1414 nil
1415 rst-section-hierarchy)
1419 ignore
1423 ;; Clear cache reflecting that a possible update is not
1424 ;; reflected.
1425 nil
1427 r)))
1430 "Return the adornments around point.
1431 Return a list of the previous and next adornments."
1434 prev next
1437 ;; Search for the adornments around the current line.
1441 ;; 'cur' is the following adornment.
1449 "Return true if the adornment ADO around point is complete."
1450 ;; Note: we assume that the detection of the overline as being the underline
1451 ;; of a preceding title has already been detected, and has been eliminated
1452 ;; from the adornment that is given to us.
1454 ;; There is some sectioning already present, so check if the current
1455 ;; sectioning is complete and correct.
1474 "Get the next adornment for CURADO, in given hierarchy HIER.
1475 If suggesting, suggest for new adornment SUGGESTION.
1476 REVERSE-DIRECTION is used to reverse the cycling order."
1482 ;; Build a new list of adornments for the rotation.
1485 ;; Suggest a new adornment.
1487 ;; If nothing to suggest, use first adornment.
1490 ;; Search for next adornment.
1498 cur))
1500 ;; If not found, take the first of all adornments.
1501 suggestion)))
1504 ;; FIXME: A line "``/`` full" is not accepted as a section title.
1506 "Auto-adjust the adornment around point.
1508 Adjust/rotate the section adornment for the section title around
1509 point or promote/demote the adornments inside the region,
1510 depending on whether the region is active. This function is meant
1511 to be invoked possibly multiple times, and can vary its behavior
1512 with a positive PFXARG (toggle style), or with a negative
1513 PFXARG (alternate behavior).
1515 This function is a bit of a swiss knife. It is meant to adjust
1516 the adornments of a section title in reStructuredText. It tries
1520 See the documentations of `rst-adjust-adornment-work' and
1521 `rst-promote-region' for full details.
1523 Prefix Arguments
1524 ================
1526 The method can take either (but not both) of
1528 a. a (non-negative) prefix argument, which means to toggle the
1529 adornment style. Invoke with a prefix argument for example;
1531 b. a negative numerical argument, which generally inverts the
1532 direction of search in the file or hierarchy. Invoke with C--
1533 prefix for example."
1543 ;; Adjust adornments within region.
1545 ;; Adjust adornment around point.
1548 ;; Run the hooks to run after adjusting.
1551 ;; Make sure to reset the cursor position properly after we're done.
1555 "Hooks to be run after running `rst-adjust'."
1562 "Controls level of new adornment for section headers."
1571 "Call `rst-adjust-adornment-work' interactively.
1573 Keep this for compatibility for older bindings (are there any?).
1574 Argument PFXARG has the same meaning as for `rst-adjust'."
1582 "Adjust/rotate the section adornment for the section title around point.
1584 This function is meant to be invoked possibly multiple times, and
1585 can vary its behavior with a true TOGGLE-STYLE argument, or with
1586 a REVERSE-DIRECTION argument.
1588 General Behavior
1589 ================
1591 The next action it takes depends on context around the point, and
1592 it is meant to be invoked possibly more than once to rotate among
1593 the various possibilities. Basically, this function deals with:
1595 - adding a adornment if the title does not have one;
1597 - adjusting the length of the underline characters to fit a
1598 modified title;
1600 - rotating the adornment in the set of already existing
1601 sectioning adornments used in the file;
1603 - switching between simple and over-and-under styles.
1605 You should normally not have to read all the following, just
1606 invoke the method and it will do the most obvious thing that you
1607 would expect.
1610 Adornment Definitions
1611 =====================
1613 The adornments consist in
1615 1. a CHARACTER
1617 2. a STYLE which can be either `simple' or `over-and-under'.
1619 3. an INDENT (meaningful for the over-and-under style only)
1620 which determines how many characters and over-and-under
1621 style is hanging outside of the title at the beginning and
1622 ending.
1624 See source code for mode details.
1627 Detailed Behavior Description
1628 =============================
1630 Here are the gory details of the algorithm (it seems quite
1631 complicated, but really, it does the most obvious thing in all
1632 the particular cases):
1634 Before applying the adornment change, the cursor is placed on
1635 the closest line that could contain a section title.
1637 Case 1: No Adornment
1638 --------------------
1640 If the current line has no adornment around it,
1642 - search backwards for the last previous adornment, and apply
1643 the adornment one level lower to the current line. If there
1644 is no defined level below this previous adornment, we suggest
1645 the most appropriate of the `rst-preferred-adornments'.
1647 If REVERSE-DIRECTION is true, we simply use the previous
1648 adornment found directly.
1650 - if there is no adornment found in the given direction, we use
1651 the first of `rst-preferred-adornments'.
1653 TOGGLE-STYLE forces a toggle of the prescribed adornment style.
1655 Case 2: Incomplete Adornment
1656 ----------------------------
1658 If the current line does have an existing adornment, but the
1659 adornment is incomplete, that is, the underline/overline does
1660 not extend to exactly the end of the title line (it is either
1661 too short or too long), we simply extend the length of the
1662 underlines/overlines to fit exactly the section title.
1664 If TOGGLE-STYLE we toggle the style of the adornment as well.
1666 REVERSE-DIRECTION has no effect in this case.
1668 Case 3: Complete Existing Adornment
1669 -----------------------------------
1671 If the adornment is complete (i.e. the underline (overline)
1672 length is already adjusted to the end of the title line), we
1673 search/parse the file to establish the hierarchy of all the
1674 adornments (making sure not to include the adornment around
1675 point), and we rotate the current title's adornment from within
1676 that list (by default, going *down* the hierarchy that is present
1677 in the file, i.e. to a lower section level). This is meant to be
1678 used potentially multiple times, until the desired adornment is
1679 found around the title.
1681 If we hit the boundary of the hierarchy, exactly one choice from
1682 the list of preferred adornments is suggested/chosen, the first
1683 of those adornment that has not been seen in the file yet (and
1684 not including the adornment around point), and the next
1685 invocation rolls over to the other end of the hierarchy (i.e. it
1686 cycles). This allows you to avoid having to set which character
1687 to use.
1689 If REVERSE-DIRECTION is true, the effect is to change the
1690 direction of rotation in the hierarchy of adornments, thus
1691 instead going *up* the hierarchy.
1693 However, if TOGGLE-STYLE, we do not rotate the adornment, but
1694 instead simply toggle the style of the current adornment (this
1695 should be the most common way to toggle the style of an existing
1696 complete adornment).
1699 Point Location
1700 ==============
1702 The invocation of this function can be carried out anywhere
1703 within the section title line, on an existing underline or
1704 overline, as well as on an empty line following a section title.
1705 This is meant to be as convenient as possible.
1708 Indented Sections
1709 =================
1711 Indented section titles such as ::
1713 My Title
1714 --------
1716 are invalid in reStructuredText and thus not recognized by the
1717 parser. This code will thus not work in a way that would support
1718 indented sections (it would be ambiguous anyway).
1721 Joint Sections
1722 ==============
1724 Section titles that are right next to each other may not be
1725 treated well. More work might be needed to support those, and
1726 special conditions on the completeness of existing adornments
1727 might be required to make it non-ambiguous.
1729 For now we assume that the adornments are disjoint, that is,
1730 there is at least a single line between the titles/adornment
1731 lines."
1743 char-new style-new indent-new)
1745 ;;-------------------------------------------------------------------
1746 ;; Case 1: No valid adornment
1749 cur
1751 ;; Advance one level down.
1757 prev
1761 ;; Invert the style if requested.
1768 ;;-------------------------------------------------------------------
1769 ;; Case 2: Incomplete Adornment
1771 ;; Invert the style if requested.
1775 style-new style
1776 indent-new indent))
1777 ;;-------------------------------------------------------------------
1778 ;; Case 3: Complete Existing Adornment
1781 ;; Simply switch the style of the current adornment.
1784 indent-new rst-default-indent)
1785 ;; Else, we rotate, ignoring the adornment around the current
1786 ;; line...
1788 ;; Suggestion, in case we need to come up with something new.
1790 hier
1793 curado hier suggestion reverse-direction)))
1794 ;; Indent, if present, always overrides the prescribed indent.
1798 ;; Override indent with present indent!
1802 ;; Correct the position of the cursor to more accurately reflect where
1803 ;; it was located when the function was invoked.
1808 ;; Maintain an alias for compatibility.
1813 "Promote the section titles within the region.
1815 With argument DEMOTE or a prefix argument, demote the section
1816 titles instead. The algorithm used at the boundaries of the
1817 hierarchy is similar to that used by `rst-adjust-adornment-work'."
1827 marker-list)
1829 ;; Skip the markers that come before the region beginning.
1833 ;; Create a list of markers for all the adornments which are found within
1834 ;; the region.
1843 ;; Apply modifications.
1845 ;; Go to the adornment to promote.
1848 ;; Update the adornment.
1850 ;; Rotate the next adornment.
1854 ;; Clear marker to avoid slowing down the editing after we're done.
1861 "Display the current file's section title adornments hierarchy.
1862 This function expects a list of (CHARACTER STYLE INDENT) triples
1863 in ADORNMENTS."
1879 "Redo all the adornments in the current buffer.
1880 This is done using our preferred set of adornments. This can be
1881 used, for example, when using somebody else's copy of a document,
1882 in order to adapt it to our preferred style."
1897 ;; Go to the appropriate position.
1900 ;; Apply the new style.
1903 ;; Reset the marker to avoid slowing down editing until it gets GC'ed.
1906 \f
1907 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1908 ;; Insert list items
1909 ;; =================
1912 ;=================================================
1913 ; Borrowed from a2r.el (version 1.3), by Lawrence Mitchell <wence@gmx.li>.
1914 ; I needed to make some tiny changes to the functions, so I put it here.
1915 ; -- Wei-Wei Guo
1925 "Convert Arabic number NUM to its Roman numeral representation.
1927 Obviously, NUM must be greater than zero. Don't blame me, blame the
1929 apologies to Monty Python).
1930 If optional ARG is non-nil, insert in current buffer."
1932 res)
1942 "Convert STRING of Roman numerals to an Arabic number.
1944 If STRING contains a letter which isn't a valid Roman numeral,
1945 the rest of the string from that point onwards is ignored.
1947 Hence:
1948 MMD == 2500
1949 and
1950 MMDFLXXVI == 2500.
1951 If optional ARG is non-nil, insert in current buffer."
1960 ;=================================================
1963 "Find all the positions of prefixes in region between BEG and END.
1964 This is used to find bullets and enumerated list items. PFX-RE is
1965 a regular expression for matching the lines after indentation
1966 with items. Returns a list of cons cells consisting of the point
1967 and the column of the point."
1984 pfx))
1989 "Arrange relative position of a newly inserted list item of style NEWITEM.
1991 Adding a new list might consider three situations:
1993 (a) Current line is a blank line.
1994 (b) Previous line is a blank line.
1995 (c) Following line is a blank line.
1997 When (a) and (b), just add the new list at current line.
1999 when (a) and not (b), a blank line is added before adding the new list.
2001 When not (a), first forward point to the end of the line, and add two
2002 blank lines, then add the new list.
2004 Other situations are just ignored and left to users themselves."
2016 ;; FIXME: Isn't this a `defconst'?
2025 ;; FIXME: Isn't this a `defconst'?
2031 "Insert a new list item.
2033 User is asked to select the item style first, for example (a), i), +.
2034 Use TAB for completion and choices.
2036 If user selects bullets or #, it's just added with position arranged by
2037 `rst-insert-list-pos'.
2039 If user selects enumerations, a further prompt is given. User need to
2040 input a starting item, for example 'e' for 'A)' style. The position is
2041 also arranged by `rst-insert-list-pos'."
2043 ;; FIXME: Make this comply to `interactive' standards.
2045 "Select preferred item style [#.]: "
2051 ;; FIXME: Make this comply to `interactive' standards.
2076 "List of favorite bullets."
2082 rst-bullets)))
2087 "Insert a list item with list start CURITEM including its indentation level.
2088 If PREFER-ROMAN roman numbering is preferred over using letters."
2095 curitem)
2099 nil nil curitem))
2104 ;; FIXME: Assumes one line list items without separating
2105 ;; empty lines.
2122 t nil curitem))
2126 nil nil curitem)))))
2130 "Insert a list item at the current point.
2132 The command can insert a new list or a continuing list. When it is called at a
2133 non-list line, it will promote to insert new list. When it is called at a list
2134 line, it will insert a list with the same list style.
2136 1. When inserting a new list:
2138 User is asked to select the item style first, for example (a), i), +. Use TAB
2139 for completion and choices.
2141 (a) If user selects bullets or #, it's just added.
2142 (b) If user selects enumerations, a further prompt is given. User needs to
2143 input a starting item, for example `e' for `A)' style.
2145 The position of the new list is arranged according to whether or not the
2146 current line and the previous line are blank lines.
2148 2. When continuing a list, one thing needs to be noticed:
2150 List style alphabetical list, such as `a.', and roman numerical list, such as
2151 `i.', have some overlapping items, for example `v.' The function can deal with
2152 the problem elegantly in most situations. But when those overlapped list are
2153 preceded by a blank line, it is hard to determine which type to use
2154 automatically. The function uses alphabetical list by default. If you want
2155 roman numerical list, just use a prefix to set PREFER-ROMAN."
2163 "Make all the bulleted list items in the region consistent.
2164 The region is specified between BEG and END. You can use this
2165 after you have merged multiple bulleted lists to make them use
2166 the same/correct/consistent bullet characters.
2168 See variable `rst-preferred-bullets' for the list of bullets to
2169 adjust. If bullets are found on levels beyond the
2170 `rst-preferred-bullets' list, they are not modified."
2176 ;; Create a map of levels to list of positions.
2182 levtable)))
2184 ;; Sort this map and create a new map of prefix char and list of positions.
2191 ;; Apply the characters.
2198 \f
2199 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2200 ;; Table of contents
2201 ;; =================
2203 ;; FIXME: Return value should be a `defstruct'.
2205 "Return the hierarchical tree of section titles.
2206 A tree entry looks like ((TITLE MARKER) CHILD...). TITLE is the
2207 stripped text of the section title. MARKER is a marker for the
2208 beginning of the title text. For the top node or a missing
2209 section level node TITLE is nil and MARKER points to the title
2210 text of the first child. Each CHILD is another tree entry. The
2211 CHILD list may be empty."
2214 lev-ttl-mrk-l)
2218 ;; Compare just the character and indent in the hash table.
2222 ;; Create a list that contains (LEVEL TITLE MARKER) for each adornment.
2230 ;; Get title.
2241 ;; FIXME: Return value should be a `defstruct'.
2243 "Process the first entry of REMAINING expected to be on level LEV.
2244 REMAINING is the remaining list of adornments consisting
2245 of (LEVEL TITLE MARKER) entries.
2247 Return (UNPROCESSED (TITLE MARKER) CHILD...) for the first entry
2248 of REMAINING where TITLE is nil if the expected level is not
2249 matched. UNPROCESSED is the list of still unprocessed entries.
2250 Each CHILD is a child of this entry in the same format but
2251 without UNPROCESSED."
2254 ttl-mrk children)
2255 ;; If the current adornment matches expected level.
2257 ;; Consume the current entry and create the current node with it.
2261 ;; Build the child nodes as long as they have deeper level.
2270 ;; Node on this level missing - use nil as text and the
2271 ;; marker of the first child.
2273 children))))
2276 "Return section containing POINT by returning the closest node in TREE.
2277 TREE is a section tree as returned by `rst-section-tree'
2278 consisting of (NODE CHILD...) entries. POINT defaults to the
2279 current point. A NODE must have the structure (IGNORED MARKER...).
2281 Return (PATH NODE CHILD...). NODE is the node where POINT is in
2282 if any. PATH is a list of nodes from the top of the tree down to
2283 and including NODE. List of CHILD are the children of NODE if any."
2287 ;; Point behind current node?
2289 ;; Iterate all the children, looking for one that might contain the
2290 ;; current section.
2296 ;; Found section containing point in children.
2298 ;; Extend path with current node and return NODE CHILD... from
2299 ;; sub.
2301 ;; Point in this section: Start a new path with current node and
2302 ;; return current NODE CHILD...
2304 ;; Current node behind point: start a new path with current node and
2305 ;; no NODE CHILD...
2309 "Settings for reStructuredText table of contents."
2314 "Indentation for table-of-contents display.
2315 Also used for formatting insertion, when numbering is disabled."
2321 "Insertion style for table-of-contents.
2322 Set this to one of the following values to determine numbering and
2323 indentation style:
2324 - `plain': no numbering (fixed indentation)
2325 - `fixed': numbering, but fixed indentation
2326 - `aligned': numbering, titles aligned under each other
2327 - `listed': numbering, with dashes like list items (EXPERIMENTAL)"
2336 "Separator that goes between the TOC number and the title."
2341 ;; This is used to avoid having to change the user's mode.
2345 map)
2349 "If non-nil, maximum depth of the inserted TOC."
2355 "Insert a simple text rendering of the table of contents.
2356 By default the top level is ignored if there is only one, because
2357 we assume that the document will have a single title.
2359 If a numeric prefix argument PFXARG is given, insert the TOC up
2360 to the specified level.
2362 The TOC is inserted indented at the current column."
2370 ;; Get the section tree for the current cursor point.
2375 ;; Figure out initial indent.
2382 ;; Fixup for the first line.
2385 ;; Delete the last newline added.
2389 "Insert tree node NODE in table-of-contents.
2390 Recursive function that does printing of the inserted TOC.
2391 LEVEL is the depth level of the sections in the tree.
2392 INDENT is the indentation string. PFX is the prefix numbering,
2393 that includes the alignment necessary for all the children of
2394 level to align."
2396 ;; Note: we do child numbering from the parent, so we start number the
2397 ;; children one level before we print them.
2406 ;; Add properties to the text, even though in normal text mode it
2407 ;; won't be doing anything for now. Not sure that I want to change
2408 ;; mode stuff. At least the highlighting gives the idea that this
2409 ;; is generated automatically.
2415 ;; Prepare indent for children.
2434 fmt)
2437 ;; Add a separating dot if there is already a prefix.
2442 ;; Calculate the amount of space that the prefix will require
2443 ;; for the numbers.
2452 indent
2459 "Automatically find the contents section of a document and update.
2460 Updates the inserted TOC if present. You can use this in your
2461 file-write hook to always make it up-to-date automatically."
2464 ;; Find and delete an existing comment after the first contents directive.
2465 ;; Delete that region.
2467 ;; We look for the following and the following only (in other words, if your
2468 ;; syntax differs, this won't work.).
2469 ;;
2470 ;; .. contents:: [...anything here...]
2471 ;; [:field: value]...
2472 ;; ..
2473 ;; XXXXXXXX
2474 ;; XXXXXXXX
2475 ;; [more lines]
2479 last-real)
2481 ;; Look for the first line that starts at the first column.
2498 ;; Note: always return nil, because this may be used as a hook.
2499 nil)
2501 ;; Note: we cannot bind the TOC update on file write because it messes with
2502 ;; undo. If we disable undo, since it adds and removes characters, the
2503 ;; positions in the undo list are not making sense anymore. Dunno what to do
2504 ;; with this, it would be nice to update when saving.
2505 ;;
2506 ;; (add-hook 'write-contents-hooks 'rst-toc-update-fun)
2507 ;; (defun rst-toc-update-fun ()
2508 ;; ;; Disable undo for the write file hook.
2509 ;; (let ((buffer-undo-list t)) (rst-toc-update) ))
2513 ;;------------------------------------------------------------------------------
2516 "Recursive function that does insert NODE at LEVEL in the table-of-contents."
2520 ;; Insert line text.
2524 ;; Highlight lines.
2527 ;; Add link on lines.
2536 "Count the number of lines from NODE to the TARGET-NODE node.
2537 This recursive function returns a cons of the number of
2538 additional lines that have been counted for its node and
2539 children, and t if the node has been found."
2542 found)
2561 "Display a table-of-contents.
2562 Finds all the section titles and their adornments in the
2563 file, and displays a hierarchically-organized list of the
2564 titles, which is essentially a table-of-contents of the
2565 document.
2567 The Emacs buffer can be navigated, and selecting a section
2568 brings the cursor in that section."
2575 line
2577 ;; Create a temporary buffer.
2589 ;; Count the lines to our found node.
2595 ;; Save the buffer to return to.
2598 ;; Move the cursor near the right section in the TOC.
2604 "Get the section from text property at point."
2610 pos))
2612 ;; FIXME: Cursor before or behind the list must be handled properly; before the
2613 ;; list should jump to the top and behind the list to the last normal
2614 ;; paragraph.
2616 "Go to the section the current line describes.
2617 If KILL a TOC buffer is destroyed."
2621 ;; FIXME: This should rather go to `rst-toc-mode-goto-section'.
2626 ;; FIXME: make the recentering conditional on scroll.
2630 "Go to the section the current line describes and kill the TOC buffer."
2635 "In `rst-toc' mode, go to the occurrence whose line you click on.
2636 EVENT is the input event."
2648 "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well.
2649 EVENT is the input event."
2655 "Leave the current TOC buffer."
2669 map)
2674 ;; Could inherit from the new `special-mode'.
2679 ;; Note: use occur-mode (replace.el) as a good example to complete missing
2680 ;; features.
2682 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2683 ;; Section movement commands
2684 ;; =========================
2687 "Skip to the next reStructuredText section title.
2688 OFFSET specifies how many titles to skip. Use a negative OFFSET
2689 to move backwards in the file (default is to use 1)."
2695 ;; Get all the adornments in the file, with their line numbers.
2698 ;; Get the current line.
2704 ;; Find the index of the "next" adornment w.r.t. to the current line.
2708 ;; 'cur' is the adornment on or following the current line.
2713 ;; Find the final index.
2717 ;; If the index is positive, goto the line, otherwise go to the buffer
2718 ;; boundaries.
2726 "Like `rst-forward-section', except move back one title."
2730 ;; FIXME: What is `allow-extend' for?
2732 "Select COUNT sections around point.
2733 Mark following sections for positive COUNT or preceding sections
2734 for negative COUNT."
2735 ;; Cloned from mark-paragraph.
2753 \f
2754 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2755 ;; Indentation
2758 "Return the leftmost column spanned by region BEG to END.
2759 The line containing the start of the region is always considered
2760 spanned. If the region ends at the beginning of a line this line
2761 is not considered spanned, otherwise it is spanned."
2772 mincol))
2774 ;; FIXME: At the moment only block comments with leading empty comment line are
2775 ;; supported. Comment lines with leading comment markup should be also
2776 ;; supported. May be a customizable option could control which style to
2777 ;; prefer.
2781 In reStructuredText indentation points are usually determined by
2782 preceding lines. Sometimes the syntax allows arbitrary indentation
2783 points such as where to start the first line following a directive.
2784 These indentation widths can be customized here."
2791 "Indentation when there is no more indentation point given."
2797 "Indentation for first line after a field or 0 to always indent for content."
2804 "Default indentation for literal block after a markup on an own line."
2811 "Default indentation for literal block after a minimized markup."
2818 "Default indentation for first line of a comment."
2824 ;; FIXME: Must consider other tabs:
2825 ;; * Line blocks
2826 ;; * Definition lists
2827 ;; * Option lists
2829 "Return tabs of the current line or nil for no tab.
2830 The list is sorted so the tab where writing continues most likely
2831 is the first one. Each tab is of the form (COLUMN . INNER).
2832 COLUMN is the column of the tab. INNER is non-nil if this is an
2833 inner tab. I.e. a tab which does come from the basic indentation
2834 and not from inner alignment points."
2840 ;; Current indentation is always the least likely tab.
2842 ;; Push inner tabs more likely to continue writing.
2844 ;; Item.
2848 ;; Field.
2859 ;; Directive.
2866 ;; Footnote or citation definition.
2871 ;; Comment.
2874 ;; Start of literal block.
2880 rst-indent-literal-minimized
2881 rst-indent-literal-normal))
2886 tabs))))))
2889 "Build the list of possible tabs for all lines above.
2890 Search backwards from point PT to build the list of possible tabs.
2891 Return a list of tabs sorted by likeliness to continue writing
2892 like `rst-line-tabs'. Nearer lines have generally a higher
2893 likeliness than farther lines. Return nil if no tab is found in
2894 the text above."
2898 innermost ; Leftmost column for inner tab.
2899 tablist)
2906 ;; Consider only lines indented less or same if not INNERMOST.
2924 leftcol
2925 innermost))
2930 "Indent current line to next best reStructuredText tab.
2931 The next best tab is taken from the tab list returned by
2932 `rst-compute-tabs' which is used in a cyclic manner. If the
2933 current indentation does not end on a tab use the first one. If
2934 the current indentation is on a tab use the next tab. This allows
2936 possible tabs. If no indentation is possible return `noindent' or
2937 use DFLT. Return the indentation indented to. When point is in
2938 indentation it ends up at its end. Otherwise the point is kept
2939 relative to the content."
2945 ind)
2947 'noindent
2960 ind)))
2963 "Shift region BEG to END by CNT tabs.
2964 Shift by one tab to the right (CNT > 0) or left (CNT < 0) or
2965 remove all indentation (CNT = 0). A tab is taken from the text
2966 above. If no suitable tab is found `rst-indent-width' is used."
2971 ;; Apply the indent.
2973 beg end
2976 ;; Find the next tab after the leftmost column.
2982 ;; Get the position of the first tab beyond leftmostcol.
2987 tabs)))
2988 ;; Virtual position of tab.
2991 ;; Tab exists - use it.
2993 ;; Column needs to be computed.
2995 ;; Base on last known column.
2997 dir ; Direction to take.
2998 rst-indent-width))))
3002 ;; FIXME: A paragraph with an (incorrectly) indented second line is not filled
3003 ;; correctly::
3004 ;;
3005 ;; Some start
3006 ;; continued wrong
3008 "Return fill prefix found at point.
3009 Value for `adaptive-fill-function'."
3014 ;; An non-comment prefix is fine.
3015 fnd
3016 ;; Matches a comment - return whitespace instead.
3025 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3026 ;; Comments
3029 "Break line and indent, continuing reStructuredText comment if within one.
3030 Value for `comment-line-break-function'. If SOFT use soft
3031 newlines as mandated by `comment-line-break-function'."
3044 "Return indentation for current comment line."
3048 "Insert a comment in the current line."
3053 "Comment or uncomment the current region.
3054 Region is from BEG to END. Uncomment if ARG."
3060 bol)
3070 "Uncomment the current region.
3071 Region is from BEG to END. ARG is ignored"
3082 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3083 ;; Apply to indented block
3085 ;; FIXME: These next functions should become part of a larger effort to redo
3086 ;; the bullets in bulleted lists. The enumerate would just be one of
3087 ;; the possible outputs.
3088 ;;
3089 ;; FIXME: We need to do the enumeration removal as well.
3092 "Apply FUN to all lines from BEG to END in blocks indented to IND.
3093 The first indented block starts with the first non-empty line
3094 containing or after BEG and indented to IND. After the first
3095 line the indented block may contain more lines with same
3096 indentation (the paragraph) followed by empty lines and lines
3097 more indented (the sub-blocks). A following line indented to IND
3098 starts the next indented block. A line with less indentation
3099 than IND terminates the current indented block. Such lines and
3100 all following lines not indented to IND are skipped. FUN is
3101 applied to unskipped lines like this
3103 (FUN COUNT FIRSTP SUBP EMPTYP RELIND LASTRET)
3105 COUNT is 0 before the first indented block and increments for
3106 every indented block found.
3108 FIRSTP is t when this is the first line of the paragraph.
3110 SUBP is t when this line is part of a sub-block.
3112 EMPTYP is t when this line is empty.
3114 RELIND is nil for an empty line, 0 for a line indented to IND,
3115 and the number of columns more indented otherwise.
3117 LASTRET is the return value of FUN returned by the last
3118 invocation for the same indented block or nil for the first
3119 invocation.
3121 When FUN is called point is immediately behind indentation of
3122 that line. FUN may change everything as long as a marker at END
3123 is handled correctly by the change.
3125 Return the return value of the last invocation of FUN or nil if
3126 FUN was never called."
3128 subp
3129 skipping
3130 nextm
3142 emptyp
3148 ;; Breaks indented block if one is started
3164 lastret)))
3167 "Add enumeration to all the leftmost paragraphs in the given region.
3168 The region is specified between BEG and END. With ALL,
3169 do all lines instead of just paragraphs."
3186 lastret))))
3188 ;; FIXME: Does not deal with deeper indentation - although
3189 ;; `rst-apply-indented-blocks' could.
3191 "Add bullets to all the leftmost paragraphs in the given region.
3192 The region is specified between BEG and END. With ALL,
3193 do all lines instead of just paragraphs."
3211 nil))))
3213 ;; FIXME: Does not deal with a varying number of digits appropriately.
3214 ;; FIXME: Does not deal with multiple levels independently.
3215 ;; FIXME: Does not indent a multiline item correctly.
3217 "Convert the bulleted and enumerated items in the region to enumerated lists.
3218 Renumber as necessary. Region is from BEG to END."
3235 "Add line block prefixes for a region.
3236 Region is from BEG to END. With WITH-EMPTY prefix empty lines too."
3240 beg end ind
3246 \f
3247 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3248 ;; Font lock
3249 ;; =========
3253 ;; FIXME: The obsolete variables need to disappear.
3255 ;; The following versions have been done inside Emacs and should not be
3256 ;; replaced by `:package-version' attributes until a change.
3264 "Face used for all syntax marking up a special block."
3269 "All syntax marking up a special block."
3275 "customize the face `rst-block' instead."
3279 "Face used for field names and interpreted text."
3284 "Field names and interpreted text."
3290 "customize the face `rst-external' instead."
3294 "Face used for all other defining constructs."
3299 "All other defining constructs."
3305 "customize the face `rst-definition' instead."
3308 ;; XEmacs compatibility (?).
3312 "Face used for directives and roles."
3317 "Directives and roles."
3322 "customize the face `rst-directive' instead."
3326 "Face used for comments."
3331 "Comments."
3337 "customize the face `rst-comment' instead."
3341 "Face used for simple emphasis."
3346 "Simple emphasis."
3352 "customize the face `rst-emphasis1' instead."
3356 "Face used for double emphasis."
3361 "Double emphasis."
3366 "customize the face `rst-emphasis2' instead."
3370 "Face used for literal text."
3375 "Literal text."
3381 "customize the face `rst-literal' instead."
3385 "Face used for references to a definition."
3390 "References to a definition."
3396 "customize the face `rst-reference' instead."
3400 "Face used for a transition."
3405 "Face used for the adornment of a section header."
3409 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3412 rst-level-face-base-light
3413 rst-level-face-format-light
3414 rst-level-face-step-light
3415 rst-level-1-face
3416 rst-level-2-face
3417 rst-level-3-face
3418 rst-level-4-face
3419 rst-level-5-face
3420 rst-level-6-face))
3424 ;; Define faces for the first 6 levels. More levels are possible, however.
3427 "Default face for section title text at level 1."
3432 "Default face for section title text at level 2."
3437 "Default face for section title text at level 3."
3442 "Default face for section title text at level 4."
3447 "Default face for section title text at level 5."
3452 "Default face for section title text at level 6."
3464 "Faces for the various adornment types.
3465 Key is a number (for the section title text of that level
3466 starting with 1), t (for transitions) or nil (for section title
3467 adornment). If you need levels beyond 6 you have to define faces
3468 of your own."
3471 :key-type
3479 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3482 ;; The reST-links in the comments below all relate to sections in
3483 ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
3485 ;; start.
3487 ;; Simple `Body Elements`_
3488 ;; `Bullet Lists`_
3489 ;; FIXME: A bullet directly after a field name is not recognized.
3492 ;; `Enumerated Lists`_
3495 ;; `Definition Lists`_
3496 ;; FIXME: missing.
3497 ;; `Field Lists`_
3500 ;; `Option Lists`_
3504 ;; `Line Blocks`_
3505 ;; Only for lines containing no more bar - to distinguish from tables.
3509 ;; `Tables`_
3510 ;; FIXME: missing
3512 ;; All the `Explicit Markup Blocks`_
3513 ;; `Footnotes`_ / `Citations`_
3517 ;; `Directives`_ / `Substitution Definitions`_
3522 ;; `Hyperlink Targets`_
3532 ;; All `Inline Markup`_
3533 ;; Most of them may be multiline though this is uninteresting.
3535 ;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented
3536 ;; `Strong Emphasis`_.
3539 ;; `Emphasis`_
3542 ;; `Inline Literals`_
3545 ;; `Inline Internal Targets`_
3548 ;; `Hyperlink References`_
3549 ;; FIXME: `Embedded URIs`_ not considered.
3550 ;; FIXME: Directly adjacent marked up words are not fontified correctly
3551 ;; unless they are not separated by two spaces: foo_ bar_.
3556 ;; `Interpreted Text`_
3563 ;; `Footnote References`_ / `Citation References`_
3566 ;; `Substitution References`_
3567 ;; FIXME: References substitutions like |this|_ or |this|__ are not
3568 ;; fontified correctly.
3571 ;; `Standalone Hyperlinks`_
3572 ;; FIXME: This takes it easy by using a whitespace as delimiter.
3578 ;; Do all block fontification as late as possible so 'append works.
3580 ;; Sections_ / Transitions_
3581 ;; For sections this is multiline.
3586 nil
3592 ;; FIXME: FACESPEC could be used instead of ordinary faces to set
3593 ;; properties on comments and literal blocks so they are *not*
3594 ;; inline fontified. See (elisp)Search-based Fontification.
3596 ;; FIXME: And / or use `syntax-propertize' functions as in `octave-mod.el'
3597 ;; and other V24 modes. May make `font-lock-extend-region'
3598 ;; superfluous.
3600 ;; `Comments`_
3601 ;; This is multiline.
3606 nil
3613 nil
3616 ;; FIXME: This is not rendered as comment::
3617 ;; .. .. list-table::
3618 ;; :stub-columns: 1
3619 ;; :header-rows: 1
3621 ;; FIXME: This is rendered wrong::
3622 ;;
3623 ;; xxx yyy::
3624 ;;
3625 ;; ----|> KKKKK <|----
3626 ;; / \
3627 ;; -|> AAAAAAAAAAPPPPPP <|- -|> AAAAAAAAAABBBBBBB <|-
3628 ;; | | | |
3629 ;; | | | |
3630 ;; PPPPPP PPPPPPDDDDDDD BBBBBBB PPPPPPBBBBBBB
3631 ;;
3632 ;; Indentation needs to be taken from the line with the ``::`` and not from
3633 ;; the first content line.
3635 ;; `Indented Literal Blocks`_
3636 ;; This is multiline.
3641 nil
3644 ;; FIXME: `Quoted Literal Blocks`_ missing.
3645 ;; This is multiline.
3647 ;; `Doctest Blocks`_
3648 ;; FIXME: This is wrong according to the specification:
3649 ;;
3650 ;; Doctest blocks are text blocks which begin with ">>> ", the Python
3651 ;; interactive interpreter main prompt, and end with a blank line.
3652 ;; Doctest blocks are treated as a special case of literal blocks,
3653 ;; without requiring the literal block syntax. If both are present, the
3654 ;; literal block syntax takes priority over Doctest block syntax:
3655 ;;
3656 ;; This is an ordinary paragraph.
3657 ;;
3658 ;; >>> print 'this is a Doctest block'
3659 ;; this is a Doctest block
3660 ;;
3661 ;; The following is a literal block::
3662 ;;
3663 ;; >>> This is not recognized as a doctest block by
3664 ;; reStructuredText. It *will* be recognized by the doctest
3665 ;; module, though!
3666 ;;
3667 ;; Indentation is not required for doctest blocks.
3677 "Extend the font-lock region if it might be in a multi-line construct.
3678 Return non-nil if so. Font-lock region is from `font-lock-beg'
3679 to `font-lock-end'."
3684 t)))
3687 "Check the region BEG / END for being in the middle of a multi-line construct.
3688 Return nil if not or a cons with new values for BEG / END"
3695 "Like `forward-line' but always end up in column 0 and return accordingly.
3696 Move N lines forward just as `forward-line'."
3699 moved
3703 ;; FIXME: If a single line is made a section header by `rst-adjust' the header
3704 ;; is not always fontified immediately.
3706 "Extend the region starting at point PT and extending in direction DIR.
3707 Return extended point or nil if not moved."
3708 ;; There are many potential multiline constructs but there are two groups
3709 ;; which are really relevant. The first group consists of
3710 ;;
3711 ;; * comment lines without leading explicit markup tag and
3712 ;;
3713 ;; * literal blocks following "::"
3714 ;;
3715 ;; which are both indented. Thus indentation is the first thing recognized
3716 ;; here. The second criteria is an explicit markup tag which may be a comment
3717 ;; or a double colon at the end of a line.
3718 ;;
3719 ;; The second group consists of the adornment cases.
3721 ;; Move only if we don't start inside a multiline construct already.
3724 ;; block tag.
3728 ;; The comments below are for dir == -1 / dir == 1.
3734 ; line if it exists.
3736 ; overline.
3739 ; underline / overline
3740 ; found.
3744 ; overline /
3745 ; underline.
3747 ; / adornment.
3754 ; underline.
3759 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3760 ;; Indented blocks
3763 "Move forward across one indented block.
3764 Find the next non-empty line which is not indented at least to COLUMN (defaults
3765 to the column of the point). Moves point to first character of this line or the
3766 first empty line immediately before it and returns that position. If there is
3767 no such line before LIMIT (defaults to the end of the buffer) returns nil and
3768 point is not moved."
3772 fnd beg cand)
3783 ;; FIXME: No indentation [(zerop clm)] must be handled in some
3784 ;; useful way - though it is not clear what this should mean
3785 ;; at all.
3792 fnd))
3798 "End of the match as determined by `rst-font-lock-find-unindented-line-limit'.
3802 "Find the next unindented line relative to indentation at IND-PNT.
3803 Return this point, the end of the buffer or nil if nothing found.
3804 If IND-PNT is `next' take the indentation from the next line if
3805 this is not empty and indented more than the current one. If
3806 IND-PNT is non-nil but not a number take the indentation from the
3807 next non-empty line if this is indented more than the current one."
3812 ;; Find indentation point in next line if any.
3814 ;; FIXME: Should be refactored to two different functions
3815 ;; giving their result to this function, may be
3816 ;; integrated in caller.
3822 ;; Not at EOF.
3827 ;; Use end of indentation if non-empty line.
3830 ;; Skip until non-empty line or EOF.
3835 ;; Not at EOF.
3839 ;; Indentation bigger than line of departure.
3848 "Set the match found earlier if match were found.
3849 Match has been found by `rst-font-lock-find-unindented-line-limit'
3850 the first time called or no match is found. Return non-nil if
3851 match was found. LIMIT is not used but mandated by the caller."
3855 rst-font-lock-find-unindented-line-end))
3857 rst-font-lock-find-unindented-line-end
3859 ;; Make sure this is called only once.
3861 t))
3863 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3864 ;; Adornments
3867 "Storage for `rst-font-lock-handle-adornment-matcher'.
3871 "Return section level for adornment KEY.
3872 KEY is the first element of the return list of `rst-classify-adornment'.
3873 If KEY is not a cons return it. If KEY is found in the hierarchy return
3874 its level. Otherwise return a level one beyond the existing hierarchy."
3876 key
3889 "Storage for match for current adornment.
3890 Set by `rst-font-lock-handle-adornment-pre-match-form'. Also used
3894 "Determine limit for adornments.
3895 Determine all things necessary for font-locking section titles
3896 and transitions and put the result to `rst-font-lock-adornment-match'
3897 and `rst-font-lock-adornment-level'. ADO is the complete adornment
3898 matched. ADO-END is the point where ADO ends. Return the point
3899 where the whole adorned construct ends.
3901 Called as a PRE-MATCH-FORM in the sense of `font-lock-keywords'."
3905 rst-font-lock-adornment-match nil)
3913 "Set the match found earlier if match were found.
3914 Match has been found by
3915 `rst-font-lock-handle-adornment-pre-match-form' the first time
3916 called or no match is found. Return non-nil if match was found.
3918 Called as a MATCHER in the sense of `font-lock-keywords'.
3919 LIMIT is not used but mandated by the caller."
3921 ;; May run only once - enforce this.
3928 t)))
3930 \f
3931 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3932 ;; Compilation
3935 "Settings for support of conversion of reStructuredText
3957 "Table describing the command to use for each tool-set.
3958 An association list of the tool-set to a list of the (command to use,
3959 extension of produced filename, options to the tool (nil or a
3960 string)) to be used for converting the document."
3961 ;; FIXME: These are not options but symbols which may be referenced by
3962 ;; `rst-compile-*-toolset` below. The `:validate' keyword of
3963 ;; `defcustom' may help to define this properly in newer Emacs
3964 ;; versions (> 23.1).
3966 :key-type symbol
3977 ;; FIXME: Must be defcustom.
3981 ;; FIXME: Must be defcustom.
3986 "Look for the configuration file in the parents of the current path."
3990 ;; Move up in the dir hierarchy till we find a change log file.
3995 nil)
3997 ;; Move up to the parent dir and try again.
4007 "Compile command to convert reST document into some output file.
4008 Attempts to find configuration file, if it can, overrides the
4009 options. There are two commands to choose from; with USE-ALT,
4010 select the alternative tool-set."
4012 ;; Note: maybe we want to check if there is a Makefile too and not do anything
4013 ;; if that is the case. I dunno.
4015 rst-compile-secondary-toolset
4016 rst-compile-primary-toolset)
4017 rst-compile-toolsets)))
4025 ;; Set compile-command before invocation of compile.
4037 ;; Invoke the compile command.
4043 "Compile command with the alternative tool-set."
4048 "Show pseudo-XML rendering.
4049 Rendering is done of the current active region, or of the entire
4050 buffer, if the region is not selected."
4051 ;; FIXME: The region should be given interactively.
4058 standard-output)))
4060 ;; FIXME: Should be defcustom.
4065 "Convert the document to a PDF file and launch a preview program."
4070 buffer-file-name tmp-filename
4071 rst-pdf-program tmp-filename tmp-filename)))
4073 ;; Note: you could also use (compile command) to view the compilation
4074 ;; output.
4075 ))
4077 ;; FIXME: Should be defcustom or use something like `browse-url'.
4082 "Convert the document to an S5 slide presentation and launch a preview program."
4087 buffer-file-name tmp-filename
4088 rst-slides-program tmp-filename tmp-filename)))
4090 ;; Note: you could also use (compile command) to view the compilation
4091 ;; output.
4092 ))
4094 \f
4095 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
4096 ;; Imenu support.
4098 ;; FIXME: Integrate this properly. Consider a key binding.
4100 ;; Based on code from Masatake YAMATO <yamato@redhat.com>.
4103 "Find adornments cell in ADORNMENTS for position POS."
4109 adornments nil)
4111 a))
4114 "Convert a cell ELT in a tree returned from `rst-section-tree' to Imenu index.
4115 ADORNMENTS is used as hint information for conversion."
4125 ;; FIXME: Overline adornment characters need to be in front so
4126 ;; they become visible even for long title lines. May be
4127 ;; an additional level number is also useful.
4130 title
4132 ""
4136 p
4138 ;; A bit ugly but this make which-func happy.
4142 kdr)))))
4143 nil)))
4145 ;; FIXME: Document title and subtitle need to be handled properly. They should
4146 ;; get an own "Document" top level entry.
4148 "Create index for Imenu.
4149 Return as described for `imenu--index-alist'."
4152 ;; Translate line notation to point notation.
4158 ;; FIXME: Need to consider
4159 ;; `imenu-use-markers' here?
4165 tree))))
4167 \f
4168 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
4169 ;; Generic text functions that are more convenient than the defaults.
4171 ;; FIXME: Unbound command - should be bound or removed.
4173 "Replace flush-left lines of FROMCHAR with equal-length lines of TOCHAR."
4175 cSearch for flush-left lines of char:
4188 ;; FIXME: Unbound command - should be bound or removed.
4190 "Join lines in current paragraph into one line, removing end-of-lines."
4195 ;; FIXME: Unbound command - should be bound or removed.
4197 "Fill paragraph at point, first joining the paragraph's lines into one.
4198 This is useful for filling list item paragraphs."
4204 ;; FIXME: Unbound command - should be bound or removed.
4205 ;; Generic character repeater function.
4206 ;; For sections, better to use the specialized function above, but this can
4207 ;; be useful for creating separators.
4209 "Fill the current line using the last character on the current line.
4210 Fill up to the length of the preceding line or up to `fill-column' if preceding
4211 line is empty.
4213 If USE-NEXT, use the next line rather than the preceding line.
4215 If the current line is longer than the desired length, shave the characters off
4216 the current line to fit the desired length.
4218 As an added convenience, if the command is repeated immediately, the alternative
4219 column is used (fill-column vs. end of previous/next line)."
4226 fill-column
4240 ;; Shave characters off the end.
4244 ;; Fill with last characters.
4248 \f
4250 ;; LocalWords: docutils http sourceforge rst html wp svn svnroot txt reST regex
4251 ;; LocalWords: regexes alist seq alt grp keymap abbrev overline overlines toc
4252 ;; LocalWords: XML PNT propertized
4254 ;; Local Variables:
4255 ;; sentence-end-double-space: t
4256 ;; End:
4260 ;;; rst.el ends here