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/>.
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:
34 ;; - Functions to automatically adjust and cycle the section underline
36 ;; - A mode that displays the table of contents and allows you to jump anywhere
38 ;; - Functions to insert and automatically update a TOC in your source
40 ;; - Function to insert list, processing item bullets and enumerations
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.
47 ;; See the accompanying document in the docutils documentation about
48 ;; the contents of this package and how to use it.
50 ;; For more information about reStructuredText, see
51 ;; http://docutils.sourceforge.net/rst.html
53 ;; For full details on how to use the contents of this file, see
54 ;; http://docutils.sourceforge.net/docs/user/emacs.html
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.
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::
64 ;; (add-hook 'rst-adjust-hook 'rst-toc-update)
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::
69 ;; (setq font-lock-global-modes '(not rst-mode ...))
73 ;; Customization is done by customizable variables contained in customization
74 ;; group "rst" and subgroups. Group "rst" is contained in the "wp" group.
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
84 ;; Add the following lines to your init file:
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::
93 ;; .. -*- mode: rst -*-
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:
98 ;; (setq auto-mode-alist
99 ;; (append '(("\\.txt\\'" . rst-mode)
100 ;; ("\\.rst\\'" . rst-mode)
101 ;; ("\\.rest\\'" . rst-mode)) auto-mode-alist))
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
118 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
119 ;; Support for `testcover'
121 (when (and (boundp 'testcover-1value-functions
)
122 (boundp 'testcover-compose-functions
))
123 ;; Below `lambda' is used in a loop with varying parameters and is thus not
125 (setq testcover-1value-functions
126 (delq 'lambda testcover-1value-functions
))
127 (add-to-list 'testcover-compose-functions
'lambda
))
129 (defun rst-testcover-defcustom ()
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'."
133 (when (boundp 'testcover-module-constants
)
134 (setq testcover-module-constants
138 (if (not (plist-member (symbol-plist sym
) 'standard-value
))
140 testcover-module-constants
)))))
142 (defun rst-testcover-add-compose (fun)
143 "Add FUN to `testcover-compose-functions'."
144 (when (boundp 'testcover-compose-functions
)
145 (add-to-list 'testcover-compose-functions fun
)))
147 (defun rst-testcover-add-1value (fun)
148 "Add FUN to `testcover-1value-functions'."
149 (when (boundp 'testcover-1value-functions
)
150 (add-to-list 'testcover-1value-functions fun
)))
152 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
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
162 (defun rst-signum (x)
163 "Return 1 if X is positive, -1 if negative, 0 if zero."
169 (defun rst-some (seq &optional pred
)
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
175 (setq pred
'identity
))
178 (let ((r (funcall pred elem
)))
180 (throw 'rst-some r
))))))
182 (defun rst-position-if (pred seq
)
183 "Return position of first element satisfying PRED in list SEQ or nil."
184 (catch 'rst-position-if
187 (when (funcall pred elem
)
188 (throw 'rst-position-if i
))
191 (defun rst-position (elem seq
)
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'.
197 (lexical-let ((elem elem
))
198 (rst-position-if (function (lambda (e)
202 ;; FIXME: Embed complicated `defconst's in `eval-when-compile'.
204 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
208 (defun rst-extract-version (delim-re head-re re tail-re var
&optional default
)
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."
213 (concat delim-re head-re
"\\(" re
"\\)" tail-re delim-re
)
218 ;; Use CVSHeader to really get information from CVS and not other version
220 (defconst rst-cvs-header
221 "$CVSHeader: sm/rst_el/rst.el,v 1.327.2.6 2012-10-07 13:05:50 stefan Exp $")
222 (defconst rst-cvs-rev
223 (rst-extract-version "\\$" "CVSHeader: \\S + " "[0-9]+\\(?:\\.[0-9]+\\)+"
224 " .*" rst-cvs-header
"0.0")
225 "The CVS revision of this file. CVS revision is the development revision.")
226 (defconst rst-cvs-timestamp
227 (rst-extract-version "\\$" "CVSHeader: \\S + \\S + "
228 "[0-9]+-[0-9]+-[0-9]+ [0-9]+:[0-9]+:[0-9]+" " .*"
229 rst-cvs-header
"1970-01-01 00:00:00")
230 "The CVS time stamp of this file.")
232 ;; Use LastChanged... to really get information from SVN.
233 (defconst rst-svn-rev
234 (rst-extract-version "\\$" "LastChangedRevision: " "[0-9]+" " "
235 "$LastChangedRevision: 7515 $")
236 "The SVN revision of this file.
237 SVN revision is the upstream (docutils) revision.")
238 (defconst rst-svn-timestamp
239 (rst-extract-version "\\$" "LastChangedDate: " ".+?+" " "
240 "$LastChangedDate: 2012-09-20 23:28:53 +0200 (Thu, 20 Sep 2012) $")
241 "The SVN time stamp of this file.")
243 ;; Maintained by the release process.
244 (defconst rst-official-version
245 (rst-extract-version "%" "OfficialVersion: " "[0-9]+\\(?:\\.[0-9]+\\)+" " "
246 "%OfficialVersion: 1.4.0 %")
247 "Official version of the package.")
248 (defconst rst-official-cvs-rev
249 (rst-extract-version "[%$]" "Revision: " "[0-9]+\\(?:\\.[0-9]+\\)+" " "
250 "%Revision: 1.327 %")
251 "CVS revision of this file in the official version.")
253 (defconst rst-version
254 (if (equal rst-official-cvs-rev rst-cvs-rev
)
256 (format "%s (development %s [%s])" rst-official-version
257 rst-cvs-rev rst-cvs-timestamp
))
259 Starts with the current official version. For developer versions
260 in parentheses follows the development revision and the time stamp.")
262 (defconst rst-package-emacs-version-alist
272 (unless (assoc rst-official-version rst-package-emacs-version-alist
)
273 (error "Version %s not listed in `rst-package-emacs-version-alist'"
276 (add-to-list 'customize-package-emacs-version-alist
277 (cons 'ReST rst-package-emacs-version-alist
))
279 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
280 ;; Initialize customization
283 (defgroup rst nil
"Support for reStructuredText documents."
286 :link
'(url-link "http://docutils.sourceforge.net/rst.html"))
289 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
290 ;; Facilities for regular expressions used everywhere
292 ;; The trailing numbers in the names give the number of referenceable regex
293 ;; groups contained in the regex.
295 ;; Used to be customizable but really is not customizable but fixed by the reST
297 (defconst rst-bullets
298 ;; Sorted so they can form a character class when concatenated.
299 '(?- ?
* ?
+ ?
\u2022 ?
\u2023 ?
\u2043)
300 "List of all possible bullet characters for bulleted lists.")
302 (defconst rst-uri-schemes
303 '("acap" "cid" "data" "dav" "fax" "file" "ftp" "gopher" "http" "https" "imap"
304 "ldap" "mailto" "mid" "modem" "news" "nfs" "nntp" "pop" "prospero" "rtsp"
305 "service" "sip" "tel" "telnet" "tip" "urn" "vemmi" "wais")
306 "Supported URI schemes.")
308 (defconst rst-adornment-chars
309 ;; Sorted so they can form a character class when concatenated.
311 ?
! ?
\" ?
# ?$ ?% ?
& ?
' ?\
( ?\
) ?
* ?
+ ?
, ?. ?
/ ?
: ?\
; ?< ?= ?> ?? ?@ ?\[ ?\\
314 "Characters which may be used in adornments for sections and transitions.")
316 (defconst rst-max-inline-length
318 "Maximum length of inline markup to recognize.")
320 (defconst rst-re-alist-def
321 ;; `*-beg' matches * at the beginning of a line.
322 ;; `*-end' matches * at the end of a line.
323 ;; `*-prt' matches a part of *.
324 ;; `*-tag' matches *.
325 ;; `*-sta' matches the start of * which may be followed by respective content.
326 ;; `*-pfx' matches the delimiter left of *.
327 ;; `*-sfx' matches the delimiter right of *.
328 ;; `*-hlp' helper for *.
330 ;; A trailing number says how many referenceable groups are contained.
333 ;; Horizontal white space (`hws')
335 (hws-tag hws-prt
"*") ; Optional sequence of horizontal white space.
336 (hws-sta hws-prt
"+") ; Mandatory sequence of horizontal white space.
339 (lin-beg "^" hws-tag
) ; Beginning of a possibly indented line.
340 (lin-end hws-tag
"$") ; End of a line with optional trailing white space.
341 (linemp-tag "^" hws-tag
"$") ; Empty line with optional white space.
343 ;; Various tags and parts
344 (ell-tag "\\.\\.\\.") ; Ellipsis
345 (bul-tag ,(concat "[" rst-bullets
"]")) ; A bullet.
346 (ltr-tag "[a-zA-Z]") ; A letter enumerator tag.
347 (num-prt "[0-9]") ; A number enumerator part.
348 (num-tag num-prt
"+") ; A number enumerator tag.
349 (rom-prt "[IVXLCDMivxlcdm]") ; A roman enumerator part.
350 (rom-tag rom-prt
"+") ; A roman enumerator tag.
351 (aut-tag "#") ; An automatic enumerator tag.
352 (dcl-tag "::") ; Double colon.
354 ;; Block lead in (`bli')
355 (bli-sfx (:alt hws-sta
"$")) ; Suffix of a block lead-in with *optional*
359 (bul-sta bul-tag bli-sfx
) ; Start of a bulleted item.
361 ;; Explicit markup tag (`exm')
363 (exm-sta exm-tag hws-sta
)
364 (exm-beg lin-beg exm-sta
)
366 ;; Counters in enumerations (`cnt')
367 (cntany-tag (:alt ltr-tag num-tag rom-tag aut-tag
)) ; An arbitrary counter.
368 (cntexp-tag (:alt ltr-tag num-tag rom-tag
)) ; An arbitrary explicit counter.
370 ;; Enumerator (`enm')
372 (:seq cntany-tag
"\\.")
373 (:seq
"(?" cntany-tag
")"))) ; An arbitrary enumerator.
375 (:seq cntexp-tag
"\\.")
376 (:seq
"(?" cntexp-tag
")"))) ; An arbitrary explicit
380 (:seq
"(?" aut-tag
")"))) ; An automatic enumerator.
381 (enmany-sta enmany-tag bli-sfx
) ; An arbitrary enumerator start.
382 (enmexp-sta enmexp-tag bli-sfx
) ; An arbitrary explicit enumerator start.
383 (enmexp-beg lin-beg enmexp-sta
) ; An arbitrary explicit enumerator start
384 ; at the beginning of a line.
386 ;; Items may be enumerated or bulleted (`itm')
387 (itmany-tag (:alt enmany-tag bul-tag
)) ; An arbitrary item tag.
388 (itmany-sta-1 (:grp itmany-tag
) bli-sfx
) ; An arbitrary item start, group
390 (itmany-beg-1 lin-beg itmany-sta-1
) ; An arbitrary item start at the
391 ; beginning of a line, group is the
394 ;; Inline markup (`ilm')
395 (ilm-pfx (:alt
"^" hws-prt
"[-'\"([{<\u2018\u201c\u00ab\u2019/:]"))
396 (ilm-sfx (:alt
"$" hws-prt
"[]-'\")}>\u2019\u201d\u00bb/:.,;!?\\]"))
398 ;; Inline markup content (`ilc')
399 (ilcsgl-tag "\\S ") ; A single non-white character.
400 (ilcast-prt (:alt
"[^*\\]" "\\\\.")) ; Part of non-asterisk content.
401 (ilcbkq-prt (:alt
"[^`\\]" "\\\\.")) ; Part of non-backquote content.
402 (ilcbkqdef-prt (:alt
"[^`\\\n]" "\\\\.")) ; Part of non-backquote
404 (ilcbar-prt (:alt
"[^|\\]" "\\\\.")) ; Part of non-vertical-bar content.
405 (ilcbardef-prt (:alt
"[^|\\\n]" "\\\\.")) ; Part of non-vertical-bar
407 (ilcast-sfx "[^\t *\\]") ; Suffix of non-asterisk content.
408 (ilcbkq-sfx "[^\t `\\]") ; Suffix of non-backquote content.
409 (ilcbar-sfx "[^\t |\\]") ; Suffix of non-vertical-bar content.
410 (ilcrep-hlp ,(format "\\{0,%d\\}" rst-max-inline-length
)) ; Repeat count.
411 (ilcast-tag (:alt ilcsgl-tag
413 ilcast-prt ilcrep-hlp
414 ilcast-sfx
))) ; Non-asterisk content.
415 (ilcbkq-tag (:alt ilcsgl-tag
417 ilcbkq-prt ilcrep-hlp
418 ilcbkq-sfx
))) ; Non-backquote content.
419 (ilcbkqdef-tag (:alt ilcsgl-tag
421 ilcbkqdef-prt ilcrep-hlp
422 ilcbkq-sfx
))) ; Non-backquote definition.
423 (ilcbar-tag (:alt ilcsgl-tag
425 ilcbar-prt ilcrep-hlp
426 ilcbar-sfx
))) ; Non-vertical-bar content.
427 (ilcbardef-tag (:alt ilcsgl-tag
429 ilcbardef-prt ilcrep-hlp
430 ilcbar-sfx
))) ; Non-vertical-bar definition.
433 (fldnam-prt (:alt
"[^:\n]" "\\\\:")) ; Part of a field name.
434 (fldnam-tag fldnam-prt
"+") ; A field name.
435 (fld-tag ":" fldnam-tag
":") ; A field marker.
438 (optsta-tag (:alt
"[-+/]" "--")) ; Start of an option.
439 (optnam-tag "\\sw" (:alt
"-" "\\sw") "*") ; Name of an option.
440 (optarg-tag (:shy
"[ =]\\S +")) ; Option argument.
441 (optsep-tag (:shy
"," hws-prt
)) ; Separator between options.
442 (opt-tag (:shy optsta-tag optnam-tag optarg-tag
"?")) ; A complete option.
444 ;; Footnotes and citations (`fnc')
445 (fncnam-prt "[^\]\n]") ; Part of a footnote or citation name.
446 (fncnam-tag fncnam-prt
"+") ; A footnote or citation name.
447 (fnc-tag "\\[" fncnam-tag
"]") ; A complete footnote or citation tag.
448 (fncdef-tag-2 (:grp exm-sta
)
449 (:grp fnc-tag
)) ; A complete footnote or citation definition
450 ; tag. First group is the explicit markup
451 ; start, second group is the footnote /
453 (fnc-sta-2 fncdef-tag-2 bli-sfx
) ; Start of a footnote or citation
454 ; definition. First group is the explicit
455 ; markup start, second group is the
456 ; footnote / citation tag.
458 ;; Substitutions (`sub')
459 (sub-tag "|" ilcbar-tag
"|") ; A complete substitution tag.
460 (subdef-tag "|" ilcbardef-tag
"|") ; A complete substitution definition
464 (sym-prt "[-+.:_]") ; Non-word part of a symbol.
465 (sym-tag (:shy
"\\sw+" (:shy sym-prt
"\\sw+") "*"))
468 (uri-tag (:alt
,@rst-uri-schemes
))
471 (ado-prt "[" ,(concat rst-adornment-chars
) "]")
472 (adorep3-hlp "\\{3,\\}") ; There must be at least 3 characters because
473 ; otherwise explicit markup start would be
475 (adorep2-hlp "\\{2,\\}") ; As `adorep3-hlp' but when the first of three
476 ; characters is matched differently.
477 (ado-tag-1-1 (:grp ado-prt
)
478 "\\1" adorep2-hlp
) ; A complete adornment, group is the first
479 ; adornment character and MUST be the FIRST
480 ; group in the whole expression.
481 (ado-tag-1-2 (:grp ado-prt
)
482 "\\2" adorep2-hlp
) ; A complete adornment, group is the first
483 ; adornment character and MUST be the
484 ; SECOND group in the whole expression.
485 (ado-beg-2-1 "^" (:grp ado-tag-1-2
)
486 lin-end
) ; A complete adornment line; first group is the whole
487 ; adornment and MUST be the FIRST group in the whole
488 ; expression; second group is the first adornment
492 (ttl-tag "\\S *\\w\\S *") ; A title text.
493 (ttl-beg lin-beg ttl-tag
) ; A title text at the beginning of a line.
495 ;; Directives and substitution definitions (`dir')
496 (dir-tag-3 (:grp exm-sta
)
497 (:grp
(:shy subdef-tag hws-sta
) "?")
498 (:grp sym-tag dcl-tag
)) ; A directive or substitution definition
499 ; tag. First group is explicit markup
500 ; start, second group is a possibly
501 ; empty substitution tag, third group is
502 ; the directive tag including the double
504 (dir-sta-3 dir-tag-3 bli-sfx
) ; Start of a directive or substitution
505 ; definition. Groups are as in dir-tag-3.
507 ;; Literal block (`lit')
508 (lit-sta-2 (:grp
(:alt
"[^.\n]" "\\.[^.\n]") ".*") "?"
509 (:grp dcl-tag
) "$") ; Start of a literal block. First group is
510 ; any text before the double colon tag which
511 ; may not exist, second group is the double
515 (cmt-sta-1 (:grp exm-sta
) "[^\[|_\n]"
516 (:alt
"[^:\n]" (:seq
":" (:alt
"[^:\n]" "$")))
517 "*$") ; Start of a comment block; first group is explicit markup
520 ;; Paragraphs (`par')
521 (par-tag- (:alt itmany-tag fld-tag opt-tag fncdef-tag-2 dir-tag-3 exm-tag
)
522 ) ; Tag at the beginning of a paragraph; there may be groups in
525 "Definition alist of relevant regexes.
526 Each entry consists of the symbol naming the regex and an
527 argument list for `rst-re'.")
529 (defvar rst-re-alist
) ; Forward declare to use it in `rst-re'.
531 ;; FIXME: Use `sregex` or `rx` instead of re-inventing the wheel.
532 (rst-testcover-add-compose 'rst-re
)
534 (defun rst-re (&rest args
)
535 "Interpret ARGS as regular expressions and return a regex string.
536 Each element of ARGS may be one of the following:
538 A string which is inserted unchanged.
540 A character which is resolved to a quoted regex.
542 A symbol which is resolved to a string using `rst-re-alist-def'.
544 A list with a keyword in the car. Each element of the cdr of such
545 a list is recursively interpreted as ARGS. The results of this
546 interpretation are concatenated according to the keyword.
548 For the keyword `:seq' the results are simply concatenated.
550 For the keyword `:shy' the results are concatenated and
551 surrounded by a shy-group (\"\\(?:...\\)\").
553 For the keyword `:alt' the results form an alternative (\"\\|\")
554 which is shy-grouped (\"\\(?:...\\)\").
556 For the keyword `:grp' the results are concatenated and form a
557 referenceable group (\"\\(...\\)\").
559 After interpretation of ARGS the results are concatenated as for
568 (cadr (assoc re rst-re-alist
)))
570 (regexp-quote (char-to-string re
)))
573 (mapcar (lambda (elt)
578 (mapconcat 'identity nested
""))
580 (concat "\\(?:" (mapconcat 'identity nested
"") "\\)"))
582 (concat "\\(" (mapconcat 'identity nested
"") "\\)"))
584 (concat "\\(?:" (mapconcat 'identity nested
"\\|") "\\)"))
586 (error "Unknown list car: %s" (car re
))))))
588 (error "Unknown object type for building regex: %s" re
))))
591 ;; FIXME: Remove circular dependency between `rst-re' and `rst-re-alist'.
592 (with-no-warnings ; Silence byte-compiler about this construction.
593 (defconst rst-re-alist
594 ;; Shadow global value we are just defining so we can construct it step by
597 (dolist (re rst-re-alist-def rst-re-alist
)
600 (list (list (car re
) (apply 'rst-re
(cdr re
))))))))
601 "Alist mapping symbols from `rst-re-alist-def' to regex strings."))
604 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
608 (defun rst-define-key (keymap key def
&rest deprecated
)
609 "Bind like `define-key' but add deprecated key definitions.
610 KEYMAP, KEY, and DEF are as in `define-key'. DEPRECATED key
611 definitions should be in vector notation. These are defined
612 as well but give an additional message."
613 (define-key keymap key def
)
615 (let* ((command-name (symbol-name def
))
616 (forwarder-function-name
617 (if (string-match "^rst-\\(.*\\)$" command-name
)
618 (concat "rst-deprecated-"
619 (match-string 1 command-name
))
620 (error "not an RST command: %s" command-name
)))
621 (forwarder-function (intern forwarder-function-name
)))
622 (unless (fboundp forwarder-function
)
623 (defalias forwarder-function
624 (lexical-let ((key key
) (def def
))
627 (call-interactively def
)
628 (message "[Deprecated use of key %s; use key %s instead]"
629 (key-description (this-command-keys))
630 (key-description key
))))
631 (format "Deprecated binding for %s, use \\[%s] instead."
633 (dolist (dep-key deprecated
)
634 (define-key keymap dep-key forwarder-function
)))))
637 (let ((map (make-sparse-keymap)))
639 ;; \C-c is the general keymap.
640 (rst-define-key map
[?\C-c ?\C-h
] 'describe-prefix-bindings
)
643 ;; Section Adornments
645 ;; The adjustment function that adorns or rotates a section title.
646 (rst-define-key map
[?\C-c ?\C-
=] 'rst-adjust
[?\C-c ?\C-a t
])
647 (rst-define-key map
[?\C-
=] 'rst-adjust
) ; Does not work on the Mac OSX and
650 ;; \C-c \C-a is the keymap for adornments.
651 (rst-define-key map
[?\C-c ?\C-a ?\C-h
] 'describe-prefix-bindings
)
652 ;; Another binding which works with all types of input.
653 (rst-define-key map
[?\C-c ?\C-a ?\C-a
] 'rst-adjust
)
654 ;; Display the hierarchy of adornments implied by the current document
656 (rst-define-key map
[?\C-c ?\C-a ?\C-d
] 'rst-display-adornments-hierarchy
)
657 ;; Homogenize the adornments in the document.
658 (rst-define-key map
[?\C-c ?\C-a ?\C-s
] 'rst-straighten-adornments
662 ;; Section Movement and Selection
664 ;; Mark the subsection where the cursor is.
665 (rst-define-key map
[?\C-\M-h
] 'rst-mark-section
666 ;; Same as mark-defun sgml-mark-current-element.
668 ;; Move backward/forward between section titles.
669 ;; FIXME: Also bind similar to outline mode.
670 (rst-define-key map
[?\C-\M-a
] 'rst-backward-section
671 ;; Same as beginning-of-defun.
673 (rst-define-key map
[?\C-\M-e
] 'rst-forward-section
674 ;; Same as end-of-defun.
678 ;; Operating on regions
680 ;; \C-c \C-r is the keymap for regions.
681 (rst-define-key map
[?\C-c ?\C-r ?\C-h
] 'describe-prefix-bindings
)
682 ;; Makes region a line-block.
683 (rst-define-key map
[?\C-c ?\C-r ?\C-l
] 'rst-line-block-region
685 ;; Shift region left or right according to tabs.
686 (rst-define-key map
[?\C-c ?\C-r tab
] 'rst-shift-region
687 [?\C-c ?\C-r t
] [?\C-c ?\C-l t
])
690 ;; Operating on lists
692 ;; \C-c \C-l is the keymap for lists.
693 (rst-define-key map
[?\C-c ?\C-l ?\C-h
] 'describe-prefix-bindings
)
694 ;; Makes paragraphs in region as a bullet list.
695 (rst-define-key map
[?\C-c ?\C-l ?\C-b
] 'rst-bullet-list-region
697 ;; Makes paragraphs in region as a enumeration.
698 (rst-define-key map
[?\C-c ?\C-l ?\C-e
] 'rst-enumerate-region
700 ;; Converts bullets to an enumeration.
701 (rst-define-key map
[?\C-c ?\C-l ?\C-c
] 'rst-convert-bullets-to-enumeration
703 ;; Make sure that all the bullets in the region are consistent.
704 (rst-define-key map
[?\C-c ?\C-l ?\C-s
] 'rst-straighten-bullets-region
706 ;; Insert a list item.
707 (rst-define-key map
[?\C-c ?\C-l ?\C-i
] 'rst-insert-list
)
710 ;; Table-of-Contents Features
712 ;; \C-c \C-t is the keymap for table of contents.
713 (rst-define-key map
[?\C-c ?\C-t ?\C-h
] 'describe-prefix-bindings
)
714 ;; Enter a TOC buffer to view and move to a specific section.
715 (rst-define-key map
[?\C-c ?\C-t ?\C-t
] 'rst-toc
)
716 ;; Insert a TOC here.
717 (rst-define-key map
[?\C-c ?\C-t ?\C-i
] 'rst-toc-insert
719 ;; Update the document's TOC (without changing the cursor position).
720 (rst-define-key map
[?\C-c ?\C-t ?\C-u
] 'rst-toc-update
722 ;; Go to the section under the cursor (cursor must be in TOC).
723 (rst-define-key map
[?\C-c ?\C-t ?\C-j
] 'rst-goto-section
727 ;; Converting Documents from Emacs
729 ;; \C-c \C-c is the keymap for compilation.
730 (rst-define-key map
[?\C-c ?\C-c ?\C-h
] 'describe-prefix-bindings
)
731 ;; Run one of two pre-configured toolset commands on the document.
732 (rst-define-key map
[?\C-c ?\C-c ?\C-c
] 'rst-compile
734 (rst-define-key map
[?\C-c ?\C-c ?\C-a
] 'rst-compile-alt-toolset
736 ;; Convert the active region to pseudo-xml using the docutils tools.
737 (rst-define-key map
[?\C-c ?\C-c ?\C-x
] 'rst-compile-pseudo-region
739 ;; Convert the current document to PDF and launch a viewer on the results.
740 (rst-define-key map
[?\C-c ?\C-c ?\C-p
] 'rst-compile-pdf-preview
742 ;; Convert the current document to S5 slides and view in a web browser.
743 (rst-define-key map
[?\C-c ?\C-c ?\C-s
] 'rst-compile-slides-preview
747 "Keymap for reStructuredText mode commands.
748 This inherits from Text mode.")
752 (define-abbrev-table 'rst-mode-abbrev-table
753 (mapcar (lambda (x) (append x
'(nil 0 system
)))
754 '(("contents" ".. contents::\n..\n ")
755 ("con" ".. contents::\n..\n ")
757 ("skip" "\n\n[...]\n\n ")
758 ("seq" "\n\n[...]\n\n ")
759 ;; FIXME: Add footnotes, links, and more.
761 "Abbrev table used while in `rst-mode'.")
765 (defvar rst-mode-syntax-table
766 (let ((st (copy-syntax-table text-mode-syntax-table
)))
767 (modify-syntax-entry ?$
"." st
)
768 (modify-syntax-entry ?%
"." st
)
769 (modify-syntax-entry ?
& "." st
)
770 (modify-syntax-entry ?
' "." st
)
771 (modify-syntax-entry ?
* "." st
)
772 (modify-syntax-entry ?
+ "." st
)
773 (modify-syntax-entry ?-
"." st
)
774 (modify-syntax-entry ?
/ "." st
)
775 (modify-syntax-entry ?
< "." st
)
776 (modify-syntax-entry ?
= "." st
)
777 (modify-syntax-entry ?
> "." st
)
778 (modify-syntax-entry ?
\\ "\\" st
)
779 (modify-syntax-entry ?_
"." st
)
780 (modify-syntax-entry ?|
"." st
)
781 (modify-syntax-entry ?
\u00ab "." st
)
782 (modify-syntax-entry ?
\u00bb "." st
)
783 (modify-syntax-entry ?
\u2018 "." st
)
784 (modify-syntax-entry ?
\u2019 "." st
)
785 (modify-syntax-entry ?
\u201c "." st
)
786 (modify-syntax-entry ?
\u201d "." st
)
788 "Syntax table used while in `rst-mode'.")
790 (defcustom rst-mode-hook nil
791 "Hook run when `rst-mode' is turned on.
792 The hook for `text-mode' is run before this one."
795 (rst-testcover-defcustom)
797 ;; Pull in variable definitions silencing byte-compiler.
798 (require 'newcomment
)
800 (defvar electric-pair-pairs
)
802 ;; Use rst-mode for *.rst and *.rest files. Many ReStructured-Text files
803 ;; use *.txt, but this is too generic to be set as a default.
804 ;;;###autoload (add-to-list 'auto-mode-alist (purecopy '("\\.re?st\\'" . rst-mode)))
806 (define-derived-mode rst-mode text-mode
"ReST"
807 "Major mode for editing reStructuredText documents.
810 Turning on `rst-mode' calls the normal hooks `text-mode-hook'
811 and `rst-mode-hook'. This mode also supports font-lock
815 :abbrev-table rst-mode-abbrev-table
816 :syntax-table rst-mode-syntax-table
819 ;; Paragraph recognition.
820 (set (make-local-variable 'paragraph-separate
)
824 (set (make-local-variable 'paragraph-start
)
828 (:seq hws-tag par-tag- bli-sfx
))))
830 ;; Indenting and filling.
831 (set (make-local-variable 'indent-line-function
) 'rst-indent-line
)
832 (set (make-local-variable 'adaptive-fill-mode
) t
)
833 (set (make-local-variable 'adaptive-fill-regexp
)
834 (rst-re 'hws-tag
'par-tag-
"?" 'hws-tag
))
835 (set (make-local-variable 'adaptive-fill-function
) 'rst-adaptive-fill
)
836 (set (make-local-variable 'fill-paragraph-handle-comment
) nil
)
839 (set (make-local-variable 'comment-start
) ".. ")
840 (set (make-local-variable 'comment-start-skip
)
841 (rst-re 'lin-beg
'exm-tag
'bli-sfx
))
842 (set (make-local-variable 'comment-continue
) " ")
843 (set (make-local-variable 'comment-multi-line
) t
)
844 (set (make-local-variable 'comment-use-syntax
) nil
)
845 ;; reStructuredText has not really a comment ender but nil is not really a
846 ;; permissible value.
847 (set (make-local-variable 'comment-end
) "")
848 (set (make-local-variable 'comment-end-skip
) nil
)
850 ;; Commenting in reStructuredText is very special so use our own set of
852 (set (make-local-variable 'comment-line-break-function
)
853 'rst-comment-line-break
)
854 (set (make-local-variable 'comment-indent-function
)
856 (set (make-local-variable 'comment-insert-comment-function
)
857 'rst-comment-insert-comment
)
858 (set (make-local-variable 'comment-region-function
)
860 (set (make-local-variable 'uncomment-region-function
)
861 'rst-uncomment-region
)
863 (set (make-local-variable 'electric-pair-pairs
)
864 '((?
\" . ?
\") (?\
* . ?\
*) (?\
` . ?\
`)))
866 ;; Imenu and which function.
867 ;; FIXME: Check documentation of `which-function' for alternative ways to
868 ;; determine the current function name.
869 (set (make-local-variable 'imenu-create-index-function
)
870 'rst-imenu-create-index
)
873 (set (make-local-variable 'font-lock-defaults
)
874 '(rst-font-lock-keywords
876 (font-lock-multiline . t
)
877 (font-lock-mark-block-function . mark-paragraph
)))
878 (add-hook 'font-lock-extend-region-functions
'rst-font-lock-extend-region t
)
880 ;; Text after a changed line may need new fontification.
881 (set (make-local-variable 'jit-lock-contextually
) t
)
883 ;; Indentation is not deterministic.
884 (setq electric-indent-inhibit t
))
887 (define-minor-mode rst-minor-mode
888 "Toggle ReST minor mode.
889 With a prefix argument ARG, enable ReST minor mode if ARG is
890 positive, and disable it otherwise. If called from Lisp, enable
891 the mode if ARG is omitted or nil.
893 When ReST minor mode is enabled, the ReST mode keybindings
894 are installed on top of the major mode bindings. Use this
895 for modes derived from Text mode, like Mail mode."
896 ;; The initial value.
898 ;; The indicator for the mode line.
900 ;; The minor mode bindings.
904 ;; FIXME: can I somehow install these too?
905 ;; :abbrev-table rst-mode-abbrev-table
906 ;; :syntax-table rst-mode-syntax-table
909 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
910 ;; Section Adornment Adjustment
911 ;; ============================
913 ;; The following functions implement a smart automatic title sectioning feature.
914 ;; The idea is that with the cursor sitting on a section title, we try to get as
915 ;; much information from context and try to do the best thing automatically.
916 ;; This function can be invoked many times and/or with prefix argument to rotate
917 ;; between the various sectioning adornments.
919 ;; Definitions: the two forms of sectioning define semantically separate section
920 ;; levels. A sectioning ADORNMENT consists in:
924 ;; - a STYLE which can be either of 'simple' or 'over-and-under'.
926 ;; - an INDENT (meaningful for the over-and-under style only) which determines
927 ;; how many characters and over-and-under style is hanging outside of the
928 ;; title at the beginning and ending.
930 ;; Here are two examples of adornments (| represents the window border, column
934 ;; 1. char: '-' e |Some Title
935 ;; style: simple |----------
937 ;; 2. char: '=' |==============
938 ;; style: over-and-under | Some Title
939 ;; indent: 2 |==============
944 ;; - The underlining character that is used depends on context. The file is
945 ;; scanned to find other sections and an appropriate character is selected.
946 ;; If the function is invoked on a section that is complete, the character is
947 ;; rotated among the existing section adornments.
949 ;; Note that when rotating the characters, if we come to the end of the
950 ;; hierarchy of adornments, the variable rst-preferred-adornments is
951 ;; consulted to propose a new underline adornment, and if continued, we cycle
952 ;; the adornments all over again. Set this variable to nil if you want to
953 ;; limit the underlining character propositions to the existing adornments in
956 ;; - An underline/overline that is not extended to the column at which it should
957 ;; be hanging is dubbed INCOMPLETE. For example::
962 ;; Examples of default invocation:
964 ;; |Some Title ---> |Some Title
967 ;; |Some Title ---> |Some Title
968 ;; |----- |----------
971 ;; | Some Title ---> | Some Title
974 ;; In over-and-under style, when alternating the style, a variable is
975 ;; available to select how much default indent to use (it can be zero). Note
976 ;; that if the current section adornment already has an indent, we don't
977 ;; adjust it to the default, we rather use the current indent that is already
978 ;; there for adjustment (unless we cycle, in which case we use the indent
979 ;; that has been found previously).
981 (defgroup rst-adjust nil
982 "Settings for adjustment and cycling of section title adornments."
986 (define-obsolete-variable-alias
987 'rst-preferred-decorations
'rst-preferred-adornments
"rst 1.0.0")
988 (defcustom rst-preferred-adornments
'((?
= over-and-under
1)
996 "Preferred hierarchy of section title adornments.
998 A list consisting of lists of the form (CHARACTER STYLE INDENT).
999 CHARACTER is the character used. STYLE is one of the symbols
1000 `over-and-under' or `simple'. INDENT is an integer giving the
1001 wanted indentation for STYLE `over-and-under'. CHARACTER and
1002 STYLE are always used when a section adornment is described.
1003 In other places, t instead of a list stands for a transition.
1005 This sequence is consulted to offer a new adornment suggestion
1006 when we rotate the underlines at the end of the existing
1007 hierarchy of characters, or when there is no existing section
1010 Set this to an empty list to use only the adornment found in the
1014 (group :tag
"Adornment specification"
1015 (choice :tag
"Adornment character"
1016 ,@(mapcar (lambda (char)
1018 :tag
(char-to-string char
) char
))
1019 rst-adornment-chars
))
1020 (radio :tag
"Adornment type"
1021 (const :tag
"Overline and underline" over-and-under
)
1022 (const :tag
"Underline only" simple
))
1023 (integer :tag
"Indentation for overline and underline type"
1025 (rst-testcover-defcustom)
1027 (defcustom rst-default-indent
1
1028 "Number of characters to indent the section title.
1030 This is used for when toggling adornment styles, when switching
1031 from a simple adornment style to a over-and-under adornment
1035 (rst-testcover-defcustom)
1037 (defun rst-compare-adornments (ado1 ado2
)
1038 "Compare adornments.
1039 Return true if both ADO1 and ADO2 adornments are equal,
1040 according to restructured text semantics (only the character
1041 and the style are compared, the indentation does not matter)."
1042 (and (eq (car ado1
) (car ado2
))
1043 (eq (cadr ado1
) (cadr ado2
))))
1046 (defun rst-get-adornment-match (hier ado
)
1047 "Return the index (level) in hierarchy HIER of adornment ADO.
1048 This basically just searches for the item using the appropriate
1049 comparison and returns the index. Return nil if the item is
1052 (while (and cur
(not (rst-compare-adornments (car cur
) ado
)))
1053 (setq cur
(cdr cur
)))
1056 ;; testcover: FIXME: Test with `rst-preferred-adornments' == nil. Add test
1057 ;; `rst-adjust-no-preference'.
1058 (defun rst-suggest-new-adornment (allados &optional prev
)
1059 "Suggest a new, different adornment from all that have been seen.
1061 ALLADOS is the set of all adornments, including the line numbers.
1062 PREV is the optional previous adornment, in order to suggest a
1065 ;; For all the preferred adornments...
1067 ;; If 'prev' is given, reorder the list to start searching after the
1070 (cdr (rst-get-adornment-match rst-preferred-adornments prev
)))
1072 ;; List of candidates to search.
1073 (curpotential (append fplist rst-preferred-adornments
)))
1075 ;; For all the adornments...
1078 (while (and cur
(not found
))
1079 (if (rst-compare-adornments (car cur
) (car curpotential
))
1081 (setq found
(car curpotential
))
1082 (setq cur
(cdr cur
))))
1085 (setq curpotential
(cdr curpotential
)))
1087 (copy-sequence (car curpotential
))))
1089 (defun rst-delete-entire-line ()
1090 "Delete the entire current line without using the `kill-ring'."
1091 (delete-region (line-beginning-position)
1092 (line-beginning-position 2)))
1094 (defun rst-update-section (char style
&optional indent
)
1095 "Unconditionally update the style of a section adornment.
1097 Do this using the given character CHAR, with STYLE `simple'
1098 or `over-and-under', and with indent INDENT. If the STYLE
1099 is `simple', whitespace before the title is removed (indent
1100 is always assumed to be 0).
1102 If there are existing overline and/or underline from the
1103 existing adornment, they are removed before adding the
1104 requested adornment."
1106 (let ((marker (point-marker))
1109 ;; Fixup whitespace at the beginning and end of the line.
1110 (if (or (null indent
) (eq style
'simple
)) ;; testcover: ok.
1113 (delete-horizontal-space)
1114 (insert (make-string indent ?
))
1117 (delete-horizontal-space)
1119 ;; Set the current column, we're at the end of the title line.
1120 (setq len
(+ (current-column) indent
))
1122 ;; Remove previous line if it is an adornment.
1124 (forward-line -
1) ;; testcover: FIXME: Doesn't work when in first line
1126 (if (and (looking-at (rst-re 'ado-beg-2-1
))
1127 ;; Avoid removing the underline of a title right above us.
1128 (save-excursion (forward-line -
1)
1129 (not (looking-at (rst-re 'ttl-beg
)))))
1130 (rst-delete-entire-line)))
1132 ;; Remove following line if it is an adornment.
1134 (forward-line +1) ;; testcover: FIXME: Doesn't work when in last line
1136 (if (looking-at (rst-re 'ado-beg-2-1
))
1137 (rst-delete-entire-line))
1138 ;; Add a newline if we're at the end of the buffer, for the subsequence
1139 ;; inserting of the underline.
1140 (if (= (point) (buffer-end 1))
1144 (if (eq style
'over-and-under
)
1148 (insert (make-string len char
))))
1150 ;; Insert underline.
1151 (1value ;; Line has been inserted above.
1154 (insert (make-string len char
))
1156 (1value ;; Line has been inserted above.
1158 (goto-char marker
)))
1160 (defun rst-classify-adornment (adornment end
)
1161 "Classify adornment for section titles and transitions.
1162 ADORNMENT is the complete adornment string as found in the buffer
1163 with optional trailing whitespace. END is the point after the
1164 last character of ADORNMENT.
1166 Return a list. The first entry is t for a transition or a
1167 cons (CHARACTER . STYLE). Check `rst-preferred-adornments' for
1168 the meaning of CHARACTER and STYLE.
1170 The remaining list forms four match groups as returned by
1171 `match-data'. Match group 0 matches the whole construct. Match
1172 group 1 matches the overline adornment if present. Match group 2
1173 matches the section title text or the transition. Match group 3
1174 matches the underline adornment.
1176 Return nil if no syntactically valid adornment is found."
1179 (when (string-match (rst-re 'ado-beg-2-1
) adornment
)
1181 (let* ((ado-ch (string-to-char (match-string 2 adornment
)))
1182 (ado-re (rst-re ado-ch
'adorep3-hlp
))
1185 (1value ;; No lines may be left to move.
1188 (nxt-emp ; Next line nonexistent or empty
1190 (or (not (zerop (forward-line 1)))
1191 ;; testcover: FIXME: Add test classifying at the end of
1193 (looking-at (rst-re 'lin-end
)))))
1194 (prv-emp ; Previous line nonexistent or empty
1196 (or (not (zerop (forward-line -
1)))
1197 (looking-at (rst-re 'lin-end
)))))
1198 (ttl-blw ; Title found below starting here.
1201 (zerop (forward-line 1)) ;; testcover: FIXME: Add test
1202 ;; classifying at the end of
1204 (looking-at (rst-re 'ttl-beg
))
1206 (ttl-abv ; Title found above starting here.
1209 (zerop (forward-line -
1))
1210 (looking-at (rst-re 'ttl-beg
))
1212 (und-fnd ; Matching underline found starting here.
1215 (zerop (forward-line 2)) ;; testcover: FIXME: Add test
1216 ;; classifying at the end of
1218 (looking-at (rst-re ado-re
'lin-end
))
1220 (ovr-fnd ; Matching overline found starting here.
1223 (zerop (forward-line -
2))
1224 (looking-at (rst-re ado-re
'lin-end
))
1226 key beg-ovr end-ovr beg-txt end-txt beg-und end-und
)
1228 ((and nxt-emp prv-emp
)
1233 ((or und-fnd ovr-fnd
)
1234 ;; An overline with an underline.
1235 (setq key
(cons ado-ch
'over-and-under
))
1236 (let (;; Prefer overline match over underline match.
1237 (und-pnt (if ovr-fnd beg-pnt und-fnd
))
1238 (ovr-pnt (if ovr-fnd ovr-fnd beg-pnt
))
1239 (txt-pnt (if ovr-fnd ttl-abv ttl-blw
)))
1241 (setq beg-ovr
(point)
1242 end-ovr
(line-end-position))
1244 (setq beg-txt
(point)
1245 end-txt
(line-end-position))
1247 (setq beg-und
(point)
1248 end-und
(line-end-position))))
1251 (setq key
(cons ado-ch
'simple
)
1255 (setq beg-txt
(point)
1256 end-txt
(line-end-position)))
1258 ;; Invalid adornment.
1262 (or beg-ovr beg-txt
)
1263 (or end-und end-txt
)
1264 beg-ovr end-ovr beg-txt end-txt beg-und end-und
)))))))
1266 (defun rst-find-title-line ()
1267 "Find a section title line around point and return its characteristics.
1268 If the point is on an adornment line find the respective title
1269 line. If the point is on an empty line check previous or next
1270 line whether it is a suitable title line and use it if so. If
1271 point is on a suitable title line use it.
1273 If no title line is found return nil.
1275 Otherwise return as `rst-classify-adornment' does. However, if
1276 the title line has no syntactically valid adornment, STYLE is nil
1277 in the first element. If there is no adornment around the title,
1278 CHARACTER is also nil and match groups for overline and underline
1281 (1value ;; No lines may be left to move.
1283 (let ((orig-pnt (point))
1284 (orig-end (line-end-position)))
1286 ((looking-at (rst-re 'ado-beg-2-1
))
1287 (let ((char (string-to-char (match-string-no-properties 2)))
1288 (r (rst-classify-adornment (match-string-no-properties 0)
1292 ;; Invalid adornment - check whether this is an incomplete overline.
1294 (zerop (forward-line 1))
1295 (looking-at (rst-re 'ttl-beg
)))
1296 (list (cons char nil
) orig-pnt
(line-end-position)
1297 orig-pnt orig-end
(point) (line-end-position) nil nil
)))
1299 ;; A section title - not a transition.
1301 ((looking-at (rst-re 'lin-end
))
1304 (if (and (zerop (forward-line -
1))
1305 (looking-at (rst-re 'ttl-beg
)))
1306 (list (cons nil nil
) (point) (line-end-position)
1307 nil nil
(point) (line-end-position) nil nil
)))
1309 (if (and (zerop (forward-line 1))
1310 (looking-at (rst-re 'ttl-beg
)))
1311 (list (cons nil nil
) (point) (line-end-position)
1312 nil nil
(point) (line-end-position) nil nil
)))))
1313 ((looking-at (rst-re 'ttl-beg
))
1314 ;; Try to use the underline.
1315 (let ((r (rst-classify-adornment
1316 (buffer-substring-no-properties
1317 (line-beginning-position 2) (line-end-position 2))
1318 (line-end-position 2))))
1321 ;; No valid adornment found.
1322 (list (cons nil nil
) (point) (line-end-position)
1323 nil nil
(point) (line-end-position) nil nil
))))))))
1325 ;; The following function and variables are used to maintain information about
1326 ;; current section adornment in a buffer local cache. Thus they can be used for
1327 ;; font-locking and manipulation commands.
1329 (defvar rst-all-sections nil
1330 "All section adornments in the buffer as found by `rst-find-all-adornments'.
1331 Set to t when no section adornments were found.")
1332 (make-variable-buffer-local 'rst-all-sections
)
1334 ;; FIXME: If this variable is set to a different value font-locking of section
1335 ;; headers is wrong.
1336 (defvar rst-section-hierarchy nil
1337 "Section hierarchy in the buffer as determined by `rst-get-hierarchy'.
1338 Set to t when no section adornments were found.
1339 Value depends on `rst-all-sections'.")
1340 (make-variable-buffer-local 'rst-section-hierarchy
)
1342 (rst-testcover-add-1value 'rst-reset-section-caches
)
1343 (defun rst-reset-section-caches ()
1344 "Reset all section cache variables.
1345 Should be called by interactive functions which deal with sections."
1346 (setq rst-all-sections nil
1347 rst-section-hierarchy nil
))
1349 (defun rst-find-all-adornments ()
1350 "Return all the section adornments in the current buffer.
1351 Return a list of (LINE . ADORNMENT) with ascending LINE where
1352 LINE is the line containing the section title. ADORNMENT consists
1353 of a (CHARACTER STYLE INDENT) triple as described for
1354 `rst-preferred-adornments'.
1356 Uses and sets `rst-all-sections'."
1357 (unless rst-all-sections
1359 ;; Iterate over all the section titles/adornments in the file.
1361 (goto-char (point-min))
1362 (while (re-search-forward (rst-re 'ado-beg-2-1
) nil t
)
1363 (let ((ado-data (rst-classify-adornment
1364 (match-string-no-properties 0) (point))))
1366 (consp (car ado-data
))) ; Ignore transitions.
1367 (set-match-data (cdr ado-data
))
1368 (goto-char (match-beginning 2)) ; Goto the title start.
1369 (push (cons (1+ (count-lines (point-min) (point)))
1370 (list (caar ado-data
)
1372 (current-indentation)))
1374 (goto-char (match-end 0))))) ; Go beyond the whole thing.
1375 (setq positions
(nreverse positions
))
1376 (setq rst-all-sections
(or positions t
)))))
1377 (if (eq rst-all-sections t
)
1381 (defun rst-infer-hierarchy (adornments)
1382 "Build a hierarchy of adornments using the list of given ADORNMENTS.
1384 ADORNMENTS is a list of (CHARACTER STYLE INDENT) adornment
1385 specifications, in order that they appear in a file, and will
1386 infer a hierarchy of section levels by removing adornments that
1387 have already been seen in a forward traversal of the adornments,
1388 comparing just CHARACTER and STYLE.
1390 Similarly returns a list of (CHARACTER STYLE INDENT), where each
1391 list element should be unique."
1392 (let (hierarchy-alist)
1393 (dolist (x adornments
)
1394 (let ((char (car x
))
1396 (unless (assoc (cons char style
) hierarchy-alist
)
1397 (push (cons (cons char style
) x
) hierarchy-alist
))))
1398 (mapcar 'cdr
(nreverse hierarchy-alist
))))
1400 (defun rst-get-hierarchy (&optional ignore
)
1401 "Return the hierarchy of section titles in the file.
1403 Return a list of adornments that represents the hierarchy of
1404 section titles in the file. Each element consists of (CHARACTER
1405 STYLE INDENT) as described for `rst-find-all-adornments'. If the
1406 line number in IGNORE is specified, a possibly adornment found on
1407 that line is not taken into account when building the hierarchy.
1409 Uses and sets `rst-section-hierarchy' unless IGNORE is given."
1410 (if (and (not ignore
) rst-section-hierarchy
)
1411 (if (eq rst-section-hierarchy t
)
1413 rst-section-hierarchy
)
1414 (let ((r (rst-infer-hierarchy
1418 (rst-find-all-adornments))))))
1419 (setq rst-section-hierarchy
1421 ;; Clear cache reflecting that a possible update is not
1427 (defun rst-get-adornments-around ()
1428 "Return the adornments around point.
1429 Return a list of the previous and next adornments."
1430 (let* ((all (rst-find-all-adornments))
1431 (curline (line-number-at-pos))
1435 ;; Search for the adornments around the current line.
1436 (while (and cur
(< (caar cur
) curline
))
1439 ;; 'cur' is the following adornment.
1441 (if (and cur
(caar cur
))
1442 (setq next
(if (= curline
(caar cur
)) (cdr cur
) cur
)))
1444 (mapcar 'cdar
(list prev next
))))
1446 (defun rst-adornment-complete-p (ado)
1447 "Return true if the adornment ADO around point is complete."
1448 ;; Note: we assume that the detection of the overline as being the underline
1449 ;; of a preceding title has already been detected, and has been eliminated
1450 ;; from the adornment that is given to us.
1452 ;; There is some sectioning already present, so check if the current
1453 ;; sectioning is complete and correct.
1454 (let* ((char (car ado
))
1456 (indent (caddr ado
))
1457 (endcol (save-excursion (end-of-line) (current-column))))
1459 (let ((exps (rst-re "^" char
(format "\\{%d\\}" (+ endcol indent
)) "$")))
1461 (save-excursion (forward-line +1)
1464 (or (not (eq style
'over-and-under
))
1465 (save-excursion (forward-line -
1)
1467 (looking-at exps
))))))))
1470 (defun rst-get-next-adornment
1471 (curado hier
&optional suggestion reverse-direction
)
1472 "Get the next adornment for CURADO, in given hierarchy HIER.
1473 If suggesting, suggest for new adornment SUGGESTION.
1474 REVERSE-DIRECTION is used to reverse the cycling order."
1478 (style (cadr curado
))
1480 ;; Build a new list of adornments for the rotation.
1483 ;; Suggest a new adornment.
1485 ;; If nothing to suggest, use first adornment.
1488 ;; Search for next adornment.
1490 (let ((cur (if reverse-direction rotados
1491 (reverse rotados
))))
1493 (not (and (eq char
(caar cur
))
1494 (eq style
(cadar cur
)))))
1495 (setq cur
(cdr cur
)))
1498 ;; If not found, take the first of all adornments.
1502 ;; FIXME: A line "``/`` full" is not accepted as a section title.
1503 (defun rst-adjust (pfxarg)
1504 "Auto-adjust the adornment around point.
1506 Adjust/rotate the section adornment for the section title around
1507 point or promote/demote the adornments inside the region,
1508 depending on whether the region is active. This function is meant
1509 to be invoked possibly multiple times, and can vary its behavior
1510 with a positive PFXARG (toggle style), or with a negative
1511 PFXARG (alternate behavior).
1513 This function is a bit of a swiss knife. It is meant to adjust
1514 the adornments of a section title in reStructuredText. It tries
1515 to deal with all the possible cases gracefully and to do `the
1516 right thing' in all cases.
1518 See the documentations of `rst-adjust-adornment-work' and
1519 `rst-promote-region' for full details.
1524 The method can take either (but not both) of
1526 a. a (non-negative) prefix argument, which means to toggle the
1527 adornment style. Invoke with a prefix argument for example;
1529 b. a negative numerical argument, which generally inverts the
1530 direction of search in the file or hierarchy. Invoke with C--
1531 prefix for example."
1534 (let* (;; Save our original position on the current line.
1535 (origpt (point-marker))
1537 (reverse-direction (and pfxarg
(< (prefix-numeric-value pfxarg
) 0)))
1538 (toggle-style (and pfxarg
(not reverse-direction
))))
1541 ;; Adjust adornments within region.
1542 (rst-promote-region (and pfxarg t
))
1543 ;; Adjust adornment around point.
1544 (rst-adjust-adornment-work toggle-style reverse-direction
))
1546 ;; Run the hooks to run after adjusting.
1547 (run-hooks 'rst-adjust-hook
)
1549 ;; Make sure to reset the cursor position properly after we're done.
1550 (goto-char origpt
)))
1552 (defcustom rst-adjust-hook nil
1553 "Hooks to be run after running `rst-adjust'."
1556 :package-version
'(rst .
"1.1.0"))
1557 (rst-testcover-defcustom)
1559 (defcustom rst-new-adornment-down nil
1560 "Controls level of new adornment for section headers."
1563 (const :tag
"Same level as previous one" nil
)
1564 (const :tag
"One level down relative to the previous one" t
))
1565 :package-version
'(rst .
"1.1.0"))
1566 (rst-testcover-defcustom)
1568 (defun rst-adjust-adornment (pfxarg)
1569 "Call `rst-adjust-adornment-work' interactively.
1571 Keep this for compatibility for older bindings (are there any?).
1572 Argument PFXARG has the same meaning as for `rst-adjust'."
1575 (let* ((reverse-direction (and pfxarg
(< (prefix-numeric-value pfxarg
) 0)))
1576 (toggle-style (and pfxarg
(not reverse-direction
))))
1577 (rst-adjust-adornment-work toggle-style reverse-direction
)))
1579 (defun rst-adjust-adornment-work (toggle-style reverse-direction
)
1580 "Adjust/rotate the section adornment for the section title around point.
1582 This function is meant to be invoked possibly multiple times, and
1583 can vary its behavior with a true TOGGLE-STYLE argument, or with
1584 a REVERSE-DIRECTION argument.
1589 The next action it takes depends on context around the point, and
1590 it is meant to be invoked possibly more than once to rotate among
1591 the various possibilities. Basically, this function deals with:
1593 - adding a adornment if the title does not have one;
1595 - adjusting the length of the underline characters to fit a
1598 - rotating the adornment in the set of already existing
1599 sectioning adornments used in the file;
1601 - switching between simple and over-and-under styles.
1603 You should normally not have to read all the following, just
1604 invoke the method and it will do the most obvious thing that you
1608 Adornment Definitions
1609 =====================
1611 The adornments consist in
1615 2. a STYLE which can be either `simple' or `over-and-under'.
1617 3. an INDENT (meaningful for the over-and-under style only)
1618 which determines how many characters and over-and-under
1619 style is hanging outside of the title at the beginning and
1622 See source code for mode details.
1625 Detailed Behavior Description
1626 =============================
1628 Here are the gory details of the algorithm (it seems quite
1629 complicated, but really, it does the most obvious thing in all
1630 the particular cases):
1632 Before applying the adornment change, the cursor is placed on
1633 the closest line that could contain a section title.
1635 Case 1: No Adornment
1636 --------------------
1638 If the current line has no adornment around it,
1640 - search backwards for the last previous adornment, and apply
1641 the adornment one level lower to the current line. If there
1642 is no defined level below this previous adornment, we suggest
1643 the most appropriate of the `rst-preferred-adornments'.
1645 If REVERSE-DIRECTION is true, we simply use the previous
1646 adornment found directly.
1648 - if there is no adornment found in the given direction, we use
1649 the first of `rst-preferred-adornments'.
1651 TOGGLE-STYLE forces a toggle of the prescribed adornment style.
1653 Case 2: Incomplete Adornment
1654 ----------------------------
1656 If the current line does have an existing adornment, but the
1657 adornment is incomplete, that is, the underline/overline does
1658 not extend to exactly the end of the title line (it is either
1659 too short or too long), we simply extend the length of the
1660 underlines/overlines to fit exactly the section title.
1662 If TOGGLE-STYLE we toggle the style of the adornment as well.
1664 REVERSE-DIRECTION has no effect in this case.
1666 Case 3: Complete Existing Adornment
1667 -----------------------------------
1669 If the adornment is complete (i.e. the underline (overline)
1670 length is already adjusted to the end of the title line), we
1671 search/parse the file to establish the hierarchy of all the
1672 adornments (making sure not to include the adornment around
1673 point), and we rotate the current title's adornment from within
1674 that list (by default, going *down* the hierarchy that is present
1675 in the file, i.e. to a lower section level). This is meant to be
1676 used potentially multiple times, until the desired adornment is
1677 found around the title.
1679 If we hit the boundary of the hierarchy, exactly one choice from
1680 the list of preferred adornments is suggested/chosen, the first
1681 of those adornment that has not been seen in the file yet (and
1682 not including the adornment around point), and the next
1683 invocation rolls over to the other end of the hierarchy (i.e. it
1684 cycles). This allows you to avoid having to set which character
1687 If REVERSE-DIRECTION is true, the effect is to change the
1688 direction of rotation in the hierarchy of adornments, thus
1689 instead going *up* the hierarchy.
1691 However, if TOGGLE-STYLE, we do not rotate the adornment, but
1692 instead simply toggle the style of the current adornment (this
1693 should be the most common way to toggle the style of an existing
1694 complete adornment).
1700 The invocation of this function can be carried out anywhere
1701 within the section title line, on an existing underline or
1702 overline, as well as on an empty line following a section title.
1703 This is meant to be as convenient as possible.
1709 Indented section titles such as ::
1714 are invalid in reStructuredText and thus not recognized by the
1715 parser. This code will thus not work in a way that would support
1716 indented sections (it would be ambiguous anyway).
1722 Section titles that are right next to each other may not be
1723 treated well. More work might be needed to support those, and
1724 special conditions on the completeness of existing adornments
1725 might be required to make it non-ambiguous.
1727 For now we assume that the adornments are disjoint, that is,
1728 there is at least a single line between the titles/adornment
1730 (rst-reset-section-caches)
1731 (let ((ttl-fnd (rst-find-title-line))
1734 (set-match-data (cdr ttl-fnd
))
1735 (goto-char (match-beginning 2))
1736 (let* ((moved (- (line-number-at-pos) (line-number-at-pos orig-pnt
)))
1737 (char (caar ttl-fnd
))
1738 (style (cdar ttl-fnd
))
1739 (indent (current-indentation))
1740 (curado (list char style indent
))
1741 char-new style-new indent-new
)
1743 ;;-------------------------------------------------------------------
1744 ;; Case 1: No valid adornment
1746 (let ((prev (car (rst-get-adornments-around)))
1748 (hier (rst-get-hierarchy)))
1749 ;; Advance one level down.
1752 (if (or (and rst-new-adornment-down reverse-direction
)
1753 (and (not rst-new-adornment-down
)
1754 (not reverse-direction
)))
1756 (or (cadr (rst-get-adornment-match hier prev
))
1757 (rst-suggest-new-adornment hier prev
)))
1758 (copy-sequence (car rst-preferred-adornments
))))
1759 ;; Invert the style if requested.
1761 (setcar (cdr cur
) (if (eq (cadr cur
) 'simple
)
1762 'over-and-under
'simple
)) )
1763 (setq char-new
(car cur
)
1764 style-new
(cadr cur
)
1765 indent-new
(caddr cur
))))
1766 ;;-------------------------------------------------------------------
1767 ;; Case 2: Incomplete Adornment
1768 ((not (rst-adornment-complete-p curado
))
1769 ;; Invert the style if requested.
1771 (setq style
(if (eq style
'simple
) 'over-and-under
'simple
)))
1775 ;;-------------------------------------------------------------------
1776 ;; Case 3: Complete Existing Adornment
1779 ;; Simply switch the style of the current adornment.
1781 style-new
(if (eq style
'simple
) 'over-and-under
'simple
)
1782 indent-new rst-default-indent
)
1783 ;; Else, we rotate, ignoring the adornment around the current
1785 (let* ((hier (rst-get-hierarchy (line-number-at-pos)))
1786 ;; Suggestion, in case we need to come up with something new.
1787 (suggestion (rst-suggest-new-adornment
1789 (car (rst-get-adornments-around))))
1790 (nextado (rst-get-next-adornment
1791 curado hier suggestion reverse-direction
)))
1792 ;; Indent, if present, always overrides the prescribed indent.
1793 (setq char-new
(car nextado
)
1794 style-new
(cadr nextado
)
1795 indent-new
(caddr nextado
))))))
1796 ;; Override indent with present indent!
1797 (setq indent-new
(if (> indent
0) indent indent-new
))
1798 (if (and char-new style-new
)
1799 (rst-update-section char-new style-new indent-new
))
1800 ;; Correct the position of the cursor to more accurately reflect where
1801 ;; it was located when the function was invoked.
1802 (unless (zerop moved
)
1803 (forward-line (- moved
))
1806 ;; Maintain an alias for compatibility.
1807 (defalias 'rst-adjust-section-title
'rst-adjust
)
1810 (defun rst-promote-region (demote)
1811 "Promote the section titles within the region.
1813 With argument DEMOTE or a prefix argument, demote the section
1814 titles instead. The algorithm used at the boundaries of the
1815 hierarchy is similar to that used by `rst-adjust-adornment-work'."
1817 (rst-reset-section-caches)
1818 (let* ((cur (rst-find-all-adornments))
1819 (hier (rst-get-hierarchy))
1820 (suggestion (rst-suggest-new-adornment hier
))
1822 (region-begin-line (line-number-at-pos (region-beginning)))
1823 (region-end-line (line-number-at-pos (region-end)))
1827 ;; Skip the markers that come before the region beginning.
1828 (while (and cur
(< (caar cur
) region-begin-line
))
1829 (setq cur
(cdr cur
)))
1831 ;; Create a list of markers for all the adornments which are found within
1835 (while (and cur
(< (setq line
(caar cur
)) region-end-line
))
1836 (goto-char (point-min))
1837 (forward-line (1- line
))
1838 (push (list (point-marker) (cdar cur
)) marker-list
)
1839 (setq cur
(cdr cur
)) ))
1841 ;; Apply modifications.
1842 (dolist (p marker-list
)
1843 ;; Go to the adornment to promote.
1846 ;; Update the adornment.
1847 (apply 'rst-update-section
1848 ;; Rotate the next adornment.
1849 (rst-get-next-adornment
1850 (cadr p
) hier suggestion demote
))
1852 ;; Clear marker to avoid slowing down the editing after we're done.
1853 (set-marker (car p
) nil
))
1854 (setq deactivate-mark nil
))))
1858 (defun rst-display-adornments-hierarchy (&optional adornments
)
1859 "Display the current file's section title adornments hierarchy.
1860 This function expects a list of (CHARACTER STYLE INDENT) triples
1863 (rst-reset-section-caches)
1864 (if (not adornments
)
1865 (setq adornments
(rst-get-hierarchy)))
1866 (with-output-to-temp-buffer "*rest section hierarchy*"
1868 (with-current-buffer standard-output
1869 (dolist (x adornments
)
1870 (insert (format "\nSection Level %d" level
))
1871 (apply 'rst-update-section x
)
1872 (goto-char (point-max))
1876 (defun rst-straighten-adornments ()
1877 "Redo all the adornments in the current buffer.
1878 This is done using our preferred set of adornments. This can be
1879 used, for example, when using somebody else's copy of a document,
1880 in order to adapt it to our preferred style."
1882 (rst-reset-section-caches)
1884 (let (;; Get a list of pairs of (level . marker).
1885 (levels-and-markers (mapcar
1887 (cons (rst-position (cdr ado
)
1888 (rst-get-hierarchy))
1890 (goto-char (point-min))
1891 (forward-line (1- (car ado
)))
1893 (rst-find-all-adornments))))
1894 (dolist (lm levels-and-markers
)
1895 ;; Go to the appropriate position.
1896 (goto-char (cdr lm
))
1898 ;; Apply the new style.
1899 (apply 'rst-update-section
(nth (car lm
) rst-preferred-adornments
))
1901 ;; Reset the marker to avoid slowing down editing until it gets GC'ed.
1902 (set-marker (cdr lm
) nil
)))))
1905 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1906 ;; Insert list items
1907 ;; =================
1910 ;=================================================
1911 ; Borrowed from a2r.el (version 1.3), by Lawrence Mitchell <wence@gmx.li>.
1912 ; I needed to make some tiny changes to the functions, so I put it here.
1915 (defconst rst-arabic-to-roman
1916 '((1000 .
"M") (900 .
"CM") (500 .
"D") (400 .
"CD")
1917 (100 .
"C") (90 .
"XC") (50 .
"L") (40 .
"XL")
1918 (10 .
"X") (9 .
"IX") (5 .
"V") (4 .
"IV")
1920 "List of maps between Arabic numbers and their Roman numeral equivalents.")
1922 (defun rst-arabic-to-roman (num &optional arg
)
1923 "Convert Arabic number NUM to its Roman numeral representation.
1925 Obviously, NUM must be greater than zero. Don't blame me, blame the
1926 Romans, I mean \"what have the Romans ever _done_ for /us/?\" (with
1927 apologies to Monty Python).
1928 If optional ARG is non-nil, insert in current buffer."
1929 (let ((map rst-arabic-to-roman
)
1931 (while (and map
(> num
0))
1932 (if (or (= num
(caar map
))
1934 (setq res
(concat res
(cdar map
))
1935 num
(- num
(caar map
)))
1936 (setq map
(cdr map
))))
1937 (if arg
(insert (or res
"")) res
)))
1939 (defun rst-roman-to-arabic (string &optional arg
)
1940 "Convert STRING of Roman numerals to an Arabic number.
1942 If STRING contains a letter which isn't a valid Roman numeral,
1943 the rest of the string from that point onwards is ignored.
1949 If optional ARG is non-nil, insert in current buffer."
1951 (map rst-arabic-to-roman
))
1953 (if (string-match (concat "^" (cdar map
)) string
)
1954 (setq res
(+ res
(caar map
))
1955 string
(replace-match "" nil t string
))
1956 (setq map
(cdr map
))))
1957 (if arg
(insert res
) res
)))
1958 ;=================================================
1960 (defun rst-find-pfx-in-region (beg end pfx-re
)
1961 "Find all the positions of prefixes in region between BEG and END.
1962 This is used to find bullets and enumerated list items. PFX-RE is
1963 a regular expression for matching the lines after indentation
1964 with items. Returns a list of cons cells consisting of the point
1965 and the column of the point."
1969 (while (< (point) end
)
1970 (back-to-indentation)
1972 (looking-at pfx-re
) ; pfx found and...
1973 (let ((pfx-col (current-column)))
1975 (forward-line -
1) ; ...previous line is...
1976 (back-to-indentation)
1977 (or (looking-at (rst-re 'lin-end
)) ; ...empty,
1978 (> (current-column) pfx-col
) ; ...deeper level, or
1979 (and (= (current-column) pfx-col
)
1980 (looking-at pfx-re
)))))) ; ...pfx at same level.
1981 (push (cons (point) (current-column))
1986 (defun rst-insert-list-pos (newitem)
1987 "Arrange relative position of a newly inserted list item of style NEWITEM.
1989 Adding a new list might consider three situations:
1991 (a) Current line is a blank line.
1992 (b) Previous line is a blank line.
1993 (c) Following line is a blank line.
1995 When (a) and (b), just add the new list at current line.
1997 when (a) and not (b), a blank line is added before adding the new list.
1999 When not (a), first forward point to the end of the line, and add two
2000 blank lines, then add the new list.
2002 Other situations are just ignored and left to users themselves."
2005 (looking-at (rst-re 'lin-end
)))
2008 (looking-at (rst-re 'lin-end
)))
2009 (insert newitem
" ")
2010 (insert "\n" newitem
" "))
2012 (insert "\n\n" newitem
" ")))
2014 ;; FIXME: Isn't this a `defconst'?
2015 (defvar rst-initial-enums
2017 (dolist (fmt '("%s." "(%s)" "%s)"))
2018 (dolist (c '("1" "a" "A" "I" "i"))
2019 (push (format fmt c
) vals
)))
2020 (cons "#." (nreverse vals
)))
2021 "List of initial enumerations.")
2023 ;; FIXME: Isn't this a `defconst'?
2024 (defvar rst-initial-items
2025 (append (mapcar 'char-to-string rst-bullets
) rst-initial-enums
)
2026 "List of initial items. It's a collection of bullets and enumerations.")
2028 (defun rst-insert-list-new-item ()
2029 "Insert a new list item.
2031 User is asked to select the item style first, for example (a), i), +.
2032 Use TAB for completion and choices.
2034 If user selects bullets or #, it's just added with position arranged by
2035 `rst-insert-list-pos'.
2037 If user selects enumerations, a further prompt is given. User need to
2038 input a starting item, for example 'e' for 'A)' style. The position is
2039 also arranged by `rst-insert-list-pos'."
2041 ;; FIXME: Make this comply to `interactive' standards.
2042 (let* ((itemstyle (completing-read
2043 "Select preferred item style [#.]: "
2044 rst-initial-items nil t nil nil
"#."))
2045 (cnt (if (string-match (rst-re 'cntexp-tag
) itemstyle
)
2046 (match-string 0 itemstyle
)))
2049 ;; FIXME: Make this comply to `interactive' standards.
2052 (let ((itemno (read-string "Give starting value [a]: "
2054 (downcase (substring itemno
0 1))))
2056 (let ((itemno (read-string "Give starting value [A]: "
2058 (upcase (substring itemno
0 1))))
2060 (let ((itemno (read-number "Give starting value [1]: " 1)))
2061 (rst-arabic-to-roman itemno
)))
2063 (let ((itemno (read-number "Give starting value [1]: " 1)))
2064 (downcase (rst-arabic-to-roman itemno
))))
2066 (let ((itemno (read-number "Give starting value [1]: " 1)))
2067 (number-to-string itemno
)))))))
2069 (setq itemstyle
(replace-match no t t itemstyle
)))
2070 (rst-insert-list-pos itemstyle
)))
2072 (defcustom rst-preferred-bullets
2074 "List of favorite bullets."
2077 (choice ,@(mapcar (lambda (char)
2079 :tag
(char-to-string char
) char
))
2081 :package-version
'(rst .
"1.1.0"))
2082 (rst-testcover-defcustom)
2084 (defun rst-insert-list-continue (curitem prefer-roman
)
2085 "Insert a list item with list start CURITEM including its indentation level.
2086 If PREFER-ROMAN roman numbering is preferred over using letters."
2089 "\n" ; FIXME: Separating lines must be possible.
2091 ((string-match (rst-re '(:alt enmaut-tag
2094 ((string-match (rst-re 'num-tag
) curitem
)
2095 (replace-match (number-to-string
2096 (1+ (string-to-number (match-string 0 curitem
))))
2098 ((and (string-match (rst-re 'rom-tag
) curitem
)
2100 (if (string-match (rst-re 'ltr-tag
) curitem
) ; Also a letter tag.
2102 ;; FIXME: Assumes one line list items without separating
2104 (if (and (zerop (forward-line -
1))
2105 (looking-at (rst-re 'enmexp-beg
)))
2108 (match-string 0)) ; Previous was a roman tag.
2109 prefer-roman
)) ; Don't know - use flag.
2110 t
))) ; Not a letter tag.
2112 (let* ((old (match-string 0 curitem
))
2113 (new (save-match-data
2114 (rst-arabic-to-roman
2115 (1+ (rst-roman-to-arabic
2117 (if (equal old
(upcase old
))
2121 ((string-match (rst-re 'ltr-tag
) curitem
)
2122 (replace-match (char-to-string
2123 (1+ (string-to-char (match-string 0 curitem
))))
2124 nil nil curitem
)))))
2127 (defun rst-insert-list (&optional prefer-roman
)
2128 "Insert a list item at the current point.
2130 The command can insert a new list or a continuing list. When it is called at a
2131 non-list line, it will promote to insert new list. When it is called at a list
2132 line, it will insert a list with the same list style.
2134 1. When inserting a new list:
2136 User is asked to select the item style first, for example (a), i), +. Use TAB
2137 for completion and choices.
2139 (a) If user selects bullets or #, it's just added.
2140 (b) If user selects enumerations, a further prompt is given. User needs to
2141 input a starting item, for example 'e' for 'A)' style.
2143 The position of the new list is arranged according to whether or not the
2144 current line and the previous line are blank lines.
2146 2. When continuing a list, one thing needs to be noticed:
2148 List style alphabetical list, such as 'a.', and roman numerical list, such as
2149 'i.', have some overlapping items, for example 'v.' The function can deal with
2150 the problem elegantly in most situations. But when those overlapped list are
2151 preceded by a blank line, it is hard to determine which type to use
2152 automatically. The function uses alphabetical list by default. If you want
2153 roman numerical list, just use a prefix to set PREFER-ROMAN."
2156 (if (looking-at (rst-re 'itmany-beg-1
))
2157 (rst-insert-list-continue (match-string 0) prefer-roman
)
2158 (rst-insert-list-new-item)))
2160 (defun rst-straighten-bullets-region (beg end
)
2161 "Make all the bulleted list items in the region consistent.
2162 The region is specified between BEG and END. You can use this
2163 after you have merged multiple bulleted lists to make them use
2164 the same/correct/consistent bullet characters.
2166 See variable `rst-preferred-bullets' for the list of bullets to
2167 adjust. If bullets are found on levels beyond the
2168 `rst-preferred-bullets' list, they are not modified."
2171 (let ((bullets (rst-find-pfx-in-region beg end
(rst-re 'bul-sta
)))
2172 (levtable (make-hash-table :size
4)))
2174 ;; Create a map of levels to list of positions.
2176 (let ((key (cdr x
)))
2178 (append (gethash key levtable
(list))
2182 ;; Sort this map and create a new map of prefix char and list of positions.
2183 (let ((poslist ())) ; List of (indent . positions).
2184 (maphash (lambda (x y
) (push (cons x y
) poslist
)) levtable
)
2186 (let ((bullets rst-preferred-bullets
))
2187 (dolist (x (sort poslist
'car-less-than-car
))
2189 ;; Apply the characters.
2190 (dolist (pos (cdr x
))
2193 (insert (string (car bullets
))))
2194 (setq bullets
(cdr bullets
))))))))
2197 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2198 ;; Table of contents
2199 ;; =================
2201 ;; FIXME: Return value should be a `defstruct'.
2202 (defun rst-section-tree ()
2203 "Return the hierarchical tree of section titles.
2204 A tree entry looks like ((TITLE MARKER) CHILD...). TITLE is the
2205 stripped text of the section title. MARKER is a marker for the
2206 beginning of the title text. For the top node or a missing
2207 section level node TITLE is nil and MARKER points to the title
2208 text of the first child. Each CHILD is another tree entry. The
2209 CHILD list may be empty."
2210 (let ((hier (rst-get-hierarchy))
2211 (ch-sty2level (make-hash-table :test
'equal
:size
10))
2216 ;; Compare just the character and indent in the hash table.
2217 (puthash (cons (car ado
) (cadr ado
)) lev ch-sty2level
)
2220 ;; Create a list that contains (LEVEL TITLE MARKER) for each adornment.
2223 (mapcar (lambda (ado)
2224 (goto-char (point-min))
2225 (1value ;; This should really succeed.
2226 (forward-line (1- (car ado
))))
2227 (list (gethash (cons (cadr ado
) (caddr ado
)) ch-sty2level
)
2230 (if (re-search-forward
2231 (rst-re "\\S .*\\S ") (line-end-position) t
)
2232 (buffer-substring-no-properties
2233 (match-beginning 0) (match-end 0))
2236 (rst-find-all-adornments))))
2237 (cdr (rst-section-tree-rec lev-ttl-mrk-l -
1))))
2239 ;; FIXME: Return value should be a `defstruct'.
2240 (defun rst-section-tree-rec (remaining lev
)
2241 "Process the first entry of REMAINING expected to be on level LEV.
2242 REMAINING is the remaining list of adornments consisting
2243 of (LEVEL TITLE MARKER) entries.
2245 Return (UNPROCESSED (TITLE MARKER) CHILD...) for the first entry
2246 of REMAINING where TITLE is nil if the expected level is not
2247 matched. UNPROCESSED is the list of still unprocessed entries.
2248 Each CHILD is a child of this entry in the same format but
2249 without UNPROCESSED."
2250 (let ((cur (car remaining
))
2251 (unprocessed remaining
)
2253 ;; If the current adornment matches expected level.
2254 (when (and cur
(= (car cur
) lev
))
2255 ;; Consume the current entry and create the current node with it.
2256 (setq unprocessed
(cdr remaining
))
2257 (setq ttl-mrk
(cdr cur
)))
2259 ;; Build the child nodes as long as they have deeper level.
2260 (while (and unprocessed
(> (caar unprocessed
) lev
))
2261 (let ((rem-children (rst-section-tree-rec unprocessed
(1+ lev
))))
2262 (setq children
(cons (cdr rem-children
) children
))
2263 (setq unprocessed
(car rem-children
))))
2264 (setq children
(reverse children
))
2268 ;; Node on this level missing - use nil as text and the
2269 ;; marker of the first child.
2270 (cons nil
(cdaar children
)))
2273 (defun rst-section-tree-point (tree &optional point
)
2274 "Return section containing POINT by returning the closest node in TREE.
2275 TREE is a section tree as returned by `rst-section-tree'
2276 consisting of (NODE CHILD...) entries. POINT defaults to the
2277 current point. A NODE must have the structure (IGNORED MARKER...).
2279 Return (PATH NODE CHILD...). NODE is the node where POINT is in
2280 if any. PATH is a list of nodes from the top of the tree down to
2281 and including NODE. List of CHILD are the children of NODE if any."
2282 (setq point
(or point
(point)))
2283 (let ((cur (car tree
))
2284 (children (cdr tree
)))
2285 ;; Point behind current node?
2286 (if (and (cadr cur
) (>= point
(cadr cur
)))
2287 ;; Iterate all the children, looking for one that might contain the
2290 (while (and children
(>= point
(cadaar children
)))
2291 (setq found children
2292 children
(cdr children
)))
2294 ;; Found section containing point in children.
2295 (let ((sub (rst-section-tree-point (car found
) point
)))
2296 ;; Extend path with current node and return NODE CHILD... from
2298 (cons (cons cur
(car sub
)) (cdr sub
)))
2299 ;; Point in this section: Start a new path with current node and
2300 ;; return current NODE CHILD...
2301 (cons (list cur
) tree
)))
2302 ;; Current node behind point: start a new path with current node and
2304 (list (list cur
)))))
2306 (defgroup rst-toc nil
2307 "Settings for reStructuredText table of contents."
2311 (defcustom rst-toc-indent
2
2312 "Indentation for table-of-contents display.
2313 Also used for formatting insertion, when numbering is disabled."
2316 (rst-testcover-defcustom)
2318 (defcustom rst-toc-insert-style
'fixed
2319 "Insertion style for table-of-contents.
2320 Set this to one of the following values to determine numbering and
2322 - `plain': no numbering (fixed indentation)
2323 - `fixed': numbering, but fixed indentation
2324 - `aligned': numbering, titles aligned under each other
2325 - `listed': numbering, with dashes like list items (EXPERIMENTAL)"
2326 :type
'(choice (const plain
)
2331 (rst-testcover-defcustom)
2333 (defcustom rst-toc-insert-number-separator
" "
2334 "Separator that goes between the TOC number and the title."
2337 (rst-testcover-defcustom)
2339 ;; This is used to avoid having to change the user's mode.
2340 (defvar rst-toc-insert-click-keymap
2341 (let ((map (make-sparse-keymap)))
2342 (define-key map
[mouse-1
] 'rst-toc-mode-mouse-goto
)
2344 "(Internal) What happens when you click on propertized text in the TOC.")
2346 (defcustom rst-toc-insert-max-level nil
2347 "If non-nil, maximum depth of the inserted TOC."
2348 :type
'(choice (const nil
) integer
)
2350 (rst-testcover-defcustom)
2352 (defun rst-toc-insert (&optional pfxarg
)
2353 "Insert a simple text rendering of the table of contents.
2354 By default the top level is ignored if there is only one, because
2355 we assume that the document will have a single title.
2357 If a numeric prefix argument PFXARG is given, insert the TOC up
2358 to the specified level.
2360 The TOC is inserted indented at the current column."
2362 (rst-reset-section-caches)
2363 (let* (;; Check maximum level override.
2364 (rst-toc-insert-max-level
2365 (if (and (integerp pfxarg
) (> (prefix-numeric-value pfxarg
) 0))
2366 (prefix-numeric-value pfxarg
) rst-toc-insert-max-level
))
2368 ;; Get the section tree for the current cursor point.
2370 (rst-section-tree-point
2371 (rst-section-tree)))
2373 ;; Figure out initial indent.
2374 (initial-indent (make-string (current-column) ?
))
2375 (init-point (point)))
2377 (when (cddr sectree-pair
)
2378 (rst-toc-insert-node (cdr sectree-pair
) 0 initial-indent
"")
2380 ;; Fixup for the first line.
2381 (delete-region init-point
(+ init-point
(length initial-indent
)))
2383 ;; Delete the last newline added.
2386 (defun rst-toc-insert-node (node level indent pfx
)
2387 "Insert tree node NODE in table-of-contents.
2388 Recursive function that does printing of the inserted TOC.
2389 LEVEL is the depth level of the sections in the tree.
2390 INDENT is the indentation string. PFX is the prefix numbering,
2391 that includes the alignment necessary for all the children of
2394 ;; Note: we do child numbering from the parent, so we start number the
2395 ;; children one level before we print them.
2396 (let ((do-print (> level
0))
2401 (unless (equal rst-toc-insert-style
'plain
)
2402 (insert pfx rst-toc-insert-number-separator
))
2403 (insert (or (caar node
) "[missing node]"))
2404 ;; Add properties to the text, even though in normal text mode it
2405 ;; won't be doing anything for now. Not sure that I want to change
2406 ;; mode stuff. At least the highlighting gives the idea that this
2407 ;; is generated automatically.
2408 (put-text-property b
(point) 'mouse-face
'highlight
)
2409 (put-text-property b
(point) 'rst-toc-target
(cadar node
))
2410 (put-text-property b
(point) 'keymap rst-toc-insert-click-keymap
))
2413 ;; Prepare indent for children.
2416 ((eq rst-toc-insert-style
'plain
)
2417 (concat indent
(make-string rst-toc-indent ?
)))
2419 ((eq rst-toc-insert-style
'fixed
)
2420 (concat indent
(make-string rst-toc-indent ?
)))
2422 ((eq rst-toc-insert-style
'aligned
)
2423 (concat indent
(make-string (+ (length pfx
) 2) ?
)))
2425 ((eq rst-toc-insert-style
'listed
)
2426 (concat (substring indent
0 -
3)
2427 (concat (make-string (+ (length pfx
) 2) ?
) " - "))))))
2429 (if (or (eq rst-toc-insert-max-level nil
)
2430 (< level rst-toc-insert-max-level
))
2431 (let ((do-child-numbering (>= level
0))
2433 (if do-child-numbering
2435 ;; Add a separating dot if there is already a prefix.
2436 (when (> (length pfx
) 0)
2437 (string-match (rst-re "[ \t\n]*\\'") pfx
)
2438 (setq pfx
(concat (replace-match "" t t pfx
) ".")))
2440 ;; Calculate the amount of space that the prefix will require
2443 (setq fmt
(format "%%-%dd"
2444 (1+ (floor (log (length (cdr node
))
2447 (dolist (child (cdr node
))
2448 (rst-toc-insert-node child
2451 (if do-child-numbering
2452 (concat pfx
(format fmt count
)) pfx
))
2456 (defun rst-toc-update ()
2457 "Automatically find the contents section of a document and update.
2458 Updates the inserted TOC if present. You can use this in your
2459 file-write hook to always make it up-to-date automatically."
2462 ;; Find and delete an existing comment after the first contents directive.
2463 ;; Delete that region.
2464 (goto-char (point-min))
2465 ;; We look for the following and the following only (in other words, if your
2466 ;; syntax differs, this won't work.).
2468 ;; .. contents:: [...anything here...]
2469 ;; [:field: value]...
2474 (let ((beg (re-search-forward
2475 (rst-re "^" 'exm-sta
"contents" 'dcl-tag
".*\n"
2476 "\\(?:" 'hws-sta
'fld-tag
".*\n\\)*" 'exm-tag
) nil t
))
2479 ;; Look for the first line that starts at the first column.
2482 (< (point) (point-max))
2484 (rst-re 'hws-sta
"\\S ")) ; indented content.
2485 (setq last-real
(point)))
2486 (looking-at (rst-re 'lin-end
)))) ; empty line.
2490 (goto-char last-real
)
2492 (delete-region beg
(point)))
2496 ;; Note: always return nil, because this may be used as a hook.
2499 ;; Note: we cannot bind the TOC update on file write because it messes with
2500 ;; undo. If we disable undo, since it adds and removes characters, the
2501 ;; positions in the undo list are not making sense anymore. Dunno what to do
2502 ;; with this, it would be nice to update when saving.
2504 ;; (add-hook 'write-contents-hooks 'rst-toc-update-fun)
2505 ;; (defun rst-toc-update-fun ()
2506 ;; ;; Disable undo for the write file hook.
2507 ;; (let ((buffer-undo-list t)) (rst-toc-update) ))
2509 (defalias 'rst-toc-insert-update
'rst-toc-update
) ; backwards compat.
2511 ;;------------------------------------------------------------------------------
2513 (defun rst-toc-node (node level
)
2514 "Recursive function that does insert NODE at LEVEL in the table-of-contents."
2518 ;; Insert line text.
2519 (insert (make-string (* rst-toc-indent
(1- level
)) ?
))
2520 (insert (or (caar node
) "[missing node]"))
2523 (put-text-property b
(point) 'mouse-face
'highlight
)
2525 ;; Add link on lines.
2526 (put-text-property b
(point) 'rst-toc-target
(cadar node
))
2530 (dolist (child (cdr node
))
2531 (rst-toc-node child
(1+ level
))))
2533 (defun rst-toc-count-lines (node target-node
)
2534 "Count the number of lines from NODE to the TARGET-NODE node.
2535 This recursive function returns a cons of the number of
2536 additional lines that have been counted for its node and
2537 children, and t if the node has been found."
2541 (if (eq node target-node
)
2543 (let ((child (cdr node
)))
2544 (while (and child
(not found
))
2545 (let ((cl (rst-toc-count-lines (car child
) target-node
)))
2546 (setq count
(+ count
(car cl
))
2548 child
(cdr child
))))))
2549 (cons count found
)))
2551 (defvar rst-toc-buffer-name
"*Table of Contents*"
2552 "Name of the Table of Contents buffer.")
2554 (defvar rst-toc-return-wincfg nil
2555 "Window configuration to which to return when leaving the TOC.")
2559 "Display a table-of-contents.
2560 Finds all the section titles and their adornments in the
2561 file, and displays a hierarchically-organized list of the
2562 titles, which is essentially a table-of-contents of the
2565 The Emacs buffer can be navigated, and selecting a section
2566 brings the cursor in that section."
2568 (rst-reset-section-caches)
2569 (let* ((curbuf (list (current-window-configuration) (point-marker)))
2570 (sectree (rst-section-tree))
2572 (our-node (cdr (rst-section-tree-point sectree
)))
2575 ;; Create a temporary buffer.
2576 (buf (get-buffer-create rst-toc-buffer-name
)))
2578 (with-current-buffer buf
2579 (let ((inhibit-read-only t
))
2581 (delete-region (point-min) (point-max))
2582 (insert (format "Table of Contents: %s\n" (or (caar sectree
) "")))
2583 (put-text-property (point-min) (point)
2584 'face
(list '(background-color .
"gray")))
2585 (rst-toc-node sectree
0)
2587 ;; Count the lines to our found node.
2588 (let ((linefound (rst-toc-count-lines sectree our-node
)))
2589 (setq line
(if (cdr linefound
) (car linefound
) 0)))))
2590 (display-buffer buf
)
2593 ;; Save the buffer to return to.
2594 (set (make-local-variable 'rst-toc-return-wincfg
) curbuf
)
2596 ;; Move the cursor near the right section in the TOC.
2597 (goto-char (point-min))
2598 (forward-line (1- line
))))
2601 (defun rst-toc-mode-find-section ()
2602 "Get the section from text property at point."
2603 (let ((pos (get-text-property (point) 'rst-toc-target
)))
2605 (error "No section on this line"))
2606 (unless (buffer-live-p (marker-buffer pos
))
2607 (error "Buffer for this section was killed"))
2610 ;; FIXME: Cursor before or behind the list must be handled properly; before the
2611 ;; list should jump to the top and behind the list to the last normal
2613 (defun rst-goto-section (&optional kill
)
2614 "Go to the section the current line describes.
2615 If KILL a TOC buffer is destroyed."
2617 (let ((pos (rst-toc-mode-find-section)))
2619 ;; FIXME: This should rather go to `rst-toc-mode-goto-section'.
2620 (set-window-configuration (car rst-toc-return-wincfg
))
2621 (kill-buffer (get-buffer rst-toc-buffer-name
)))
2622 (pop-to-buffer (marker-buffer pos
))
2624 ;; FIXME: make the recentering conditional on scroll.
2627 (defun rst-toc-mode-goto-section ()
2628 "Go to the section the current line describes and kill the TOC buffer."
2630 (rst-goto-section t
))
2632 (defun rst-toc-mode-mouse-goto (event)
2633 "In `rst-toc' mode, go to the occurrence whose line you click on.
2634 EVENT is the input event."
2637 (with-current-buffer (window-buffer (posn-window (event-end event
)))
2639 (goto-char (posn-point (event-end event
)))
2640 (rst-toc-mode-find-section)))))
2641 (pop-to-buffer (marker-buffer pos
))
2645 (defun rst-toc-mode-mouse-goto-kill (event)
2646 "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well.
2647 EVENT is the input event."
2649 (call-interactively 'rst-toc-mode-mouse-goto event
)
2650 (kill-buffer (get-buffer rst-toc-buffer-name
)))
2652 (defun rst-toc-quit-window ()
2653 "Leave the current TOC buffer."
2655 (let ((retbuf rst-toc-return-wincfg
))
2656 (set-window-configuration (car retbuf
))
2657 (goto-char (cadr retbuf
))))
2659 (defvar rst-toc-mode-map
2660 (let ((map (make-sparse-keymap)))
2661 (define-key map
[mouse-1
] 'rst-toc-mode-mouse-goto-kill
)
2662 (define-key map
[mouse-2
] 'rst-toc-mode-mouse-goto
)
2663 (define-key map
"\C-m" 'rst-toc-mode-goto-section
)
2664 (define-key map
"f" 'rst-toc-mode-goto-section
)
2665 (define-key map
"q" 'rst-toc-quit-window
)
2666 (define-key map
"z" 'kill-this-buffer
)
2668 "Keymap for `rst-toc-mode'.")
2670 (put 'rst-toc-mode
'mode-class
'special
)
2672 ;; Could inherit from the new `special-mode'.
2673 (define-derived-mode rst-toc-mode nil
"ReST-TOC"
2674 "Major mode for output from \\[rst-toc], the table-of-contents for the document."
2675 (setq buffer-read-only t
))
2677 ;; Note: use occur-mode (replace.el) as a good example to complete missing
2680 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2681 ;; Section movement commands
2682 ;; =========================
2684 (defun rst-forward-section (&optional offset
)
2685 "Skip to the next reStructuredText section title.
2686 OFFSET specifies how many titles to skip. Use a negative OFFSET
2687 to move backwards in the file (default is to use 1)."
2689 (rst-reset-section-caches)
2690 (let* (;; Default value for offset.
2691 (offset (or offset
1))
2693 ;; Get all the adornments in the file, with their line numbers.
2694 (allados (rst-find-all-adornments))
2696 ;; Get the current line.
2697 (curline (line-number-at-pos))
2702 ;; Find the index of the "next" adornment w.r.t. to the current line.
2703 (while (and cur
(< (caar cur
) curline
))
2704 (setq cur
(cdr cur
))
2706 ;; 'cur' is the adornment on or following the current line.
2708 (if (and (> offset
0) cur
(= (caar cur
) curline
))
2711 ;; Find the final index.
2712 (setq idx
(+ idx
(if (> offset
0) (- offset
1) offset
)))
2713 (setq cur
(nth idx allados
))
2715 ;; If the index is positive, goto the line, otherwise go to the buffer
2717 (if (and cur
(>= idx
0))
2719 (goto-char (point-min))
2720 (forward-line (1- (car cur
))))
2721 (if (> offset
0) (goto-char (point-max)) (goto-char (point-min))))))
2723 (defun rst-backward-section ()
2724 "Like `rst-forward-section', except move back one title."
2726 (rst-forward-section -
1))
2728 ;; FIXME: What is `allow-extend' for?
2729 (defun rst-mark-section (&optional count allow-extend
)
2730 "Select COUNT sections around point.
2731 Mark following sections for positive COUNT or preceding sections
2732 for negative COUNT."
2733 ;; Cloned from mark-paragraph.
2734 (interactive "p\np")
2735 (unless count
(setq count
1))
2737 (error "Cannot mark zero sections"))
2738 (cond ((and allow-extend
2739 (or (and (eq last-command this-command
) (mark t
))
2744 (rst-forward-section count
)
2747 (rst-forward-section count
)
2749 (rst-forward-section (- count
)))))
2752 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2753 ;; Functions to work on item lists (e.g. indent/dedent, enumerate), which are
2754 ;; always 2 or 3 characters apart horizontally with rest.
2756 (defun rst-find-leftmost-column (beg end
)
2757 "Return the leftmost column in region BEG to END."
2761 (while (< (point) end
)
2762 (back-to-indentation)
2763 (unless (looking-at (rst-re 'lin-end
))
2764 (setq mincol
(if mincol
2765 (min mincol
(current-column))
2770 ;; FIXME: This definition is old and deprecated. We need to move to the newer
2772 (defmacro rst-iterate-leftmost-paragraphs
2773 (beg end first-only body-consequent body-alternative
)
2774 ;; FIXME: The following comment is pretty useless.
2775 "Call FUN at the beginning of each line, with an argument that
2776 specifies whether we are at the first line of a paragraph that
2777 starts at the leftmost column of the given region BEG and END.
2778 Set FIRST-ONLY to true if you want to callback on the first line
2779 of each paragraph only."
2781 (let ((leftcol (rst-find-leftmost-column ,beg
,end
))
2782 (endm (copy-marker ,end
)))
2784 (do* (;; Iterate lines.
2785 (l (progn (goto-char ,beg
) (back-to-indentation))
2786 (progn (forward-line 1) (back-to-indentation)))
2788 (previous nil valid
)
2790 (curcol (current-column)
2793 (valid (and (= curcol leftcol
)
2794 (not (looking-at (rst-re 'lin-end
))))
2795 (and (= curcol leftcol
)
2796 (not (looking-at (rst-re 'lin-end
))))))
2800 (and valid
(not previous
))
2803 ,body-alternative
)))))
2805 ;; FIXME: This needs to be refactored. Probably this is simply a function
2806 ;; applying BODY rather than a macro.
2807 (defmacro rst-iterate-leftmost-paragraphs-2
(spec &rest body
)
2808 "Evaluate BODY for each line in region defined by BEG END.
2809 LEFTMOST is set to true if the line is one of the leftmost of the
2810 entire paragraph. PARABEGIN is set to true if the line is the
2811 first of a paragraph."
2812 (declare (indent 1) (debug (sexp body
)))
2814 (beg end parabegin leftmost isleftmost isempty
) spec
2817 (let ((,leftmost
(rst-find-leftmost-column ,beg
,end
))
2818 (endm (copy-marker ,end
)))
2820 (do* (;; Iterate lines.
2821 (l (progn (goto-char ,beg
) (back-to-indentation))
2822 (progn (forward-line 1) (back-to-indentation)))
2824 (empty-line-previous nil
,isempty
)
2826 (,isempty
(looking-at (rst-re 'lin-end
))
2827 (looking-at (rst-re 'lin-end
)))
2829 (,parabegin
(not ,isempty
)
2830 (and empty-line-previous
2833 (,isleftmost
(and (not ,isempty
)
2834 (= (current-column) ,leftmost
))
2836 (= (current-column) ,leftmost
))))
2841 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2844 ;; FIXME: At the moment only block comments with leading empty comment line are
2845 ;; supported. Comment lines with leading comment markup should be also
2846 ;; supported. May be a customizable option could control which style to
2849 (defgroup rst-indent nil
"Settings for indentation in reStructuredText.
2851 In reStructuredText indentation points are usually determined by
2852 preceding lines. Sometimes the syntax allows arbitrary indentation
2853 points such as where to start the first line following a directive.
2854 These indentation widths can be customized here."
2856 :package-version
'(rst .
"1.1.0"))
2858 (define-obsolete-variable-alias
2859 'rst-shift-basic-offset
'rst-indent-width
"rst 1.0.0")
2860 (defcustom rst-indent-width
2
2861 "Indentation when there is no more indentation point given."
2864 (rst-testcover-defcustom)
2866 (defcustom rst-indent-field
3
2867 "Indentation for first line after a field or 0 to always indent for content."
2869 :package-version
'(rst .
"1.1.0")
2871 (rst-testcover-defcustom)
2873 (defcustom rst-indent-literal-normal
3
2874 "Default indentation for literal block after a markup on an own line."
2876 :package-version
'(rst .
"1.1.0")
2878 (rst-testcover-defcustom)
2880 (defcustom rst-indent-literal-minimized
2
2881 "Default indentation for literal block after a minimized markup."
2883 :package-version
'(rst .
"1.1.0")
2885 (rst-testcover-defcustom)
2887 (defcustom rst-indent-comment
3
2888 "Default indentation for first line of a comment."
2890 :package-version
'(rst .
"1.1.0")
2892 (rst-testcover-defcustom)
2894 ;; FIXME: Must consider other tabs:
2896 ;; * Definition lists
2898 (defun rst-line-tabs ()
2899 "Return tabs of the current line or nil for no tab.
2900 The list is sorted so the tab where writing continues most likely
2901 is the first one. Each tab is of the form (COLUMN . INNER).
2902 COLUMN is the column of the tab. INNER is non-nil if this is an
2903 inner tab. I.e. a tab which does come from the basic indentation
2904 and not from inner alignment points."
2908 (unless (looking-at (rst-re 'lin-end
))
2909 (back-to-indentation)
2910 ;; Current indentation is always the least likely tab.
2911 (let ((tabs (list (list (point) 0 nil
)))) ; (POINT OFFSET INNER)
2912 ;; Push inner tabs more likely to continue writing.
2915 ((looking-at (rst-re '(:grp itmany-tag hws-sta
) '(:grp
"\\S ") "?"))
2916 (when (match-string 2)
2917 (push (list (match-beginning 2) 0 t
) tabs
)))
2919 ((looking-at (rst-re '(:grp fld-tag
) '(:grp hws-tag
)
2920 '(:grp
"\\S ") "?"))
2921 (unless (zerop rst-indent-field
)
2922 (push (list (match-beginning 1) rst-indent-field t
) tabs
))
2923 (if (match-string 3)
2924 (push (list (match-beginning 3) 0 t
) tabs
)
2925 (if (zerop rst-indent-field
)
2926 (push (list (match-end 2)
2927 (if (string= (match-string 2) "") 1 0)
2930 ((looking-at (rst-re 'dir-sta-3
'(:grp
"\\S ") "?"))
2931 (push (list (match-end 1) 0 t
) tabs
)
2932 (unless (string= (match-string 2) "")
2933 (push (list (match-end 2) 0 t
) tabs
))
2934 (when (match-string 4)
2935 (push (list (match-beginning 4) 0 t
) tabs
)))
2936 ;; Footnote or citation definition.
2937 ((looking-at (rst-re 'fnc-sta-2
'(:grp
"\\S ") "?"))
2938 (push (list (match-end 1) 0 t
) tabs
)
2939 (when (match-string 3)
2940 (push (list (match-beginning 3) 0 t
) tabs
)))
2942 ((looking-at (rst-re 'cmt-sta-1
))
2943 (push (list (point) rst-indent-comment t
) tabs
)))
2944 ;; Start of literal block.
2945 (when (looking-at (rst-re 'lit-sta-2
))
2946 (let ((tab0 (first tabs
)))
2947 (push (list (first tab0
)
2949 (if (match-string 1)
2950 rst-indent-literal-minimized
2951 rst-indent-literal-normal
))
2953 (mapcar (lambda (tab)
2954 (goto-char (first tab
))
2955 (cons (+ (current-column) (second tab
)) (third tab
)))
2958 (defun rst-compute-tabs (pt)
2959 "Build the list of possible tabs for all lines above.
2960 Search backwards from point PT to build the list of possible tabs.
2961 Return a list of tabs sorted by likeliness to continue writing
2962 like `rst-line-tabs'. Nearer lines have generally a higher
2963 likeliness than farther lines. Return nil if no tab is found in
2967 (let (leftmost ; Leftmost column found so far.
2968 innermost
; Leftmost column for inner tab.
2970 (while (and (zerop (forward-line -
1))
2973 (let* ((tabs (rst-line-tabs))
2974 (leftcol (if tabs
(apply 'min
(mapcar 'car tabs
)))))
2976 ;; Consider only lines indented less or same if not INNERMOST.
2977 (when (or (not leftmost
)
2978 (< leftcol leftmost
)
2979 (and (not innermost
) (= leftcol leftmost
)))
2981 (let ((inner (cdr tab
))
2987 (< newcol leftmost
)))
2990 (< newcol innermost
))))
2991 (not (memq newcol tablist
)))
2992 (push newcol tablist
))))
2993 (setq innermost
(if (rst-some (mapcar 'cdr tabs
)) ; Has inner.
2996 (setq leftmost leftcol
)))))
2997 (nreverse tablist
))))
2999 (defun rst-indent-line (&optional dflt
)
3000 "Indent current line to next best reStructuredText tab.
3001 The next best tab is taken from the tab list returned by
3002 `rst-compute-tabs' which is used in a cyclic manner. If the
3003 current indentation does not end on a tab use the first one. If
3004 the current indentation is on a tab use the next tab. This allows
3005 a repeated use of \\[indent-for-tab-command] to cycle through all
3006 possible tabs. If no indentation is possible return `noindent' or
3007 use DFLT. Return the indentation indented to. When point is in
3008 indentation it ends up at its end. Otherwise the point is kept
3009 relative to the content."
3010 (let* ((pt (point-marker))
3011 (cur (current-indentation))
3012 (clm (current-column))
3013 (tabs (rst-compute-tabs (point)))
3014 (fnd (rst-position cur tabs
))
3016 (if (and (not tabs
) (not dflt
))
3023 (if (>= fnd
(length tabs
))
3025 (setq ind
(nth fnd tabs
)))
3026 (indent-line-to ind
)
3032 (defun rst-shift-region (beg end cnt
)
3033 "Shift region BEG to END by CNT tabs.
3034 Shift by one tab to the right (CNT > 0) or left (CNT < 0) or
3035 remove all indentation (CNT = 0). A tab is taken from the text
3036 above. If no suitable tab is found `rst-indent-width' is used."
3037 (interactive "r\np")
3038 (let ((tabs (sort (rst-compute-tabs beg
) (lambda (x y
) (<= x y
))))
3039 (leftmostcol (rst-find-leftmost-column beg end
)))
3040 (when (or (> leftmostcol
0) (> cnt
0))
3041 ;; Apply the indent.
3046 ;; Find the next tab after the leftmost column.
3047 (let* ((cmp (if (> cnt
0) '> '<))
3048 (tabs (if (> cnt
0) tabs
(reverse tabs
)))
3050 (dir (rst-signum cnt
)) ; Direction to take.
3051 (abs (abs cnt
)) ; Absolute number of steps to take.
3052 ;; Get the position of the first tab beyond leftmostcol.
3053 (fnd (lexical-let ((cmp cmp
)
3054 (leftmostcol leftmostcol
)) ; Create closure.
3055 (rst-position-if (lambda (elt)
3056 (funcall cmp elt leftmostcol
))
3058 ;; Virtual position of tab.
3059 (pos (+ (or fnd len
) (1- abs
)))
3060 (tab (if (< pos len
)
3061 ;; Tab exists - use it.
3063 ;; Column needs to be computed.
3064 (let ((col (+ (or (car (last tabs
)) leftmostcol
)
3065 ;; Base on last known column.
3066 (* (- pos
(1- len
)) ; Distance left.
3067 dir
; Direction to take.
3068 rst-indent-width
))))
3069 (if (< col
0) 0 col
)))))
3070 (- tab leftmostcol
)))))))
3072 ;; FIXME: A paragraph with an (incorrectly) indented second line is not filled
3077 (defun rst-adaptive-fill ()
3078 "Return fill prefix found at point.
3079 Value for `adaptive-fill-function'."
3080 (let ((fnd (if (looking-at adaptive-fill-regexp
)
3081 (match-string-no-properties 0))))
3082 (if (save-match-data
3083 (not (string-match comment-start-skip fnd
)))
3084 ;; An non-comment prefix is fine.
3086 ;; Matches a comment - return whitespace instead.
3089 (goto-char (match-end 0))
3092 (goto-char (match-beginning 0))
3093 (current-column))) ?
))))
3095 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3098 (defun rst-comment-line-break (&optional soft
)
3099 "Break line and indent, continuing reStructuredText comment if within one.
3100 Value for `comment-line-break-function'. If SOFT use soft
3101 newlines as mandated by `comment-line-break-function'."
3103 (insert-and-inherit ?
\n)
3107 (delete-horizontal-space))
3108 (delete-horizontal-space)
3109 (let ((tabs (rst-compute-tabs (point))))
3111 (indent-line-to (car tabs
)))))
3113 (defun rst-comment-indent ()
3114 "Return indentation for current comment line."
3115 (car (rst-compute-tabs (point))))
3117 (defun rst-comment-insert-comment ()
3118 "Insert a comment in the current line."
3120 (insert comment-start
))
3122 (defun rst-comment-region (beg end
&optional arg
)
3123 "Comment or uncomment the current region.
3124 Region is from from BEG to END. Uncomment if ARG."
3127 (rst-uncomment-region beg end arg
)
3129 (let ((ind (current-indentation))
3133 (indent-rigidly bol end rst-indent-comment
)
3136 (indent-line-to ind
)
3137 (insert (comment-string-strip comment-start t t
))))))
3139 (defun rst-uncomment-region (beg end
&optional _arg
)
3140 "Uncomment the current region.
3141 Region is from BEG to END. ARG is ignored"
3149 (indent-rigidly eol end
(- rst-indent-comment
))
3150 (delete-region bol eol
))))
3152 ;;------------------------------------------------------------------------------
3154 ;; FIXME: These next functions should become part of a larger effort to redo
3155 ;; the bullets in bulleted lists. The enumerate would just be one of
3156 ;; the possible outputs.
3158 ;; FIXME: We need to do the enumeration removal as well.
3160 (defun rst-enumerate-region (beg end all
)
3161 "Add enumeration to all the leftmost paragraphs in the given region.
3162 The region is specified between BEG and END. With ALL,
3163 do all lines instead of just paragraphs."
3164 (interactive "r\nP")
3166 (last-insert-len nil
))
3167 (rst-iterate-leftmost-paragraphs
3169 (let ((ins-string (format "%d. " (incf count
))))
3170 (setq last-insert-len
(length ins-string
))
3171 (insert ins-string
))
3172 (insert (make-string last-insert-len ?\
)))))
3174 (defun rst-bullet-list-region (beg end all
)
3175 "Add bullets to all the leftmost paragraphs in the given region.
3176 The region is specified between BEG and END. With ALL,
3177 do all lines instead of just paragraphs."
3178 (interactive "r\nP")
3179 (rst-iterate-leftmost-paragraphs
3181 (insert (car rst-preferred-bullets
) " ")
3184 ;; FIXME: Does not deal with a varying number of digits appropriately.
3185 ;; FIXME: Does not deal with multiple levels independently.
3186 ;; FIXME: Does not indent a multiline item correctly.
3187 (defun rst-convert-bullets-to-enumeration (beg end
)
3188 "Convert the bulleted and enumerated items in the region to enumerated lists.
3189 Renumber as necessary. Region is from BEG to END."
3191 (let* (;; Find items and convert the positions to markers.
3194 (cons (copy-marker (car x
))
3196 (rst-find-pfx-in-region beg end
(rst-re 'itmany-sta-1
))))
3201 (looking-at (rst-re 'itmany-beg-1
))
3202 (replace-match (format "%d." count
) nil nil nil
1)
3205 ;;------------------------------------------------------------------------------
3207 (defun rst-line-block-region (rbeg rend
&optional pfxarg
)
3208 "Toggle line block prefixes for a region.
3209 Region is from RBEG to REND. With PFXARG set the empty lines too."
3210 (interactive "r\nP")
3211 (let ((comment-start "| ")
3213 (comment-start-skip "| ")
3214 (comment-style 'indent
)
3215 (force (not (not pfxarg
))))
3216 (rst-iterate-leftmost-paragraphs-2
3217 (rbeg rend parbegin leftmost isleft isempty
)
3218 (when (or force
(not isempty
))
3219 (move-to-column leftmost force
)
3220 (delete-region (point) (+ (point) (- (current-indentation) leftmost
)))
3225 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3229 (require 'font-lock
)
3231 ;; FIXME: The obsolete variables need to disappear.
3233 ;; The following versions have been done inside Emacs and should not be
3234 ;; replaced by `:package-version' attributes until a change.
3236 (defgroup rst-faces nil
"Faces used in Rst Mode."
3241 (defface rst-block
'((t :inherit font-lock-keyword-face
))
3242 "Face used for all syntax marking up a special block."
3246 (defcustom rst-block-face
'rst-block
3247 "All syntax marking up a special block."
3251 (rst-testcover-defcustom)
3252 (make-obsolete-variable 'rst-block-face
3253 "customize the face `rst-block' instead."
3256 (defface rst-external
'((t :inherit font-lock-type-face
))
3257 "Face used for field names and interpreted text."
3261 (defcustom rst-external-face
'rst-external
3262 "Field names and interpreted text."
3266 (rst-testcover-defcustom)
3267 (make-obsolete-variable 'rst-external-face
3268 "customize the face `rst-external' instead."
3271 (defface rst-definition
'((t :inherit font-lock-function-name-face
))
3272 "Face used for all other defining constructs."
3276 (defcustom rst-definition-face
'rst-definition
3277 "All other defining constructs."
3281 (rst-testcover-defcustom)
3282 (make-obsolete-variable 'rst-definition-face
3283 "customize the face `rst-definition' instead."
3286 ;; XEmacs compatibility (?).
3287 (defface rst-directive
(if (boundp 'font-lock-builtin-face
)
3288 '((t :inherit font-lock-builtin-face
))
3289 '((t :inherit font-lock-preprocessor-face
)))
3290 "Face used for directives and roles."
3294 (defcustom rst-directive-face
'rst-directive
3295 "Directives and roles."
3298 (rst-testcover-defcustom)
3299 (make-obsolete-variable 'rst-directive-face
3300 "customize the face `rst-directive' instead."
3303 (defface rst-comment
'((t :inherit font-lock-comment-face
))
3304 "Face used for comments."
3308 (defcustom rst-comment-face
'rst-comment
3313 (rst-testcover-defcustom)
3314 (make-obsolete-variable 'rst-comment-face
3315 "customize the face `rst-comment' instead."
3318 (defface rst-emphasis1
'((t :inherit italic
))
3319 "Face used for simple emphasis."
3323 (defcustom rst-emphasis1-face
'rst-emphasis1
3328 (rst-testcover-defcustom)
3329 (make-obsolete-variable 'rst-emphasis1-face
3330 "customize the face `rst-emphasis1' instead."
3333 (defface rst-emphasis2
'((t :inherit bold
))
3334 "Face used for double emphasis."
3338 (defcustom rst-emphasis2-face
'rst-emphasis2
3342 (rst-testcover-defcustom)
3343 (make-obsolete-variable 'rst-emphasis2-face
3344 "customize the face `rst-emphasis2' instead."
3347 (defface rst-literal
'((t :inherit font-lock-string-face
))
3348 "Face used for literal text."
3352 (defcustom rst-literal-face
'rst-literal
3357 (rst-testcover-defcustom)
3358 (make-obsolete-variable 'rst-literal-face
3359 "customize the face `rst-literal' instead."
3362 (defface rst-reference
'((t :inherit font-lock-variable-name-face
))
3363 "Face used for references to a definition."
3367 (defcustom rst-reference-face
'rst-reference
3368 "References to a definition."
3372 (rst-testcover-defcustom)
3373 (make-obsolete-variable 'rst-reference-face
3374 "customize the face `rst-reference' instead."
3377 (defface rst-transition
'((t :inherit font-lock-keyword-face
))
3378 "Face used for a transition."
3379 :package-version
'(rst .
"1.3.0")
3382 (defface rst-adornment
'((t :inherit font-lock-keyword-face
))
3383 "Face used for the adornment of a section header."
3384 :package-version
'(rst .
"1.3.0")
3387 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3389 (dolist (var '(rst-level-face-max rst-level-face-base-color
3390 rst-level-face-base-light
3391 rst-level-face-format-light
3392 rst-level-face-step-light
3399 (make-obsolete-variable var
"customize the faces `rst-level-*' instead."
3402 ;; Define faces for the first 6 levels. More levels are possible, however.
3403 (defface rst-level-1
'((((background light
)) (:background
"grey85"))
3404 (((background dark
)) (:background
"grey15")))
3405 "Default face for section title text at level 1."
3406 :package-version
'(rst .
"1.4.0"))
3408 (defface rst-level-2
'((((background light
)) (:background
"grey78"))
3409 (((background dark
)) (:background
"grey22")))
3410 "Default face for section title text at level 2."
3411 :package-version
'(rst .
"1.4.0"))
3413 (defface rst-level-3
'((((background light
)) (:background
"grey71"))
3414 (((background dark
)) (:background
"grey29")))
3415 "Default face for section title text at level 3."
3416 :package-version
'(rst .
"1.4.0"))
3418 (defface rst-level-4
'((((background light
)) (:background
"grey64"))
3419 (((background dark
)) (:background
"grey36")))
3420 "Default face for section title text at level 4."
3421 :package-version
'(rst .
"1.4.0"))
3423 (defface rst-level-5
'((((background light
)) (:background
"grey57"))
3424 (((background dark
)) (:background
"grey43")))
3425 "Default face for section title text at level 5."
3426 :package-version
'(rst .
"1.4.0"))
3428 (defface rst-level-6
'((((background light
)) (:background
"grey50"))
3429 (((background dark
)) (:background
"grey50")))
3430 "Default face for section title text at level 6."
3431 :package-version
'(rst .
"1.4.0"))
3433 (defcustom rst-adornment-faces-alist
3434 '((t . rst-transition
)
3435 (nil . rst-adornment
)
3442 "Faces for the various adornment types.
3443 Key is a number (for the section title text of that level
3444 starting with 1), t (for transitions) or nil (for section title
3445 adornment). If you need levels beyond 6 you have to define faces
3451 (integer :tag
"Section level")
3452 (const :tag
"transitions" t
)
3453 (const :tag
"section title adornment" nil
))
3454 :value-type
(face)))
3455 (rst-testcover-defcustom)
3457 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3459 (defvar rst-font-lock-keywords
3460 ;; The reST-links in the comments below all relate to sections in
3461 ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
3462 `(;; FIXME: Block markup is not recognized in blocks after explicit markup
3465 ;; Simple `Body Elements`_
3467 ;; FIXME: A bullet directly after a field name is not recognized.
3468 (,(rst-re 'lin-beg
'(:grp bul-sta
))
3470 ;; `Enumerated Lists`_
3471 (,(rst-re 'lin-beg
'(:grp enmany-sta
))
3473 ;; `Definition Lists`_
3476 (,(rst-re 'lin-beg
'(:grp fld-tag
) 'bli-sfx
)
3477 1 rst-external-face
)
3479 (,(rst-re 'lin-beg
'(:grp opt-tag
(:shy optsep-tag opt-tag
) "*")
3480 '(:alt
"$" (:seq hws-prt
"\\{2\\}")))
3483 ;; Only for lines containing no more bar - to distinguish from tables.
3484 (,(rst-re 'lin-beg
'(:grp
"|" bli-sfx
) "[^|\n]*$")
3490 ;; All the `Explicit Markup Blocks`_
3491 ;; `Footnotes`_ / `Citations`_
3492 (,(rst-re 'lin-beg
'fnc-sta-2
)
3493 (1 rst-definition-face
)
3494 (2 rst-definition-face
))
3495 ;; `Directives`_ / `Substitution Definitions`_
3496 (,(rst-re 'lin-beg
'dir-sta-3
)
3497 (1 rst-directive-face
)
3498 (2 rst-definition-face
)
3499 (3 rst-directive-face
))
3500 ;; `Hyperlink Targets`_
3502 '(:grp exm-sta
"_" (:alt
3503 (:seq
"`" ilcbkqdef-tag
"`")
3504 (:seq
(:alt
"[^:\\\n]" "\\\\.") "+")) ":")
3506 1 rst-definition-face
)
3507 (,(rst-re 'lin-beg
'(:grp
"__") 'bli-sfx
)
3508 1 rst-definition-face
)
3510 ;; All `Inline Markup`_
3511 ;; Most of them may be multiline though this is uninteresting.
3513 ;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented
3514 ;; `Strong Emphasis`_.
3515 (,(rst-re 'ilm-pfx
'(:grp
"\\*\\*" ilcast-tag
"\\*\\*") 'ilm-sfx
)
3516 1 rst-emphasis2-face
)
3518 (,(rst-re 'ilm-pfx
'(:grp
"\\*" ilcast-tag
"\\*") 'ilm-sfx
)
3519 1 rst-emphasis1-face
)
3520 ;; `Inline Literals`_
3521 (,(rst-re 'ilm-pfx
'(:grp
"``" ilcbkq-tag
"``") 'ilm-sfx
)
3523 ;; `Inline Internal Targets`_
3524 (,(rst-re 'ilm-pfx
'(:grp
"_`" ilcbkq-tag
"`") 'ilm-sfx
)
3525 1 rst-definition-face
)
3526 ;; `Hyperlink References`_
3527 ;; FIXME: `Embedded URIs`_ not considered.
3528 ;; FIXME: Directly adjacent marked up words are not fontified correctly
3529 ;; unless they are not separated by two spaces: foo_ bar_.
3530 (,(rst-re 'ilm-pfx
'(:grp
(:alt
(:seq
"`" ilcbkq-tag
"`")
3531 (:seq
"\\sw" (:alt
"\\sw" "-") "+\\sw"))
3533 1 rst-reference-face
)
3534 ;; `Interpreted Text`_
3535 (,(rst-re 'ilm-pfx
'(:grp
(:shy
":" sym-tag
":") "?")
3536 '(:grp
"`" ilcbkq-tag
"`")
3537 '(:grp
(:shy
":" sym-tag
":") "?") 'ilm-sfx
)
3538 (1 rst-directive-face
)
3539 (2 rst-external-face
)
3540 (3 rst-directive-face
))
3541 ;; `Footnote References`_ / `Citation References`_
3542 (,(rst-re 'ilm-pfx
'(:grp fnc-tag
"_") 'ilm-sfx
)
3543 1 rst-reference-face
)
3544 ;; `Substitution References`_
3545 ;; FIXME: References substitutions like |this|_ or |this|__ are not
3546 ;; fontified correctly.
3547 (,(rst-re 'ilm-pfx
'(:grp sub-tag
) 'ilm-sfx
)
3548 1 rst-reference-face
)
3549 ;; `Standalone Hyperlinks`_
3550 ;; FIXME: This takes it easy by using a whitespace as delimiter.
3551 (,(rst-re 'ilm-pfx
'(:grp uri-tag
":\\S +") 'ilm-sfx
)
3552 1 rst-definition-face
)
3553 (,(rst-re 'ilm-pfx
'(:grp sym-tag
"@" sym-tag
) 'ilm-sfx
)
3554 1 rst-definition-face
)
3556 ;; Do all block fontification as late as possible so 'append works.
3558 ;; Sections_ / Transitions_
3559 ;; For sections this is multiline.
3560 (,(rst-re 'ado-beg-2-1
)
3561 (rst-font-lock-handle-adornment-matcher
3562 (rst-font-lock-handle-adornment-pre-match-form
3563 (match-string-no-properties 1) (match-end 1))
3565 (1 (cdr (assoc nil rst-adornment-faces-alist
)) append t
)
3566 (2 (cdr (assoc rst-font-lock-adornment-level
3567 rst-adornment-faces-alist
)) append t
)
3568 (3 (cdr (assoc nil rst-adornment-faces-alist
)) append t
)))
3570 ;; FIXME: FACESPEC could be used instead of ordinary faces to set
3571 ;; properties on comments and literal blocks so they are *not*
3572 ;; inline fontified. See (elisp)Search-based Fontification.
3574 ;; FIXME: And / or use `syntax-propertize` functions as in `octave-mod.el`
3575 ;; and other V24 modes. May make `font-lock-extend-region`
3579 ;; This is multiline.
3580 (,(rst-re 'lin-beg
'cmt-sta-1
)
3581 (1 rst-comment-face
)
3582 (rst-font-lock-find-unindented-line-match
3583 (rst-font-lock-find-unindented-line-limit (match-end 1))
3585 (0 rst-comment-face append
)))
3586 (,(rst-re 'lin-beg
'(:grp exm-tag
) '(:grp hws-tag
) "$")
3587 (1 rst-comment-face
)
3588 (2 rst-comment-face
)
3589 (rst-font-lock-find-unindented-line-match
3590 (rst-font-lock-find-unindented-line-limit 'next
)
3592 (0 rst-comment-face append
)))
3594 ;; FIXME: This is not rendered as comment::
3595 ;; .. .. list-table::
3599 ;; FIXME: This is rendered wrong::
3603 ;; ----|> KKKKK <|----
3605 ;; -|> AAAAAAAAAAPPPPPP <|- -|> AAAAAAAAAABBBBBBB <|-
3608 ;; PPPPPP PPPPPPDDDDDDD BBBBBBB PPPPPPBBBBBBB
3610 ;; Indentation needs to be taken from the line with the ``::`` and not from
3611 ;; the first content line.
3613 ;; `Indented Literal Blocks`_
3614 ;; This is multiline.
3615 (,(rst-re 'lin-beg
'lit-sta-2
)
3617 (rst-font-lock-find-unindented-line-match
3618 (rst-font-lock-find-unindented-line-limit t
)
3620 (0 rst-literal-face append
)))
3622 ;; FIXME: `Quoted Literal Blocks`_ missing.
3623 ;; This is multiline.
3625 ;; `Doctest Blocks`_
3626 ;; FIXME: This is wrong according to the specification:
3628 ;; Doctest blocks are text blocks which begin with ">>> ", the Python
3629 ;; interactive interpreter main prompt, and end with a blank line.
3630 ;; Doctest blocks are treated as a special case of literal blocks,
3631 ;; without requiring the literal block syntax. If both are present, the
3632 ;; literal block syntax takes priority over Doctest block syntax:
3634 ;; This is an ordinary paragraph.
3636 ;; >>> print 'this is a Doctest block'
3637 ;; this is a Doctest block
3639 ;; The following is a literal block::
3641 ;; >>> This is not recognized as a doctest block by
3642 ;; reStructuredText. It *will* be recognized by the doctest
3645 ;; Indentation is not required for doctest blocks.
3646 (,(rst-re 'lin-beg
'(:grp
(:alt
">>>" ell-tag
)) '(:grp
".+"))
3648 (2 rst-literal-face
)))
3649 "Keywords to highlight in rst mode.")
3651 (defvar font-lock-beg
)
3652 (defvar font-lock-end
)
3654 (defun rst-font-lock-extend-region ()
3655 "Extend the font-lock region if it might be in a multi-line construct.
3656 Return non-nil if so. Font-lock region is from `font-lock-beg'
3657 to `font-lock-end'."
3658 (let ((r (rst-font-lock-extend-region-internal font-lock-beg font-lock-end
)))
3660 (setq font-lock-beg
(car r
))
3661 (setq font-lock-end
(cdr r
))
3664 (defun rst-font-lock-extend-region-internal (beg end
)
3665 "Check the region BEG / END for being in the middle of a multi-line construct.
3666 Return nil if not or a cons with new values for BEG / END"
3667 (let ((nbeg (rst-font-lock-extend-region-extend beg -
1))
3668 (nend (rst-font-lock-extend-region-extend end
1)))
3670 (cons (or nbeg beg
) (or nend end
)))))
3672 (defun rst-forward-line (&optional n
)
3673 "Like `forward-line' but always end up in column 0 and return accordingly.
3674 Move N lines forward just as `forward-line'."
3675 (let ((moved (forward-line n
)))
3679 (- moved
(rst-signum n
)))))
3681 ;; FIXME: If a single line is made a section header by `rst-adjust' the header
3682 ;; is not always fontified immediately.
3683 (defun rst-font-lock-extend-region-extend (pt dir
)
3684 "Extend the region starting at point PT and extending in direction DIR.
3685 Return extended point or nil if not moved."
3686 ;; There are many potential multiline constructs but there are two groups
3687 ;; which are really relevant. The first group consists of
3689 ;; * comment lines without leading explicit markup tag and
3691 ;; * literal blocks following "::"
3693 ;; which are both indented. Thus indentation is the first thing recognized
3694 ;; here. The second criteria is an explicit markup tag which may be a comment
3695 ;; or a double colon at the end of a line.
3697 ;; The second group consists of the adornment cases.
3698 (if (not (get-text-property pt
'font-lock-multiline
))
3699 ;; Move only if we don't start inside a multiline construct already.
3701 (let (;; Non-empty non-indented line, explicit markup tag or literal
3703 (stop-re (rst-re '(:alt
"[^ \t\n]"
3704 (:seq hws-tag exm-tag
)
3705 (:seq
".*" dcl-tag lin-end
)))))
3706 ;; The comments below are for dir == -1 / dir == 1.
3710 (while (and (not (looking-at stop-re
))
3711 (zerop (rst-forward-line dir
)))) ; try previous / next
3712 ; line if it exists.
3713 (if (looking-at (rst-re 'ado-beg-2-1
)) ; may be an underline /
3715 (if (zerop (rst-forward-line dir
))
3716 (if (looking-at (rst-re 'ttl-beg
)) ; title found, i.e.
3717 ; underline / overline
3719 (if (zerop (rst-forward-line dir
))
3721 (looking-at (rst-re 'ado-beg-2-1
))) ; no
3724 (rst-forward-line (- dir
)))) ; step back to title
3726 (if (< dir
0) ; keep downward adornment.
3727 (rst-forward-line (- dir
))))) ; step back to adornment.
3728 (if (looking-at (rst-re 'ttl-beg
)) ; may be a title.
3729 (if (zerop (rst-forward-line dir
))
3731 (looking-at (rst-re 'ado-beg-2-1
))) ; no overline /
3733 (rst-forward-line (- dir
)))))) ; step back to line.
3734 (if (not (= (point) pt
))
3737 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3740 (defun rst-forward-indented-block (&optional column limit
)
3741 "Move forward across one indented block.
3742 Find the next non-empty line which is not indented at least to COLUMN (defaults
3743 to the column of the point). Moves point to first character of this line or the
3744 first empty line immediately before it and returns that position. If there is
3745 no such line before LIMIT (defaults to the end of the buffer) returns nil and
3746 point is not moved."
3748 (let ((clm (or column
(current-column)))
3752 (setq limit
(point-max)))
3754 (while (and (not fnd
) (< (point) limit
))
3756 (when (< (point) limit
)
3758 (if (looking-at (rst-re 'lin-end
))
3759 (setq cand
(or cand beg
)) ; An empty line is a candidate.
3760 (move-to-column clm
)
3761 ;; FIXME: No indentation [(zerop clm)] must be handled in some
3762 ;; useful way - though it is not clear what this should mean
3765 (rst-re 'linemp-tag
)
3766 (buffer-substring-no-properties beg
(point)))
3767 (setq cand nil
) ; An indented line resets a candidate.
3768 (setq fnd
(or cand beg
)))))))
3769 (goto-char (or fnd start
))
3772 (defvar rst-font-lock-find-unindented-line-begin nil
3773 "Beginning of the match if `rst-font-lock-find-unindented-line-end'.")
3775 (defvar rst-font-lock-find-unindented-line-end nil
3776 "End of the match as determined by `rst-font-lock-find-unindented-line-limit'.
3777 Also used as a trigger for `rst-font-lock-find-unindented-line-match'.")
3779 (defun rst-font-lock-find-unindented-line-limit (ind-pnt)
3780 "Find the next unindented line relative to indentation at IND-PNT.
3781 Return this point, the end of the buffer or nil if nothing found.
3782 If IND-PNT is `next' take the indentation from the next line if
3783 this is not empty and indented more than the current one. If
3784 IND-PNT is non-nil but not a number take the indentation from the
3785 next non-empty line if this is indented more than the current one."
3786 (setq rst-font-lock-find-unindented-line-begin ind-pnt
)
3787 (setq rst-font-lock-find-unindented-line-end
3789 (when (not (numberp ind-pnt
))
3790 ;; Find indentation point in next line if any.
3792 ;; FIXME: Should be refactored to two different functions
3793 ;; giving their result to this function, may be
3794 ;; integrated in caller.
3796 (let ((cur-ind (current-indentation)))
3797 (if (eq ind-pnt
'next
)
3798 (when (and (zerop (forward-line 1))
3799 (< (point) (point-max)))
3801 (setq rst-font-lock-find-unindented-line-begin
3803 (when (and (not (looking-at (rst-re 'lin-end
)))
3804 (> (current-indentation) cur-ind
))
3805 ;; Use end of indentation if non-empty line.
3806 (looking-at (rst-re 'hws-tag
))
3808 ;; Skip until non-empty line or EOF.
3809 (while (and (zerop (forward-line 1))
3810 (< (point) (point-max))
3811 (looking-at (rst-re 'lin-end
))))
3812 (when (< (point) (point-max))
3814 (setq rst-font-lock-find-unindented-line-begin
3816 (when (> (current-indentation) cur-ind
)
3817 ;; Indentation bigger than line of departure.
3818 (looking-at (rst-re 'hws-tag
))
3819 (match-end 0))))))))
3822 (or (rst-forward-indented-block nil
(point-max))
3825 (defun rst-font-lock-find-unindented-line-match (_limit)
3826 "Set the match found earlier if match were found.
3827 Match has been found by `rst-font-lock-find-unindented-line-limit'
3828 the first time called or no match is found. Return non-nil if
3829 match was found. LIMIT is not used but mandated by the caller."
3830 (when rst-font-lock-find-unindented-line-end
3832 (list rst-font-lock-find-unindented-line-begin
3833 rst-font-lock-find-unindented-line-end
))
3834 (put-text-property rst-font-lock-find-unindented-line-begin
3835 rst-font-lock-find-unindented-line-end
3836 'font-lock-multiline t
)
3837 ;; Make sure this is called only once.
3838 (setq rst-font-lock-find-unindented-line-end nil
)
3841 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3844 (defvar rst-font-lock-adornment-level nil
3845 "Storage for `rst-font-lock-handle-adornment-matcher'.
3846 Either section level of the current adornment or t for a transition.")
3848 (defun rst-adornment-level (key)
3849 "Return section level for adornment KEY.
3850 KEY is the first element of the return list of `rst-classify-adornment'.
3851 If KEY is not a cons return it. If KEY is found in the hierarchy return
3852 its level. Otherwise return a level one beyond the existing hierarchy."
3853 (if (not (consp key
))
3855 (let* ((hier (rst-get-hierarchy))
3858 (1+ (or (lexical-let ((char char
)
3860 (hier hier
)) ; Create closure.
3861 (rst-position-if (lambda (elt)
3862 (and (equal (car elt
) char
)
3863 (equal (cadr elt
) style
))) hier
))
3866 (defvar rst-font-lock-adornment-match nil
3867 "Storage for match for current adornment.
3868 Set by `rst-font-lock-handle-adornment-pre-match-form'. Also used
3869 as a trigger for `rst-font-lock-handle-adornment-matcher'.")
3871 (defun rst-font-lock-handle-adornment-pre-match-form (ado ado-end
)
3872 "Determine limit for adornments.
3873 Determine all things necessary for font-locking section titles
3874 and transitions and put the result to `rst-font-lock-adornment-match'
3875 and `rst-font-lock-adornment-level'. ADO is the complete adornment
3876 matched. ADO-END is the point where ADO ends. Return the point
3877 where the whole adorned construct ends.
3879 Called as a PRE-MATCH-FORM in the sense of `font-lock-keywords'."
3880 (let ((ado-data (rst-classify-adornment ado ado-end
)))
3882 (setq rst-font-lock-adornment-level nil
3883 rst-font-lock-adornment-match nil
)
3884 (setq rst-font-lock-adornment-level
3885 (rst-adornment-level (car ado-data
)))
3886 (setq rst-font-lock-adornment-match
(cdr ado-data
))
3887 (goto-char (nth 1 ado-data
)) ; Beginning of construct.
3888 (nth 2 ado-data
)))) ; End of construct.
3890 (defun rst-font-lock-handle-adornment-matcher (_limit)
3891 "Set the match found earlier if match were found.
3892 Match has been found by
3893 `rst-font-lock-handle-adornment-pre-match-form' the first time
3894 called or no match is found. Return non-nil if match was found.
3896 Called as a MATCHER in the sense of `font-lock-keywords'.
3897 LIMIT is not used but mandated by the caller."
3898 (let ((match rst-font-lock-adornment-match
))
3899 ;; May run only once - enforce this.
3900 (setq rst-font-lock-adornment-match nil
)
3902 (set-match-data match
)
3903 (goto-char (match-end 0))
3904 (put-text-property (match-beginning 0) (match-end 0)
3905 'font-lock-multiline t
)
3909 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3912 (defgroup rst-compile nil
3913 "Settings for support of conversion of reStructuredText
3914 document with \\[rst-compile]."
3918 (defcustom rst-compile-toolsets
3919 `((html ,(if (executable-find "rst2html.py") "rst2html.py" "rst2html")
3921 (latex ,(if (executable-find "rst2latex.py") "rst2latex.py" "rst2latex")
3923 (newlatex ,(if (executable-find "rst2newlatex.py") "rst2newlatex.py"
3926 (pseudoxml ,(if (executable-find "rst2pseudoxml.py") "rst2pseudoxml.py"
3929 (xml ,(if (executable-find "rst2xml.py") "rst2xml.py" "rst2xml")
3931 (pdf ,(if (executable-find "rst2pdf.py") "rst2pdf.py" "rst2pdf")
3933 (s5 ,(if (executable-find "rst2s5.py") "rst2s5.py" "rst2s5")
3935 "Table describing the command to use for each tool-set.
3936 An association list of the tool-set to a list of the (command to use,
3937 extension of produced filename, options to the tool (nil or a
3938 string)) to be used for converting the document."
3939 ;; FIXME: These are not options but symbols which may be referenced by
3940 ;; `rst-compile-*-toolset` below. The `:validate' keyword of
3941 ;; `defcustom' may help to define this properly in newer Emacs
3942 ;; versions (> 23.1).
3943 :type
'(alist :options
(html latex newlatex pseudoxml xml pdf s5
)
3945 :value-type
(list :tag
"Specification"
3946 (file :tag
"Command")
3947 (string :tag
"File extension")
3948 (choice :tag
"Command options"
3949 (const :tag
"No options" nil
)
3950 (string :tag
"Options"))))
3952 :package-version
"1.2.0")
3953 (rst-testcover-defcustom)
3955 ;; FIXME: Must be `defcustom`.
3956 (defvar rst-compile-primary-toolset
'html
3957 "The default tool-set for `rst-compile'.")
3959 ;; FIXME: Must be `defcustom`.
3960 (defvar rst-compile-secondary-toolset
'latex
3961 "The default tool-set for `rst-compile' with a prefix argument.")
3963 (defun rst-compile-find-conf ()
3964 "Look for the configuration file in the parents of the current path."
3966 (let ((file-name "docutils.conf")
3967 (buffer-file (buffer-file-name)))
3968 ;; Move up in the dir hierarchy till we find a change log file.
3969 (let* ((dir (file-name-directory buffer-file
))
3971 (while (and (or (not (string= dir prevdir
))
3974 (not (file-exists-p (concat dir file-name
))))
3975 ;; Move up to the parent dir and try again.
3977 (setq dir
(expand-file-name (file-name-directory
3978 (directory-file-name
3979 (file-name-directory dir
))))))
3980 (or (and dir
(concat dir file-name
)) nil
))))
3984 (defun rst-compile (&optional use-alt
)
3985 "Compile command to convert reST document into some output file.
3986 Attempts to find configuration file, if it can, overrides the
3987 options. There are two commands to choose from; with USE-ALT,
3988 select the alternative tool-set."
3990 ;; Note: maybe we want to check if there is a Makefile too and not do anything
3991 ;; if that is the case. I dunno.
3992 (let* ((toolset (cdr (assq (if use-alt
3993 rst-compile-secondary-toolset
3994 rst-compile-primary-toolset
)
3995 rst-compile-toolsets
)))
3996 (command (car toolset
))
3997 (extension (cadr toolset
))
3998 (options (caddr toolset
))
3999 (conffile (rst-compile-find-conf))
4000 (bufname (file-name-nondirectory buffer-file-name
))
4001 (outname (file-name-sans-extension bufname
)))
4003 ;; Set compile-command before invocation of compile.
4004 (set (make-local-variable 'compile-command
)
4005 (mapconcat 'identity
4009 (concat "--config=" (shell-quote-argument conffile
))
4011 (shell-quote-argument bufname
)
4012 (shell-quote-argument (concat outname extension
)))
4015 ;; Invoke the compile command.
4016 (if (or compilation-read-command use-alt
)
4017 (call-interactively 'compile
)
4018 (compile compile-command
))))
4020 (defun rst-compile-alt-toolset ()
4021 "Compile command with the alternative tool-set."
4025 (defun rst-compile-pseudo-region ()
4026 "Show pseudo-XML rendering.
4027 Rendering is done of the current active region, or of the entire
4028 buffer, if the region is not selected."
4029 ;; FIXME: The region should be given interactively.
4031 (with-output-to-temp-buffer "*pseudoxml*"
4032 (shell-command-on-region
4033 (if mark-active
(region-beginning) (point-min))
4034 (if mark-active
(region-end) (point-max))
4035 (cadr (assq 'pseudoxml rst-compile-toolsets
))
4038 ;; FIXME: Should be `defcustom`.
4039 (defvar rst-pdf-program
"xpdf"
4040 "Program used to preview PDF files.")
4042 (defun rst-compile-pdf-preview ()
4043 "Convert the document to a PDF file and launch a preview program."
4045 (let* ((tmp-filename (make-temp-file "rst_el" nil
".pdf"))
4046 (command (format "%s %s %s && %s %s ; rm %s"
4047 (cadr (assq 'pdf rst-compile-toolsets
))
4048 buffer-file-name tmp-filename
4049 rst-pdf-program tmp-filename tmp-filename
)))
4050 (start-process-shell-command "rst-pdf-preview" nil command
)
4051 ;; Note: you could also use (compile command) to view the compilation
4055 ;; FIXME: Should be `defcustom` or use something like `browse-url`.
4056 (defvar rst-slides-program
"firefox"
4057 "Program used to preview S5 slides.")
4059 (defun rst-compile-slides-preview ()
4060 "Convert the document to an S5 slide presentation and launch a preview program."
4062 (let* ((tmp-filename (make-temp-file "rst_el" nil
".html"))
4063 (command (format "%s %s %s && %s %s ; rm %s"
4064 (cadr (assq 's5 rst-compile-toolsets
))
4065 buffer-file-name tmp-filename
4066 rst-slides-program tmp-filename tmp-filename
)))
4067 (start-process-shell-command "rst-slides-preview" nil command
)
4068 ;; Note: you could also use (compile command) to view the compilation
4073 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
4076 ;; FIXME: Integrate this properly. Consider a key binding.
4078 ;; Based on code from Masatake YAMATO <yamato@redhat.com>.
4080 (defun rst-imenu-find-adornments-for-position (adornments pos
)
4081 "Find adornments cell in ADORNMENTS for position POS."
4084 (if (and (car adornments
)
4085 (eq (car (car adornments
)) pos
))
4088 (setq adornments
(cdr adornments
))))
4091 (defun rst-imenu-convert-cell (elt adornments
)
4092 "Convert a cell ELT in a tree returned from `rst-section-tree' to Imenu index.
4093 ADORNMENTS is used as hint information for conversion."
4094 (let* ((kar (car elt
))
4098 (let* ((p (marker-position (cadr kar
)))
4100 (rst-imenu-find-adornments-for-position adornments p
))
4101 (a (car adornments
))
4102 (adornments (cdr adornments
))
4103 ;; FIXME: Overline adornment characters need to be in front so
4104 ;; they become visible even for long title lines. May be
4105 ;; an additional level number is also useful.
4106 (title (format "%s%s%s"
4107 (make-string (1+ (nth 3 a
)) (nth 1 a
))
4109 (if (eq (nth 2 a
) 'simple
)
4111 (char-to-string (nth 1 a
))))))
4116 ;; A bit ugly but this make which-func happy.
4118 (mapcar (lambda (elt0)
4119 (rst-imenu-convert-cell elt0 adornments
))
4123 ;; FIXME: Document title and subtitle need to be handled properly. They should
4124 ;; get an own "Document" top level entry.
4125 (defun rst-imenu-create-index ()
4126 "Create index for Imenu.
4127 Return as described for `imenu--index-alist'."
4128 (rst-reset-section-caches)
4129 (let ((tree (rst-section-tree))
4130 ;; Translate line notation to point notation.
4131 (adornments (save-excursion
4132 (mapcar (lambda (ln-ado)
4134 (goto-char (point-min))
4135 (forward-line (1- (car ln-ado
)))
4136 ;; FIXME: Need to consider
4137 ;; `imenu-use-markers' here?
4140 (rst-find-all-adornments)))))
4141 (delete nil
(mapcar (lambda (elt)
4142 (rst-imenu-convert-cell elt adornments
))
4146 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
4147 ;; Generic text functions that are more convenient than the defaults.
4149 ;; FIXME: Unbound command - should be bound or removed.
4150 (defun rst-replace-lines (fromchar tochar
)
4151 "Replace flush-left lines of FROMCHAR with equal-length lines of TOCHAR."
4153 cSearch for flush-left lines of char:
4154 cand replace with char: ")
4156 (let ((searchre (rst-re "^" fromchar
"+\\( *\\)$"))
4158 (while (search-forward-regexp searchre nil t
)
4159 (setq found
(1+ found
))
4160 (goto-char (match-beginning 1))
4161 (let ((width (current-column)))
4162 (rst-delete-entire-line)
4163 (insert-char tochar width
)))
4164 (message (format "%d lines replaced." found
)))))
4166 ;; FIXME: Unbound command - should be bound or removed.
4167 (defun rst-join-paragraph ()
4168 "Join lines in current paragraph into one line, removing end-of-lines."
4170 (let ((fill-column 65000)) ; Some big number.
4171 (call-interactively 'fill-paragraph
)))
4173 ;; FIXME: Unbound command - should be bound or removed.
4174 (defun rst-force-fill-paragraph ()
4175 "Fill paragraph at point, first joining the paragraph's lines into one.
4176 This is useful for filling list item paragraphs."
4178 (rst-join-paragraph)
4179 (fill-paragraph nil
))
4182 ;; FIXME: Unbound command - should be bound or removed.
4183 ;; Generic character repeater function.
4184 ;; For sections, better to use the specialized function above, but this can
4185 ;; be useful for creating separators.
4186 (defun rst-repeat-last-character (use-next)
4187 "Fill the current line using the last character on the current line.
4188 Fill up to the length of the preceding line or up to `fill-column' if preceding
4191 If USE-NEXT, use the next line rather than the preceding line.
4193 If the current line is longer than the desired length, shave the characters off
4194 the current line to fit the desired length.
4196 As an added convenience, if the command is repeated immediately, the alternative
4197 column is used (fill-column vs. end of previous/next line)."
4199 (let* ((curcol (current-column))
4200 (curline (+ (count-lines (point-min) (point))
4201 (if (zerop curcol
) 1 0)))
4202 (lbp (line-beginning-position 0))
4203 (prevcol (if (and (= curline
1) (not use-next
))
4206 (forward-line (if use-next
1 -
1))
4208 (skip-chars-backward " \t" lbp
)
4209 (let ((cc (current-column)))
4210 (if (zerop cc
) fill-column cc
)))))
4212 (cond ((equal last-command
'rst-repeat-last-character
)
4213 (if (= curcol fill-column
) prevcol fill-column
))
4215 (if (zerop prevcol
) fill-column prevcol
))))))
4217 (if (> (current-column) rightmost-column
)
4218 ;; Shave characters off the end.
4219 (delete-region (- (point)
4220 (- (current-column) rightmost-column
))
4222 ;; Fill with last characters.
4223 (insert-char (preceding-char)
4224 (- rightmost-column
(current-column))))))
4228 ;; LocalWords: docutils http sourceforge rst html wp svn svnroot txt reST regex
4229 ;; LocalWords: regexes alist seq alt grp keymap abbrev overline overlines toc
4230 ;; LocalWords: XML PNT propertized
4233 ;; sentence-end-double-space: t
4238 ;;; rst.el ends here