[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r108425: Silence `checkdoc-ispell' er
|
From: |
Stefan Merten |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r108425: Silence `checkdoc-ispell' errors where possible. Fix authors. Improve |
|
Date: |
Tue, 29 May 2012 22:14:18 +0200 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 108425
committer: Stefan Merten <address@hidden>
branch nick: trunk
timestamp: Tue 2012-05-29 22:14:18 +0200
message:
Silence `checkdoc-ispell' errors where possible. Fix authors. Improve
comments. Improve loading of `cl'.
(rst-mode-abbrev-table): Merge definition.
(rst-mode): Make sure `font-lock-defaults' is buffer local.
(rst-define-key, rst-deprecated-keys, rst-call-deprecated): Refactor.
modified:
etc/NEWS
lisp/ChangeLog
lisp/textmodes/rst.el
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2012-05-29 09:46:06 +0000
+++ b/etc/NEWS 2012-05-29 20:14:18 +0000
@@ -125,31 +125,31 @@
** reStructuredText mode
-*** Nearly all keys are rebound making room for more keys and comply
-better to usage in other modes. Bindings are described with C-c C-h.
-
-*** Major revision of indentation. Now works very similarly to other modes.
-TAB is your friend.
-
-*** Major revision of filling. Works fine with most of
-reStructuredText syntax. Auto-filling is also supported.
+*** Rebind nearly all keys making room for more keys and complying
+better to usage in other modes. Describe bindings with C-c C-h.
+
+*** Major revision of indentation working very similar to other
+modes. TAB is your friend.
+
+*** Major revision of filling working fine with most of
+reStructuredText syntax. Support auto-filling.
*** Major revision of comment handling.
-*** Major revision of fontification. Now works with `jit-lock-mode'.
-
-*** reStructuredText syntax is covered more closely in many cases.
-Among other things this improves the experience for Sphinx users.
-
-*** `rst-insert-list' inserts a new list or continues existing lists.
-
-*** Customization is extended, corrected and improved.
+*** Major revision of fontification working with `jit-lock-mode'.
+
+*** Cover reStructuredText syntax more closely. Improve
+the experience for Sphinx users.
+
+*** `rst-insert-list' inserts new list or continues existing lists.
+
+*** Extend correct and improve customization.
*** Negative prefix argument always works for `rst-adjust'.
-*** Window configuration is reset after displaying TOC.
+*** Reset window configuration after displaying TOC.
-*** There is a package version in `rst-version'.
+*** Package version in `rst-version'.
** New `derived-mode' filter for Ibuffer, bound to `/ M'.
`/ m' is now bound to filter by used-mode, which used to be bound to `/ M'.
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-05-29 19:42:49 +0000
+++ b/lisp/ChangeLog 2012-05-29 20:14:18 +0000
@@ -1,3 +1,13 @@
+2012-05-29 Stefan Merten <address@hidden>
+
+ * textmodes/rst.el: Silence `checkdoc-ispell' errors where
+ possible. Fix authors. Improve comments. Improve loading of
+ `cl'.
+
+ (rst-mode-abbrev-table): Merge definition.
+ (rst-mode): Make sure `font-lock-defaults' is buffer local.
+ (rst-define-key, rst-deprecated-keys, rst-call-deprecated): Refactor.
+
2012-05-29 Ulf Jasper <address@hidden>
* calendar/icalendar.el
@@ -791,6 +801,109 @@
* man.el (Man-unindent): Use text-property-default-nonsticky to
prevent untabify from inheriting face properties (Bug#11408).
+2012-05-05 Stefan Merten <address@hidden>
+
+ * textmodes/rst.el: Major merge with upstream development up to
+ Docutils SVN r7399 / rst.el V1.2.1.
+
+ Clarify maintainership and authors.
+
+ (rst-extract-version, rst-cvs-header, rst-cvs-rev)
+ (rst-cvs-timestamp, rst-svn-rev, rst-svn-timestamp)
+ (rst-official-version, rst-official-cvs-rev, rst-version)
+ (rst-package-emacs-version-alist): New functions and variables
+ for version information.
+
+ (rst-bullets, rst-uri-schemes, rst-adornment-chars)
+ (rst-max-inline-length, rst-re-alist-def, rst-re-alist)
+ (rst-mode-syntax-table, rst-mode): New and corrected functions
+ and variables representing reStructuredText features.
+
+ (rst-re): New function for reStructuredText regexes. Use in
+ many places.
+
+ (rst-deprecated-keys, rst-call-deprecated, rst-define-key)
+ (rst-mode-map): Rebind keys.
+
+ (rst-mode-lazy, rst-font-lock-keywords)
+ (rst-font-lock-extend-region)
+ (rst-font-lock-extend-region-internal)
+ (rst-font-lock-extend-region-extend)
+ (rst-font-lock-find-unindented-line-limit)
+ (rst-font-lock-find-unindented-line-match)
+ (rst-adornment-level, rst-font-lock-adornment-level)
+ (rst-font-lock-adornment-match)
+ (rst-font-lock-handle-adornment-pre-match-form)
+ (rst-font-lock-handle-adornment-matcher): Major revision of
+ font-locking. Integrate with other code. Use `jit-lock-mode'.
+
+ (rst-preferred-adornments, rst-adjust-hook)
+ (rst-new-adornment-down, rst-preferred-bullets)
+ (rst-preferred-bullets, rst-indent, rst-indent-width)
+ (rst-indent-field, rst-indent-literal-normal)
+ (rst-indent-literal-minimized, rst-indent-comment): Change,
+ extend and improve customization.
+
+ (rst-line-homogeneous-p, rst-line-homogeneous-nodent-p)
+ (rst-normalize-cursor-position, rst-get-decoration)
+ (rst-straighten-deco-spacing, rst-re-bullets, rst-re-items)
+ (rst-rstrip, rst-toc-insert-find-delete-contents)
+ (rst-shift-fill-region, rst-compute-bullet-tabs)
+ (rst-debug-print-tabs, rst-debug-mark-found)
+ (rst-shift-region-guts, rst-shift-region-right)
+ (rst-shift-region-left, rst-use-char-classes)
+ (rst-font-lock-keywords-function)
+ (rst-font-lock-indentation-point)
+ (rst-font-lock-find-unindented-line-begin)
+ (rst-font-lock-find-unindented-line-end)
+ (rst-font-lock-find-unindented-line)
+ (rst-font-lock-adornment-point, rst-font-lock-level)
+ (rst-adornment-level-alist): Remove functions and variables.
+
+ (rst-compare-adornments, rst-get-adornment-match)
+ (rst-suggest-new-adornment, rst-get-adornments-around)
+ (rst-adornment-complete-p, rst-get-next-adornment)
+ (rst-adjust-adornment, rst-display-adornments-hierarchy)
+ (rst-straighten-adornments): Standardize function names to
+ use "adornment" instead of "decoration". Correct callers.
+ Similar standardizing in many places.
+
+ (rst-update-section, rst-adjust, rst-promote-region)
+ (rst-enumerate-region, rst-bullet-list-region)
+ (rst-repeat-last-character): Correct use of `interactive'.
+
+ (rst-classify-adornment, rst-find-all-adornments)
+ (rst-get-hierarchy, rst-adjust-adornment, rst-toc-update)
+ (rst-find-leftmost-column, rst-repeat-last-character):
+ Refactor functions.
+
+ (rst-find-title-line, rst-reset-section-caches)
+ (rst-get-adornments-around, rst-adjust-adornment-work)
+ (rst-arabic-to-roman, rst-roman-to-arabic)
+ (rst-insert-list-pos, rst-insert-list-new-item)
+ (rst-insert-list-continue, rst-insert-list, rst-forward-line):
+ New functions.
+
+ (rst-all-sections, rst-section-hierarchy)
+ (rst-arabic-to-roman, rst-initial-enums, rst-initial-items):
+ New variables.
+
+ (rst-toc-return-wincfg, rst-toc-quit-window): Use window
+ configuration instead of only buffer. Change where necessary.
+
+ (rst-line-tabs, rst-compute-tabs, rst-indent-line)
+ (rst-shift-region, rst-adaptive-fill): New functions for
+ indentation and filling.
+
+ (rst-comment-line-break, rst-comment-indent)
+ (rst-comment-insert-comment, rst-comment-region)
+ (rst-uncomment-region): New functions for handling comments.
+
+ (rst-compile): Quote shell arguments.
+
+ (rst-compile-pdf-preview, rst-compile-slides-preview):
+ Delete temporary files after use.
+
2012-05-05 Glenn Morris <address@hidden>
* calendar/cal-html.el: Optionally include holidays in the output.
=== modified file 'lisp/textmodes/rst.el'
--- a/lisp/textmodes/rst.el 2012-05-29 06:16:49 +0000
+++ b/lisp/textmodes/rst.el 2012-05-29 20:14:18 +0000
@@ -3,7 +3,8 @@
;; Copyright (C) 2003-2012 Free Software Foundation, Inc.
;; Maintainer: Stefan Merten <address@hidden>
-;; Author: Martin Blais <address@hidden>,
+;; Author: Stefan Merten <address@hidden>,
+;; Martin Blais <address@hidden>,
;; David Goodger <address@hidden>,
;; Wei-Wei Guo <address@hidden>
@@ -25,10 +26,10 @@
;;; Commentary:
;; This package provides major mode rst-mode, which supports documents marked
-;; up using the reStructuredText format. Support includes font locking as well
-;; as a lot of convenience functions for editing. It does this by defining a
-;; Emacs major mode: rst-mode (ReST). This mode is derived from text-mode. This
-;; package also contains:
+;; up using the reStructuredText format. Support includes font locking as well
+;; as a lot of convenience functions for editing. It does this by defining a
+;; Emacs major mode: rst-mode (ReST). This mode is derived from text-mode.
+;; This package also contains:
;;
;; - Functions to automatically adjust and cycle the section underline
;; adornments;
@@ -53,12 +54,12 @@
;; http://docutils.sourceforge.net/docs/user/emacs.html
;;
;;
-;; There are a number of convenient keybindings provided by rst-mode.
+;; There are a number of convenient key bindings provided by rst-mode.
;; For more on bindings, see rst-mode-map below. There are also many variables
;; that can be customized, look for defcustom in this file.
;;
;; If you use the table-of-contents feature, you may want to add a hook to
-;; update the TOC automatically everytime you adjust a section title::
+;; update the TOC automatically every time you adjust a section title::
;;
;; (add-hook 'rst-adjust-hook 'rst-toc-update)
;;
@@ -70,7 +71,7 @@
;;
;;
;; Customization is done by customizable variables contained in customization
-;; group "rst" and subgroups. Group "rst" is contained in the "wp" group.
+;; group "rst" and subgroups. Group "rst" is contained in the "wp" group.
;;
;;; DOWNLOAD
@@ -95,21 +96,23 @@
;; want automatically enter rst-mode from any file with compatible extensions:
;;
;; (setq auto-mode-alist
-;; (append '(("\\.txt$" . rst-mode)
-;; ("\\.rst$" . rst-mode)
-;; ("\\.rest$" . rst-mode)) auto-mode-alist))
+;; (append '(("\\.txt\\'" . rst-mode)
+;; ("\\.rst\\'" . rst-mode)
+;; ("\\.rest\\'" . rst-mode)) auto-mode-alist))
;;
;;; Code:
-(require 'cl)
+(eval-when-compile
+ (require 'cl))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Versions
(defun rst-extract-version (delim-re head-re re tail-re var &optional default)
- "Return the version matching RE after regex DELIM-RE and HEAD-RE
-and before TAIL-RE and DELIM-RE in VAR or DEFAULT for no match"
+ "Extract the version from a variable according to the given regexes.
+Return the version after regex DELIM-RE and HEAD-RE matching RE
+and before TAIL-RE and DELIM-RE in VAR or DEFAULT for no match."
(if (string-match
(concat delim-re head-re "\\(" re "\\)" tail-re delim-re)
var)
@@ -117,20 +120,20 @@
default))
;; Use CVSHeader to really get information from CVS and not other version
-;; control systems
+;; control systems.
(defconst rst-cvs-header
- "$CVSHeader: sm/rst_el/rst.el,v 1.257 2012-04-29 15:01:17 stefan Exp $")
+ "$CVSHeader: sm/rst_el/rst.el,v 1.257.2.9 2012-05-29 19:53:00 stefan Exp $")
(defconst rst-cvs-rev
(rst-extract-version "\\$" "CVSHeader: \\S + " "[0-9]+\\(?:\\.[0-9]+\\)+"
" .*" rst-cvs-header "0.0")
- "The CVS revision of this file. CVS revision is the development revision.")
+ "The CVS revision of this file. CVS revision is the development revision.")
(defconst rst-cvs-timestamp
(rst-extract-version "\\$" "CVSHeader: \\S + \\S + "
"[0-9]+-[0-9]+-[0-9]+ [0-9]+:[0-9]+:[0-9]+" " .*"
rst-cvs-header "1970-01-01 00:00:00")
- "The CVS timestamp of this file.")
+ "The CVS time stamp of this file.")
-;; Use LastChanged... to really get information from SVN
+;; Use LastChanged... to really get information from SVN.
(defconst rst-svn-rev
(rst-extract-version "\\$" "LastChangedRevision: " "[0-9]+" " "
"$LastChangedRevision: 7399 $")
@@ -139,9 +142,9 @@
(defconst rst-svn-timestamp
(rst-extract-version "\\$" "LastChangedDate: " ".+?+" " "
"$LastChangedDate: 2012-04-29 17:01:05 +0200 (Sun, 29
Apr 2012) $")
- "The SVN timestamp of this file.")
+ "The SVN time stamp of this file.")
-;; Maintained by the release process
+;; Maintained by the release process.
(defconst rst-official-version
(rst-extract-version "%" "OfficialVersion: " "[0-9]+\\(?:\\.[0-9]+\\)+" " "
"%OfficialVersion: 1.2.1 %")
@@ -157,8 +160,8 @@
(format "%s (development %s [%s])" rst-official-version
rst-cvs-rev rst-cvs-timestamp))
"The version string.
-Starts with the current official version. For developer versions
-in parentheses follows the development revision and the timestamp.")
+Starts with the current official version. For developer versions
+in parentheses follows the development revision and the time stamp.")
(defconst rst-package-emacs-version-alist
'(("1.0.0" . "24.0")
@@ -187,12 +190,12 @@
;; Facilities for regular expressions used everywhere
;; The trailing numbers in the names give the number of referenceable regex
-;; groups contained in the regex
+;; groups contained in the regex.
;; Used to be customizable but really is not customizable but fixed by the reST
-;; syntax
+;; syntax.
(defconst rst-bullets
- ;; Sorted so they can form a character class when concatenated
+ ;; Sorted so they can form a character class when concatenated.
'(?- ?* ?+ ?\u2022 ?\u2023 ?\u2043)
"List of all possible bullet characters for bulleted lists.")
@@ -203,7 +206,7 @@
"Supported URI schemes.")
(defconst rst-adornment-chars
- ;; Sorted so they can form a character class when concatenated
+ ;; Sorted so they can form a character class when concatenated.
'(?\]
?! ?\" ?# ?$ ?% ?& ?' ?\( ?\) ?* ?+ ?, ?. ?/ ?: ?\; ?< ?= ?> ?? ?@ ?\[ ?\\
?^ ?_ ?` ?{ ?| ?} ?~
@@ -215,45 +218,45 @@
"Maximum length of inline markup to recognize.")
(defconst rst-re-alist-def
- ;; `*-beg' matches * at the beginning of a line
- ;; `*-end' matches * at the end of a line
- ;; `*-prt' matches a part of *
- ;; `*-tag' matches *
- ;; `*-sta' matches the start of * which may be followed by respective content
- ;; `*-pfx' matches the delimiter left of *
- ;; `*-sfx' matches the delimiter right of *
- ;; `*-hlp' helper for *
+ ;; `*-beg' matches * at the beginning of a line.
+ ;; `*-end' matches * at the end of a line.
+ ;; `*-prt' matches a part of *.
+ ;; `*-tag' matches *.
+ ;; `*-sta' matches the start of * which may be followed by respective
content.
+ ;; `*-pfx' matches the delimiter left of *.
+ ;; `*-sfx' matches the delimiter right of *.
+ ;; `*-hlp' helper for *.
;;
;; A trailing number says how many referenceable groups are contained.
`(
;; Horizontal white space (`hws')
(hws-prt "[\t ]")
- (hws-tag hws-prt "*") ; Optional sequence of horizontal white space
- (hws-sta hws-prt "+") ; Mandatory sequence of horizontal white space
+ (hws-tag hws-prt "*") ; Optional sequence of horizontal white space.
+ (hws-sta hws-prt "+") ; Mandatory sequence of horizontal white space.
;; Lines (`lin')
- (lin-beg "^" hws-tag) ; Beginning of a possibly indented line
- (lin-end hws-tag "$") ; End of a line with optional trailing white space
- (linemp-tag "^" hws-tag "$") ; Empty line with optional white space
+ (lin-beg "^" hws-tag) ; Beginning of a possibly indented line.
+ (lin-end hws-tag "$") ; End of a line with optional trailing white space.
+ (linemp-tag "^" hws-tag "$") ; Empty line with optional white space.
;; Various tags and parts
(ell-tag "\\.\\.\\.") ; Ellipsis
- (bul-tag ,(concat "[" rst-bullets "]")) ; A bullet
- (ltr-tag "[a-zA-Z]") ; A letter enumerator tag
- (num-prt "[0-9]") ; A number enumerator part
- (num-tag num-prt "+") ; A number enumerator tag
- (rom-prt "[IVXLCDMivxlcdm]") ; A roman enumerator part
- (rom-tag rom-prt "+") ; A roman enumerator tag
- (aut-tag "#") ; An automatic enumerator tag
- (dcl-tag "::") ; Double colon
+ (bul-tag ,(concat "[" rst-bullets "]")) ; A bullet.
+ (ltr-tag "[a-zA-Z]") ; A letter enumerator tag.
+ (num-prt "[0-9]") ; A number enumerator part.
+ (num-tag num-prt "+") ; A number enumerator tag.
+ (rom-prt "[IVXLCDMivxlcdm]") ; A roman enumerator part.
+ (rom-tag rom-prt "+") ; A roman enumerator tag.
+ (aut-tag "#") ; An automatic enumerator tag.
+ (dcl-tag "::") ; Double colon.
;; Block lead in (`bli')
(bli-sfx (:alt hws-sta "$")) ; Suffix of a block lead-in with *optional*
- ; immediate content
+ ; immediate content.
;; Various starts
- (bul-sta bul-tag bli-sfx) ; Start of a bulleted item
+ (bul-sta bul-tag bli-sfx) ; Start of a bulleted item.
;; Explicit markup tag (`exm')
(exm-tag "\\.\\.")
@@ -261,101 +264,101 @@
(exm-beg lin-beg exm-sta)
;; Counters in enumerations (`cnt')
- (cntany-tag (:alt ltr-tag num-tag rom-tag aut-tag)) ; An arbitrary counter
- (cntexp-tag (:alt ltr-tag num-tag rom-tag)) ; An arbitrary explicit counter
+ (cntany-tag (:alt ltr-tag num-tag rom-tag aut-tag)) ; An arbitrary counter.
+ (cntexp-tag (:alt ltr-tag num-tag rom-tag)) ; An arbitrary explicit
counter.
;; Enumerator (`enm')
(enmany-tag (:alt
(:seq cntany-tag "\\.")
- (:seq "(?" cntany-tag ")"))) ; An arbitrary enumerator
+ (:seq "(?" cntany-tag ")"))) ; An arbitrary enumerator.
(enmexp-tag (:alt
(:seq cntexp-tag "\\.")
(:seq "(?" cntexp-tag ")"))) ; An arbitrary explicit
- ; enumerator
+ ; enumerator.
(enmaut-tag (:alt
(:seq aut-tag "\\.")
- (:seq "(?" aut-tag ")"))) ; An automatic enumerator
- (enmany-sta enmany-tag bli-sfx) ; An arbitrary enumerator start
- (enmexp-sta enmexp-tag bli-sfx) ; An arbitrary explicit enumerator start
+ (:seq "(?" aut-tag ")"))) ; An automatic enumerator.
+ (enmany-sta enmany-tag bli-sfx) ; An arbitrary enumerator start.
+ (enmexp-sta enmexp-tag bli-sfx) ; An arbitrary explicit enumerator start.
(enmexp-beg lin-beg enmexp-sta) ; An arbitrary explicit enumerator start
- ; at the beginning of a line
+ ; at the beginning of a line.
;; Items may be enumerated or bulleted (`itm')
- (itmany-tag (:alt enmany-tag bul-tag)) ; An arbitrary item tag
+ (itmany-tag (:alt enmany-tag bul-tag)) ; An arbitrary item tag.
(itmany-sta-1 (:grp itmany-tag) bli-sfx) ; An arbitrary item start, group
- ; is the item tag
+ ; is the item tag.
(itmany-beg-1 lin-beg itmany-sta-1) ; An arbitrary item start at the
; beginning of a line, group is the
- ; item tag
+ ; item tag.
;; Inline markup (`ilm')
(ilm-pfx (:alt "^" hws-prt "[-'\"([{<\u2018\u201c\u00ab\u2019/:]"))
(ilm-sfx (:alt "$" hws-prt "[]-'\")}>\u2019\u201d\u00bb/:.,;!?\\]"))
;; Inline markup content (`ilc')
- (ilcsgl-tag "\\S ") ; A single non-white character
- (ilcast-prt (:alt "[^*\\]" "\\\\.")) ; Part of non-asterisk content
- (ilcbkq-prt (:alt "[^`\\]" "\\\\.")) ; Part of non-backquote content
+ (ilcsgl-tag "\\S ") ; A single non-white character.
+ (ilcast-prt (:alt "[^*\\]" "\\\\.")) ; Part of non-asterisk content.
+ (ilcbkq-prt (:alt "[^`\\]" "\\\\.")) ; Part of non-backquote content.
(ilcbkqdef-prt (:alt "[^`\\\n]" "\\\\.")) ; Part of non-backquote
- ; definition
- (ilcbar-prt (:alt "[^|\\]" "\\\\.")) ; Part of non-vertical-bar content
+ ; definition.
+ (ilcbar-prt (:alt "[^|\\]" "\\\\.")) ; Part of non-vertical-bar content.
(ilcbardef-prt (:alt "[^|\\\n]" "\\\\.")) ; Part of non-vertical-bar
- ; definition
- (ilcast-sfx "[^\t *\\]") ; Suffix of non-asterisk content
- (ilcbkq-sfx "[^\t `\\]") ; Suffix of non-backquote content
- (ilcbar-sfx "[^\t |\\]") ; Suffix of non-vertical-bar content
- (ilcrep-hlp ,(format "\\{0,%d\\}" rst-max-inline-length)) ; Repeat count
+ ; definition.
+ (ilcast-sfx "[^\t *\\]") ; Suffix of non-asterisk content.
+ (ilcbkq-sfx "[^\t `\\]") ; Suffix of non-backquote content.
+ (ilcbar-sfx "[^\t |\\]") ; Suffix of non-vertical-bar content.
+ (ilcrep-hlp ,(format "\\{0,%d\\}" rst-max-inline-length)) ; Repeat count.
(ilcast-tag (:alt ilcsgl-tag
(:seq ilcsgl-tag
ilcast-prt ilcrep-hlp
- ilcast-sfx))) ; Non-asterisk content
+ ilcast-sfx))) ; Non-asterisk content.
(ilcbkq-tag (:alt ilcsgl-tag
(:seq ilcsgl-tag
ilcbkq-prt ilcrep-hlp
- ilcbkq-sfx))) ; Non-backquote content
+ ilcbkq-sfx))) ; Non-backquote content.
(ilcbkqdef-tag (:alt ilcsgl-tag
(:seq ilcsgl-tag
ilcbkqdef-prt ilcrep-hlp
- ilcbkq-sfx))) ; Non-backquote definition
+ ilcbkq-sfx))) ; Non-backquote definition.
(ilcbar-tag (:alt ilcsgl-tag
(:seq ilcsgl-tag
ilcbar-prt ilcrep-hlp
- ilcbar-sfx))) ; Non-vertical-bar content
+ ilcbar-sfx))) ; Non-vertical-bar content.
(ilcbardef-tag (:alt ilcsgl-tag
(:seq ilcsgl-tag
ilcbardef-prt ilcrep-hlp
- ilcbar-sfx))) ; Non-vertical-bar definition
+ ilcbar-sfx))) ; Non-vertical-bar definition.
;; Fields (`fld')
- (fldnam-prt (:alt "[^:\n]" "\\\\:")) ; Part of a field name
- (fldnam-tag fldnam-prt "+") ; A field name
- (fld-tag ":" fldnam-tag ":") ; A field marker
+ (fldnam-prt (:alt "[^:\n]" "\\\\:")) ; Part of a field name.
+ (fldnam-tag fldnam-prt "+") ; A field name.
+ (fld-tag ":" fldnam-tag ":") ; A field marker.
;; Options (`opt')
- (optsta-tag (:alt "[-+/]" "--")) ; Start of an option
- (optnam-tag "\\sw" (:alt "-" "\\sw") "*") ; Name of an option
- (optarg-tag (:shy "[ =]\\S +")) ; Option argument
- (optsep-tag (:shy "," hws-prt)) ; Separator between options
- (opt-tag (:shy optsta-tag optnam-tag optarg-tag "?")) ; A complete option
+ (optsta-tag (:alt "[-+/]" "--")) ; Start of an option.
+ (optnam-tag "\\sw" (:alt "-" "\\sw") "*") ; Name of an option.
+ (optarg-tag (:shy "[ =]\\S +")) ; Option argument.
+ (optsep-tag (:shy "," hws-prt)) ; Separator between options.
+ (opt-tag (:shy optsta-tag optnam-tag optarg-tag "?")) ; A complete option.
;; Footnotes and citations (`fnc')
- (fncnam-prt "[^\]\n]") ; Part of a footnote or citation name
- (fncnam-tag fncnam-prt "+") ; A footnote or citation name
- (fnc-tag "\\[" fncnam-tag "]") ; A complete footnote or citation tag
+ (fncnam-prt "[^\]\n]") ; Part of a footnote or citation name.
+ (fncnam-tag fncnam-prt "+") ; A footnote or citation name.
+ (fnc-tag "\\[" fncnam-tag "]") ; A complete footnote or citation tag.
(fncdef-tag-2 (:grp exm-sta)
(:grp fnc-tag)) ; A complete footnote or citation definition
- ; tag; first group is the explicit markup
+ ; tag. First group is the explicit markup
; start, second group is the footnote /
- ; citation tag
+ ; citation tag.
(fnc-sta-2 fncdef-tag-2 bli-sfx) ; Start of a footnote or citation
- ; definition; first group is the explicit
+ ; definition. First group is the explicit
; markup start, second group is the
- ; footnote / citation tag
+ ; footnote / citation tag.
;; Substitutions (`sub')
- (sub-tag "|" ilcbar-tag "|") ; A complete substitution tag
+ (sub-tag "|" ilcbar-tag "|") ; A complete substitution tag.
(subdef-tag "|" ilcbardef-tag "|") ; A complete substitution definition
- ; tag
+ ; tag.
;; Symbol (`sym')
(sym-tag (:shy "\\sw+" (:shy "\\s_\\sw+") "*"))
@@ -367,62 +370,62 @@
(ado-prt "[" ,(concat rst-adornment-chars) "]")
(adorep3-hlp "\\{3,\\}") ; There must be at least 3 characters because
; otherwise explicit markup start would be
- ; recognized
+ ; recognized.
(adorep2-hlp "\\{2,\\}") ; As `adorep3-hlp' but when the first of three
- ; characters is matched differently
+ ; characters is matched differently.
(ado-tag-1-1 (:grp ado-prt)
"\\1" adorep2-hlp) ; A complete adornment, group is the first
; adornment character and MUST be the FIRST
- ; group in the whole expression
+ ; group in the whole expression.
(ado-tag-1-2 (:grp ado-prt)
"\\2" adorep2-hlp) ; A complete adornment, group is the first
; adornment character and MUST be the
- ; SECOND group in the whole expression
+ ; SECOND group in the whole expression.
(ado-beg-2-1 "^" (:grp ado-tag-1-2)
lin-end) ; A complete adornment line; first group is the whole
; adornment and MUST be the FIRST group in the whole
; expression; second group is the first adornment
- ; character
+ ; character.
;; Titles (`ttl')
- (ttl-tag "\\S *\\w\\S *") ; A title text
- (ttl-beg lin-beg ttl-tag) ; A title text at the beginning of a line
+ (ttl-tag "\\S *\\w\\S *") ; A title text.
+ (ttl-beg lin-beg ttl-tag) ; A title text at the beginning of a line.
;; Directives and substitution definitions (`dir')
(dir-tag-3 (:grp exm-sta)
(:grp (:shy subdef-tag hws-sta) "?")
(:grp sym-tag dcl-tag)) ; A directive or substitution definition
- ; tag; first group is explicit markup
+ ; tag. First group is explicit markup
; start, second group is a possibly
; empty substitution tag, third group is
; the directive tag including the double
- ; colon
+ ; colon.
(dir-sta-3 dir-tag-3 bli-sfx) ; Start of a directive or substitution
- ; definition; groups are as in dir-tag-3
+ ; definition. Groups are as in dir-tag-3.
;; Literal block (`lit')
(lit-sta-2 (:grp (:alt "[^.\n]" "\\.[^.\n]") ".*") "?"
- (:grp dcl-tag) "$") ; Start of a literal block; first group is
+ (:grp dcl-tag) "$") ; Start of a literal block. First group is
; any text before the double colon tag which
; may not exist, second group is the double
- ; colon tag
+ ; colon tag.
;; Comments (`cmt')
(cmt-sta-1 (:grp exm-sta) "[^\[|_\n]"
(:alt "[^:\n]" (:seq ":" (:alt "[^:\n]" "$")))
"*$") ; Start of a comment block; first group is explicit markup
- ; start
+ ; start.
;; Paragraphs (`par')
(par-tag- (:alt itmany-tag fld-tag opt-tag fncdef-tag-2 dir-tag-3 exm-tag)
) ; Tag at the beginning of a paragraph; there may be groups in
- ; certain cases
+ ; certain cases.
)
"Definition alist of relevant regexes.
Each entry consists of the symbol naming the regex and an
argument list for `rst-re'.")
-;; FIXME: Use `sregex` or `rx` instead of re-inventing the wheel
+;; FIXME: Use `sregex` or `rx` instead of re-inventing the wheel.
(defun rst-re (&rest args)
"Interpret ARGS as regular expressions and return a regex string.
Each element of ARGS may be one of the following:
@@ -433,8 +436,8 @@
A symbol which is resolved to a string using `rst-re-alist-def'.
-A list with a keyword in the car. Each element of the cdr of such
-a list is recursively interpreted as ARGS. The results of this
+A list with a keyword in the car. Each element of the cdr of such
+a list is recursively interpreted as ARGS. The results of this
interpretation are concatenated according to the keyword.
For the keyword `:seq' the results are simply concatenated.
@@ -446,11 +449,10 @@
which is shy-grouped (\"\\(?:...\\)\").
For the keyword `:grp' the results are concatenated and form a
-referenceable grouped (\"\\(...\\)\").
+referenceable group (\"\\(...\\)\").
After interpretation of ARGS the results are concatenated as for
-`:seq'.
-"
+`:seq'."
(apply 'concat
(mapcar
(lambda (re)
@@ -484,7 +486,7 @@
;; FIXME: Remove circular dependency between `rst-re' and `rst-re-alist'.
(defconst rst-re-alist
;; Shadow global value we are just defining so we can construct it step by
- ;; step
+ ;; step.
(let (rst-re-alist)
(dolist (re rst-re-alist-def)
(setq rst-re-alist
@@ -495,96 +497,78 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Mode definition.
-
-(defvar rst-deprecated-keys nil
- "Alist mapping deprecated keys to the new key to use and the definition.")
-
-(require 'edmacro)
-
-(defun rst-call-deprecated ()
- (interactive)
- (let* ((dep-key (this-command-keys-vector))
- (dep-key-s (format-kbd-macro dep-key))
- (fnd (assoc dep-key rst-deprecated-keys)))
- (if (not fnd)
- ;; Exact key sequence not found. Maybe a deprecated key sequence has
- ;; been followed by another key.
- (let* ((dep-key-pfx (butlast (append dep-key nil) 1))
- (dep-key-def (vconcat dep-key-pfx '(t)))
- (fnd-def (assoc dep-key-def rst-deprecated-keys)))
- (if (not fnd-def)
- (error "Unknown deprecated key sequence %s" dep-key-s)
- ;; Don't execute the command in this case
- (message "[Deprecated use of key %s; use key %s instead]"
- (format-kbd-macro dep-key-pfx)
- (format-kbd-macro (second fnd-def)))))
- (message "[Deprecated use of key %s; use key %s instead]"
- dep-key-s (format-kbd-macro (second fnd)))
- (call-interactively (third fnd)))))
+;; Mode definition
(defun rst-define-key (keymap key def &rest deprecated)
- "Bind like `define-key' using DEPRECATED as deprecated key definitions.
-DEPRECATED key definitions should be in vector notation. These
-are defined as well but give an additional message."
+ "Bind like `define-key' but add deprecated key definitions.
+KEYMAP, KEY, and DEF are as in `define-key'. DEPRECATED key
+definitions should be in vector notation. These are defined as
+well but give an additional message."
(define-key keymap key def)
(dolist (dep-key deprecated)
- (push (list dep-key key def) rst-deprecated-keys)
- (define-key keymap dep-key 'rst-call-deprecated)))
+ (define-key keymap dep-key
+ `(lambda ()
+ ,(format "Deprecated binding for %s, use \\[%s] instead." def def)
+ (interactive)
+ (call-interactively ',def)
+ (message "[Deprecated use of key %s; use key %s instead]"
+ (key-description (this-command-keys))
+ (key-description ,key))))))
;; Key bindings.
(defvar rst-mode-map
(let ((map (make-sparse-keymap)))
- ;; \C-c is the general keymap
+ ;; \C-c is the general keymap.
(rst-define-key map [?\C-c ?\C-h] 'describe-prefix-bindings)
;;
- ;; Section Adornments.
+ ;; Section Adornments
;;
;; The adjustment function that adorns or rotates a section title.
(rst-define-key map [?\C-c ?\C-=] 'rst-adjust [?\C-c ?\C-a t])
(rst-define-key map [?\C-=] 'rst-adjust) ; (Does not work on the Mac OSX.)
- ;; \C-c \C-a is the keymap for adornments
+ ;; \C-c \C-a is the keymap for adornments.
(rst-define-key map [?\C-c ?\C-a ?\C-h] 'describe-prefix-bindings)
- ;; Display the hierarchy of adornments implied by the current document
contents.
+ ;; Display the hierarchy of adornments implied by the current document
+ ;; contents.
(rst-define-key map [?\C-c ?\C-a ?\C-d] 'rst-display-adornments-hierarchy)
;; Homogenize the adornments in the document.
(rst-define-key map [?\C-c ?\C-a ?\C-s] 'rst-straighten-adornments
[?\C-c ?\C-s])
;;
- ;; Section Movement and Selection.
+ ;; Section Movement and Selection
;;
;; Mark the subsection where the cursor is.
(rst-define-key map [?\C-\M-h] 'rst-mark-section
- ;; same as mark-defun sgml-mark-current-element
+ ;; Same as mark-defun sgml-mark-current-element.
[?\C-c ?\C-m])
;; Move forward/backward between section titles.
(rst-define-key map [?\C-\M-a] 'rst-forward-section
- ;; same as beginning-of-defun
+ ;; Same as beginning-of-defun.
[?\C-c ?\C-n])
(rst-define-key map [?\C-\M-e] 'rst-backward-section
- ;; same as end-of-defun
+ ;; Same as end-of-defun.
[?\C-c ?\C-p])
;;
- ;; Operating on regions.
+ ;; Operating on regions
;;
- ;; \C-c \C-r is the keymap for regions
+ ;; \C-c \C-r is the keymap for regions.
(rst-define-key map [?\C-c ?\C-r ?\C-h] 'describe-prefix-bindings)
;; Makes region a line-block.
(rst-define-key map [?\C-c ?\C-r ?\C-l] 'rst-line-block-region
[?\C-c ?\C-d])
- ;; Shift region left or right according to tabs
+ ;; Shift region left or right according to tabs.
(rst-define-key map [?\C-c ?\C-r tab] 'rst-shift-region
[?\C-c ?\C-r t] [?\C-c ?\C-l t])
;;
- ;; Operating on lists.
+ ;; Operating on lists
;;
- ;; \C-c \C-l is the keymap for lists
+ ;; \C-c \C-l is the keymap for lists.
(rst-define-key map [?\C-c ?\C-l ?\C-h] 'describe-prefix-bindings)
;; Makes paragraphs in region as a bullet list.
(rst-define-key map [?\C-c ?\C-l ?\C-b] 'rst-bullet-list-region
@@ -598,13 +582,13 @@
;; Make sure that all the bullets in the region are consistent.
(rst-define-key map [?\C-c ?\C-l ?\C-s] 'rst-straighten-bullets-region
[?\C-c ?\C-w])
- ;; Insert a list item
+ ;; Insert a list item.
(rst-define-key map [?\C-c ?\C-l ?\C-i] 'rst-insert-list)
;;
- ;; Table-of-Contents Features.
+ ;; Table-of-Contents Features
;;
- ;; \C-c \C-t is the keymap for table of contents
+ ;; \C-c \C-t is the keymap for table of contents.
(rst-define-key map [?\C-c ?\C-t ?\C-h] 'describe-prefix-bindings)
;; Enter a TOC buffer to view and move to a specific section.
(rst-define-key map [?\C-c ?\C-t ?\C-t] 'rst-toc)
@@ -614,14 +598,14 @@
;; Update the document's TOC (without changing the cursor position).
(rst-define-key map [?\C-c ?\C-t ?\C-u] 'rst-toc-update
[?\C-c ?\C-u])
- ;; Got to the section under the cursor (cursor must be in TOC).
+ ;; Go to the section under the cursor (cursor must be in TOC).
(rst-define-key map [?\C-c ?\C-t ?\C-j] 'rst-goto-section
[?\C-c ?\C-f])
;;
- ;; Converting Documents from Emacs.
+ ;; Converting Documents from Emacs
;;
- ;; \C-c \C-c is the keymap for compilation
+ ;; \C-c \C-c is the keymap for compilation.
(rst-define-key map [?\C-c ?\C-c ?\C-h] 'describe-prefix-bindings)
;; Run one of two pre-configured toolset commands on the document.
(rst-define-key map [?\C-c ?\C-c ?\C-c] 'rst-compile
@@ -644,8 +628,6 @@
;; Abbrevs.
-(defvar rst-mode-abbrev-table nil
- "Abbrev table used while in `rst-mode'.")
(define-abbrev-table 'rst-mode-abbrev-table
(mapcar (lambda (x) (append x '(nil 0 system)))
'(("contents" ".. contents::\n..\n ")
@@ -654,7 +636,8 @@
("skip" "\n\n[...]\n\n ")
("seq" "\n\n[...]\n\n ")
;; FIXME: Add footnotes, links, and more.
- )))
+ ))
+ "Abbrev table used while in `rst-mode'.")
;; Syntax table.
@@ -711,7 +694,7 @@
:syntax-table rst-mode-syntax-table
:group 'rst
- ;; Paragraph recognition
+ ;; Paragraph recognition.
(set (make-local-variable 'paragraph-separate)
(rst-re '(:alt
"\f"
@@ -722,7 +705,7 @@
lin-end
(:seq hws-tag par-tag- bli-sfx))))
- ;; Indenting and filling
+ ;; Indenting and filling.
(set (make-local-variable 'indent-line-function) 'rst-indent-line)
(set (make-local-variable 'adaptive-fill-mode) t)
(set (make-local-variable 'adaptive-fill-regexp)
@@ -730,7 +713,7 @@
(set (make-local-variable 'adaptive-fill-function) 'rst-adaptive-fill)
(set (make-local-variable 'fill-paragraph-handle-comment) nil)
- ;; Comments
+ ;; Comments.
(set (make-local-variable 'comment-start) ".. ")
(set (make-local-variable 'comment-start-skip)
(rst-re 'lin-beg 'exm-tag 'bli-sfx))
@@ -738,10 +721,12 @@
(set (make-local-variable 'comment-multi-line) t)
(set (make-local-variable 'comment-use-syntax) nil)
;; reStructuredText has not really a comment ender but nil is not really a
- ;; permissible value
+ ;; permissible value.
(set (make-local-variable 'comment-end) "")
(set (make-local-variable 'comment-end-skip) nil)
+ ;; Commenting in reStructuredText is very special so use our own set of
+ ;; functions.
(set (make-local-variable 'comment-line-break-function)
'rst-comment-line-break)
(set (make-local-variable 'comment-indent-function)
@@ -753,21 +738,15 @@
(set (make-local-variable 'uncomment-region-function)
'rst-uncomment-region)
- ;; Font lock
- (setq font-lock-defaults
- '(rst-font-lock-keywords
- t nil nil nil
- (font-lock-multiline . t)
- (font-lock-mark-block-function . mark-paragraph)
- ;; rst-mode does not need font-lock-support-mode because it's fast
- ;; enough. In fact using `jit-lock-mode` slows things down
- ;; considerably even if `rst-font-lock-extend-region` is in place and
- ;; compiled.
- ;;(font-lock-support-mode . nil)
- ))
+ ;; Font lock.
+ (set (make-local-variable 'font-lock-defaults)
+ '(rst-font-lock-keywords
+ t nil nil nil
+ (font-lock-multiline . t)
+ (font-lock-mark-block-function . mark-paragraph)))
(add-hook 'font-lock-extend-region-functions 'rst-font-lock-extend-region t)
- ;; Text after a changed line may need new fontification
+ ;; Text after a changed line may need new fontification.
(set (make-local-variable 'jit-lock-contextually) t))
;;;###autoload
@@ -789,8 +768,8 @@
:group 'rst)
;; FIXME: can I somehow install these too?
-;; :abbrev-table rst-mode-abbrev-table
-;; :syntax-table rst-mode-syntax-table
+;; :abbrev-table rst-mode-abbrev-table
+;; :syntax-table rst-mode-syntax-table
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -883,10 +862,10 @@
"Preferred hierarchy of section title adornments.
A list consisting of lists of the form (CHARACTER STYLE INDENT).
-CHARACTER is the character used. STYLE is one of the symbols
-OVER-AND-UNDER or SIMPLE. INDENT is an integer giving the wanted
-indentation for STYLE OVER-AND-UNDER. CHARACTER and STYLE are
-always used when a section adornment is described. In other
+CHARACTER is the character used. STYLE is one of the symbols
+OVER-AND-UNDER or SIMPLE. INDENT is an integer giving the wanted
+indentation for STYLE OVER-AND-UNDER. CHARACTER and STYLE are
+always used when a section adornment is described. In other
places t instead of a list stands for a transition.
This sequence is consulted to offer a new adornment suggestion
@@ -991,7 +970,7 @@
(let ((marker (point-marker))
len)
- ;; Fixup whitespace at the beginning and end of the line
+ ;; Fixup whitespace at the beginning and end of the line.
(if (or (null indent) (eq style 'simple))
(setq indent 0))
(beginning-of-line)
@@ -1001,10 +980,10 @@
(end-of-line)
(delete-horizontal-space)
- ;; Set the current column, we're at the end of the title line
+ ;; Set the current column, we're at the end of the title line.
(setq len (+ (current-column) indent))
- ;; Remove previous line if it is an adornment
+ ;; Remove previous line if it is an adornment.
(save-excursion
(forward-line -1)
(if (and (looking-at (rst-re 'ado-beg-2-1))
@@ -1013,24 +992,24 @@
(not (looking-at (rst-re 'ttl-beg)))))
(rst-delete-entire-line)))
- ;; Remove following line if it is an adornment
+ ;; Remove following line if it is an adornment.
(save-excursion
(forward-line +1)
(if (looking-at (rst-re 'ado-beg-2-1))
(rst-delete-entire-line))
;; Add a newline if we're at the end of the buffer, for the subsequence
- ;; inserting of the underline
+ ;; inserting of the underline.
(if (= (point) (buffer-end 1))
(newline 1)))
- ;; Insert overline
+ ;; Insert overline.
(if (eq style 'over-and-under)
(save-excursion
(beginning-of-line)
(open-line 1)
(insert (make-string len char))))
- ;; Insert underline
+ ;; Insert underline.
(forward-line +1)
(open-line 1)
(insert (make-string len char))
@@ -1042,17 +1021,17 @@
(defun rst-classify-adornment (adornment end)
"Classify adornment for section titles and transitions.
ADORNMENT is the complete adornment string as found in the buffer
-with optional trailing whitespace. END is the point after the
+with optional trailing whitespace. END is the point after the
last character of ADORNMENT.
-Return a list. The first entry is t for a transition or a
-cons (CHARACTER . STYLE). Check `rst-preferred-adornments' for
+Return a list. The first entry is t for a transition or a
+cons (CHARACTER . STYLE). Check `rst-preferred-adornments' for
the meaning of CHARACTER and STYLE.
The remaining list forms four match groups as returned by
-`match-data'. Match group 0 matches the whole construct. Match
-group 1 matches the overline adornment if present. Match group 2
-matches the section title text or the transition. Match group 3
+`match-data'. Match group 0 matches the whole construct. Match
+group 1 matches the overline adornment if present. Match group 2
+matches the section title text or the transition. Match group 3
matches the underline adornment.
Return nil if no syntactically valid adornment is found."
@@ -1074,25 +1053,25 @@
(save-excursion
(or (not (zerop (forward-line -1)))
(looking-at (rst-re 'lin-end)))))
- (ttl-blw ; Title found below starting here
+ (ttl-blw ; Title found below starting here.
(save-excursion
(and
(zerop (forward-line 1))
(looking-at (rst-re 'ttl-beg))
(point))))
- (ttl-abv ; Title found above starting here
+ (ttl-abv ; Title found above starting here.
(save-excursion
(and
(zerop (forward-line -1))
(looking-at (rst-re 'ttl-beg))
(point))))
- (und-fnd ; Matching underline found starting here
+ (und-fnd ; Matching underline found starting here.
(save-excursion
(and ttl-blw
(zerop (forward-line 2))
(looking-at (rst-re ado-re 'lin-end))
(point))))
- (ovr-fnd ; Matching overline found starting here
+ (ovr-fnd ; Matching overline found starting here.
(save-excursion
(and ttl-abv
(zerop (forward-line -2))
@@ -1101,14 +1080,14 @@
key beg-ovr end-ovr beg-txt end-txt beg-und end-und)
(cond
((and nxt-emp prv-emp)
- ;; A transition
+ ;; A transition.
(setq key t
beg-txt beg-pnt
end-txt end-pnt))
((or und-fnd ovr-fnd)
- ;; An overline with an underline
+ ;; An overline with an underline.
(setq key (cons ado-ch 'over-and-under))
- (let (;; Prefer overline match over underline match
+ (let (;; Prefer overline match over underline match.
(und-pnt (if ovr-fnd beg-pnt und-fnd))
(ovr-pnt (if ovr-fnd ovr-fnd beg-pnt))
(txt-pnt (if ovr-fnd ttl-abv ttl-blw)))
@@ -1122,7 +1101,7 @@
(setq beg-und (point)
end-und (line-end-position))))
(ttl-abv
- ;; An underline
+ ;; An underline.
(setq key (cons ado-ch 'simple)
beg-und beg-pnt
end-und end-pnt)
@@ -1130,7 +1109,7 @@
(setq beg-txt (point)
end-txt (line-end-position)))
(t
- ;; Invalid adornment
+ ;; Invalid adornment.
(setq key nil)))
(if key
(list key
@@ -1141,15 +1120,15 @@
(defun rst-find-title-line ()
"Find a section title line around point and return its characteristics.
If the point is on an adornment line find the respective title
-line. If the point is on an empty line check previous or next
-line whether it is a suitable title line and use it if so. If
+line. If the point is on an empty line check previous or next
+line whether it is a suitable title line and use it if so. If
point is on a suitable title line use it.
If no title line is found return nil.
-Otherwise return as `rst-classify-adornment' does. However, if
+Otherwise return as `rst-classify-adornment' does. However, if
the title line has no syntactically valid adornment STYLE is nil
-in the first element. If there is no adornment around the title
+in the first element. If there is no adornment around the title
CHARACTER is also nil and match groups for overline and underline
are nil."
(save-excursion
@@ -1163,14 +1142,14 @@
(match-end 0))))
(cond
((not r)
- ;; Invalid adornment - check whether this is an incomplete overline
+ ;; Invalid adornment - check whether this is an incomplete overline.
(if (and
(zerop (forward-line 1))
(looking-at (rst-re 'ttl-beg)))
(list (cons char nil) orig-pnt (line-end-position)
orig-pnt orig-end (point) (line-end-position) nil nil)))
((consp (car r))
- ;; A section title - not a transition
+ ;; A section title - not a transition.
r))))
((looking-at (rst-re 'lin-end))
(or
@@ -1185,14 +1164,14 @@
(list (cons nil nil) (point) (line-end-position)
nil nil (point) (line-end-position) nil nil)))))
((looking-at (rst-re 'ttl-beg))
- ;; Try to use the underline
+ ;; Try to use the underline.
(let ((r (rst-classify-adornment
(buffer-substring-no-properties
(line-beginning-position 2) (line-end-position 2))
(line-end-position 2))))
(if r
r
- ;; No valid adornment found
+ ;; No valid adornment found.
(list (cons nil nil) (point) (line-end-position)
nil nil (point) (line-end-position) nil nil))))))))
@@ -1206,10 +1185,10 @@
(make-variable-buffer-local 'rst-all-sections)
;; FIXME: If this variable is set to a different value font-locking of section
-;; headers is wrong
+;; headers is wrong.
(defvar rst-section-hierarchy nil
"Section hierarchy in the buffer as determined by `rst-get-hierarchy'.
-t when no section adornments were found. Value depends on
+t when no section adornments were found. Value depends on
`rst-all-sections'.")
(make-variable-buffer-local 'rst-section-hierarchy)
@@ -1222,7 +1201,7 @@
(defun rst-find-all-adornments ()
"Return all the section adornments in the current buffer.
Return a list of (LINE . ADORNMENT) with ascending LINE where
-LINE is the line containing the section title. ADORNMENT consists
+LINE is the line containing the section title. ADORNMENT consists
of a (CHARACTER STYLE INDENT) triple as described for
`rst-preferred-adornments'.
@@ -1236,15 +1215,15 @@
(let ((ado-data (rst-classify-adornment
(match-string-no-properties 0) (point))))
(when (and ado-data
- (consp (car ado-data))) ; Ignore transitions
+ (consp (car ado-data))) ; Ignore transitions.
(set-match-data (cdr ado-data))
- (goto-char (match-beginning 2)) ; Goto the title start
+ (goto-char (match-beginning 2)) ; Goto the title start.
(push (cons (1+ (count-lines (point-min) (point)))
(list (caar ado-data)
(cdar ado-data)
(current-indentation)))
positions)
- (goto-char (match-end 0))))) ; Go beyond the whole thing
+ (goto-char (match-end 0))))) ; Go beyond the whole thing.
(setq positions (nreverse positions))
(setq rst-all-sections (or positions t)))))
(if (eq rst-all-sections t)
@@ -1274,8 +1253,8 @@
"Return the hierarchy of section titles in the file.
Return a list of adornments that represents the hierarchy of
-section titles in the file. Each element consists of (CHARACTER
-STYLE INDENT) as described for `rst-find-all-adornments'. If the
+section titles in the file. Each element consists of (CHARACTER
+STYLE INDENT) as described for `rst-find-all-adornments'. If the
line number in IGNORE is specified, a possibly adornment found on
that line is not taken into account when building the hierarchy.
@@ -1292,7 +1271,7 @@
(setq rst-section-hierarchy
(if ignore
;; Clear cache reflecting that a possible update is not
- ;; reflected
+ ;; reflected.
nil
(or r t)))
r)))
@@ -1378,19 +1357,19 @@
)))
-;; FIXME: A line "``/`` full" is not accepted as a section title
+;; FIXME: A line "``/`` full" is not accepted as a section title.
(defun rst-adjust (pfxarg)
"Auto-adjust the adornment around point.
-Adjust/rotate the section adornment for the section title
-around point or promote/demote the adornments inside the region,
+Adjust/rotate the section adornment for the section title around
+point or promote/demote the adornments inside the region,
depending on if the region is active. This function is meant to
be invoked possibly multiple times, and can vary its behavior
-with a positive prefix argument (toggle style), or with a
-negative prefix argument (alternate behavior).
+with a positive PFXARG (toggle style), or with a negative
+PFXARG (alternate behavior).
-This function is a bit of a swiss knife. It is meant to adjust
-the adornments of a section title in reStructuredText. It tries
+This function is a bit of a swiss knife. It is meant to adjust
+the adornments of a section title in reStructuredText. It tries
to deal with all the possible cases gracefully and to do `the
right thing' in all cases.
@@ -1403,7 +1382,7 @@
The method can take either (but not both) of
a. a (non-negative) prefix argument, which means to toggle the
- adornment style. Invoke with a prefix arg for example;
+ adornment style. Invoke with a prefix argument for example;
b. a negative numerical argument, which generally inverts the
direction of search in the file or hierarchy. Invoke with C--
@@ -1447,7 +1426,8 @@
(defun rst-adjust-adornment (pfxarg)
"Call `rst-adjust-adornment-work' interactively.
-Keep this for compatibility for older bindings (are there any?)."
+Keep this for compatibility for older bindings (are there any?).
+Argument PFXARG has the same meaning as for `rst-adjust'."
(interactive "P")
(let* ((reverse-direction (and pfxarg (< (prefix-numeric-value pfxarg) 0)))
@@ -1661,7 +1641,7 @@
;; Else, we rotate, ignoring the adornment around the current
;; line...
(let* ((hier (rst-get-hierarchy (line-number-at-pos)))
- ;; Suggestion, in case we need to come up with something new
+ ;; Suggestion, in case we need to come up with something new.
(suggestion (rst-suggest-new-adornment
hier
(car (rst-get-adornments-around))))
@@ -1703,7 +1683,7 @@
marker-list
)
- ;; Skip the markers that come before the region beginning
+ ;; Skip the markers that come before the region beginning.
(while (and cur (< (caar cur) region-begin-line))
(setq cur (cdr cur)))
@@ -1768,7 +1748,7 @@
(interactive)
(rst-reset-section-caches)
(save-excursion
- (let (;; Get a list of pairs of (level . marker)
+ (let (;; Get a list of pairs of (level . marker).
(levels-and-markers (mapcar
(lambda (ado)
(cons (rst-position (cdr ado)
@@ -1779,13 +1759,13 @@
(point-marker))))
(rst-find-all-adornments))))
(dolist (lm levels-and-markers)
- ;; Go to the appropriate position
+ ;; Go to the appropriate position.
(goto-char (cdr lm))
- ;; Apply the new styule
+ ;; Apply the new style.
(apply 'rst-update-section (nth (car lm) rst-preferred-adornments))
- ;; Reset the market to avoid slowing down editing until it gets GC'ed
+ ;; Reset the market to avoid slowing down editing until it gets GC'ed.
(set-marker (cdr lm) nil)
)
)))
@@ -1798,7 +1778,7 @@
;=================================================
-; Borrowed from a2r.el (version 1.3), by Lawrence Mitchell <address@hidden>
+; Borrowed from a2r.el (version 1.3), by Lawrence Mitchell <address@hidden>.
; I needed to make some tiny changes to the functions, so I put it here.
; -- Wei-Wei Guo
@@ -1849,9 +1829,9 @@
(defun rst-find-pfx-in-region (beg end pfx-re)
"Find all the positions of prefixes in region between BEG and END.
-This is used to find bullets and enumerated list items. PFX-RE is
+This is used to find bullets and enumerated list items. PFX-RE is
a regular expression for matching the lines after indentation
-with items. Returns a list of cons cells consisting of the point
+with items. Returns a list of cons cells consisting of the point
and the column of the point."
(let ((pfx ()))
(save-excursion
@@ -1867,14 +1847,14 @@
(or (looking-at (rst-re 'lin-end)) ; ...empty,
(> (current-column) pfx-col) ; ...deeper level, or
(and (= (current-column) pfx-col)
- (looking-at pfx-re)))))) ; ...pfx at same level
+ (looking-at pfx-re)))))) ; ...pfx at same level.
(push (cons (point) (current-column))
pfx))
(forward-line 1)) )
(nreverse pfx)))
(defun rst-insert-list-pos (newitem)
- "Arrange relative position of a newly inserted list item.
+ "Arrange relative position of a newly inserted list item of style NEWITEM.
Adding a new list might consider three situations:
@@ -1922,11 +1902,11 @@
If user selects bullets or #, it's just added with position arranged by
`rst-insert-list-pos'.
-If user selects enumerations, a further prompt is given. User need to input a
+If user selects enumerations, a further prompt is given. User need to input a
starting item, for example 'e' for 'A)' style. The position is also arranged
by
`rst-insert-list-pos'."
(interactive)
- ;; FIXME: Make this comply to `interactive' standards
+ ;; FIXME: Make this comply to `interactive' standards.
(let* ((itemstyle (completing-read
"Select preferred item style [#.]: "
rst-initial-items nil t nil nil "#."))
@@ -1934,7 +1914,7 @@
(match-string 0 itemstyle)))
(no
(save-match-data
- ;; FIXME: Make this comply to `interactive' standards
+ ;; FIXME: Make this comply to `interactive' standards.
(cond
((equal cnt "a")
(let ((itemno (read-string "Give starting value [a]: "
@@ -1969,10 +1949,11 @@
:package-version '(rst . "1.1.0"))
(defun rst-insert-list-continue (curitem prefer-roman)
- "Insert a list item with list start CURITEM including its indentation level."
+ "Insert a list item with list start CURITEM including its indentation level.
+If PREFER-ROMAN roman numbering is preferred over using letters."
(end-of-line)
(insert
- "\n" ; FIXME: Separating lines must be possible
+ "\n" ; FIXME: Separating lines must be possible.
(cond
((string-match (rst-re '(:alt enmaut-tag
bul-tag)) curitem)
@@ -1983,17 +1964,17 @@
nil nil curitem))
((and (string-match (rst-re 'rom-tag) curitem)
(save-match-data
- (if (string-match (rst-re 'ltr-tag) curitem) ; Also a letter tag
+ (if (string-match (rst-re 'ltr-tag) curitem) ; Also a letter tag.
(save-excursion
;; FIXME: Assumes one line list items without separating
- ;; empty lines
+ ;; empty lines.
(if (and (zerop (forward-line -1))
(looking-at (rst-re 'enmexp-beg)))
(string-match
(rst-re 'rom-tag)
- (match-string 0)) ; Previous was a roman tag
- prefer-roman)) ; Don't know - use flag
- t))) ; Not a letter tag
+ (match-string 0)) ; Previous was a roman tag.
+ prefer-roman)) ; Don't know - use flag.
+ t))) ; Not a letter tag.
(replace-match
(let* ((old (match-string 0 curitem))
(new (save-match-data
@@ -2013,13 +1994,13 @@
(defun rst-insert-list (&optional prefer-roman)
"Insert a list item at the current point.
-The command can insert a new list or a continuing list. When it is called at a
-non-list line, it will promote to insert new list. When it is called at a list
+The command can insert a new list or a continuing list. When it is called at a
+non-list line, it will promote to insert new list. When it is called at a list
line, it will insert a list with the same list style.
1. When inserting a new list:
-User is asked to select the item style first, for example (a), i), +. Use TAB
+User is asked to select the item style first, for example (a), i), +. Use TAB
for completion and choices.
(a) If user selects bullets or #, it's just added.
@@ -2036,7 +2017,7 @@
the problem elegantly in most situations. But when those overlapped list are
preceded by a blank line, it is hard to determine which type to use
automatically. The function uses alphabetical list by default. If you want
-roman numerical list, just use a prefix (\\[universal-argument])."
+roman numerical list, just use a prefix to set PREFER-ROMAN."
(interactive "P")
(beginning-of-line)
(if (looking-at (rst-re 'itmany-beg-1))
@@ -2094,8 +2075,8 @@
"Get the hierarchical tree of section titles.
Returns a hierarchical tree of the sections titles in the
-document. This can be used to generate a table of contents for
-the document. The top node will always be a nil node, with the
+document. This can be used to generate a table of contents for
+the document. The top node will always be a nil node, with the
top level titles as children (there may potentially be more than
one).
@@ -2105,7 +2086,7 @@
If there are missing section levels, the section titles are
inserted automatically, and the title string is set to nil, and
the marker set to the first non-nil child of itself.
-Conceptually, the nil nodes--i.e. those which have no title--are
+Conceptually, the nil nodes--i.e.\ those which have no title--are
to be considered as being the same line as their first non-nil
child. This has advantages later in processing the graph."
@@ -2148,14 +2129,14 @@
node
children)
- ;; If the next adornment matches our level
+ ;; If the next adornment matches our level.
(when (and nado (= (car nado) lev))
- ;; Pop the next adornment and create the current node with it
+ ;; Pop the next adornment and create the current node with it.
(setcdr ados (cddr ados))
(setq node (cdr nado)) )
;; Else we let the node title/marker be unset.
- ;; Build the child nodes
+ ;; Build the child nodes.
(while (and (cdr ados) (> (caadr ados) lev))
(setq children
(cons (rst-section-tree-rec ados (1+ lev))
@@ -2175,7 +2156,7 @@
"Find tree node at point.
Given a computed and valid section tree in NODE and a point
POINT (default being the current point in the current buffer),
-find and return the node within the sectree where the cursor
+find and return the node within the section tree where the cursor
lives.
Return values: a pair of (parent path, container subtree).
@@ -2256,7 +2237,7 @@
The TOC is inserted indented at the current column."
(interactive "P")
(rst-reset-section-caches)
- (let* (;; Check maximum level override
+ (let* (;; Check maximum level override.
(rst-toc-insert-max-level
(if (and (integerp pfxarg) (> (prefix-numeric-value pfxarg) 0))
(prefix-numeric-value pfxarg) rst-toc-insert-max-level))
@@ -2333,7 +2314,7 @@
fmt)
(if do-child-numbering
(progn
- ;; Add a separating dot if there is already a prefix
+ ;; Add a separating dot if there is already a prefix.
(when (> (length pfx) 0)
(string-match (rst-re "[ \t\n]*\\'") pfx)
(setq pfx (concat (replace-match "" t t pfx) ".")))
@@ -2385,9 +2366,9 @@
(while (and
(< (point) (point-max))
(or (if (looking-at
- (rst-re 'hws-sta "\\S ")) ; indented content
+ (rst-re 'hws-sta "\\S ")) ; indented content.
(setq last-real (point)))
- (looking-at (rst-re 'lin-end)))) ; empty line
+ (looking-at (rst-re 'lin-end)))) ; empty line.
(forward-line 1))
(if last-real
(progn
@@ -2517,12 +2498,14 @@
;; FIXME: Cursor before or behind the list must be handled properly; before the
;; list should jump to the top and behind the list to the last normal
-;; paragraph
+;; paragraph.
(defun rst-goto-section (&optional kill)
- "Go to the section the current line describes."
+ "Go to the section the current line describes.
+If KILL a toc buffer is destroyed."
(interactive)
(let ((pos (rst-toc-mode-find-section)))
(when kill
+ ;; FIXME: This should rather go to `rst-toc-mode-goto-section'.
(set-window-configuration (car rst-toc-return-wincfg))
(kill-buffer (get-buffer rst-toc-buffer-name)))
(pop-to-buffer (marker-buffer pos))
@@ -2549,7 +2532,8 @@
(recenter 5)))
(defun rst-toc-mode-mouse-goto-kill (event)
- "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well."
+ "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well.
+EVENT is the input event."
(interactive "e")
(call-interactively 'rst-toc-mode-mouse-goto event)
(kill-buffer (get-buffer rst-toc-buffer-name)))
@@ -2582,7 +2566,6 @@
;; Note: use occur-mode (replace.el) as a good example to complete missing
;; features.
-
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Section movement commands
;; =========================
@@ -2633,12 +2616,15 @@
(interactive)
(rst-forward-section -1))
-(defun rst-mark-section (&optional arg allow-extend)
- "Select the section that point is currently in."
+;; FIXME: What is `allow-extend' for?
+(defun rst-mark-section (&optional count allow-extend)
+ "Select COUNT sections around point.
+Mark following sections for positive COUNT or preceding sections
+for negative COUNT."
;; Cloned from mark-paragraph.
(interactive "p\np")
- (unless arg (setq arg 1))
- (when (zerop arg)
+ (unless count (setq count 1))
+ (when (zerop count)
(error "Cannot mark zero sections"))
(cond ((and allow-extend
(or (and (eq last-command this-command) (mark t))
@@ -2646,12 +2632,12 @@
(set-mark
(save-excursion
(goto-char (mark))
- (rst-forward-section arg)
+ (rst-forward-section count)
(point))))
(t
- (rst-forward-section arg)
+ (rst-forward-section count)
(push-mark nil t t)
- (rst-forward-section (- arg)))))
+ (rst-forward-section (- count)))))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -2672,12 +2658,12 @@
(forward-line 1)))
mincol))
+;; FIXME: This definition is old and deprecated. We need to move to the newer
+;; version below.
(defmacro rst-iterate-leftmost-paragraphs
(beg end first-only body-consequent body-alternative)
- "FIXME This definition is old and deprecated / we need to move
-to the newer version below:
-
-Call FUN at the beginning of each line, with an argument that
+ ;; FIXME: The following comment is pretty useless.
+ "Call FUN at the beginning of each line, with an argument that
specifies whether we are at the first line of a paragraph that
starts at the leftmost column of the given region BEG and END.
Set FIRST-ONLY to true if you want to callback on the first line
@@ -2686,7 +2672,7 @@
(let ((leftcol (rst-find-leftmost-column ,beg ,end))
(endm (copy-marker ,end)))
- (do* (;; Iterate lines
+ (do* (;; Iterate lines.
(l (progn (goto-char ,beg) (back-to-indentation))
(progn (forward-line 1) (back-to-indentation)))
@@ -2710,6 +2696,8 @@
))))
+;; FIXME: This needs to be refactored. Probably this is simply a function
+;; applying BODY rather than a macro.
(defmacro rst-iterate-leftmost-paragraphs-2 (spec &rest body)
"Evaluate BODY for each line in region defined by BEG END.
LEFTMOST is set to true if the line is one of the leftmost of the
@@ -2723,7 +2711,7 @@
(let ((,leftmost (rst-find-leftmost-column ,beg ,end))
(endm (copy-marker ,end)))
- (do* (;; Iterate lines
+ (do* (;; Iterate lines.
(l (progn (goto-char ,beg) (back-to-indentation))
(progn (forward-line 1) (back-to-indentation)))
@@ -2751,8 +2739,9 @@
;; Indentation
;; FIXME: At the moment only block comments with leading empty comment line are
-;; supported; comment lines with leading comment markup should be also
-;; supported; may be a customizable option could control which style to prefer
+;; supported. Comment lines with leading comment markup should be also
+;; supported. May be a customizable option could control which style to
+;; prefer.
(defgroup rst-indent nil "Settings for indentation in reStructuredText.
@@ -2772,20 +2761,17 @@
:type '(integer))
(defcustom rst-indent-field 3
- "Default indentation for first line after a field or 0 to always indent for
-content."
+ "Indentation for first line after a field or 0 to always indent for content."
:group 'rst-indent
:type '(integer))
(defcustom rst-indent-literal-normal 3
- "Default indentation for literal block after a markup on an own
-line."
+ "Default indentation for literal block after a markup on an own line."
:group 'rst-indent
:type '(integer))
(defcustom rst-indent-literal-minimized 2
- "Default indentation for literal block after a minimized
-markup."
+ "Default indentation for literal block after a minimized markup."
:group 'rst-indent
:type '(integer))
@@ -2795,30 +2781,30 @@
:type '(integer))
;; FIXME: Must consider other tabs:
-;; * Line blocks
-;; * Definition lists
-;; * Option lists
+;; * Line blocks
+;; * Definition lists
+;; * Option lists
(defun rst-line-tabs ()
"Return tabs of the current line or nil for no tab.
The list is sorted so the tab where writing continues most likely
-is the first one. Each tab is of the form (COLUMN . INNER).
-COLUMN is the column of the tab. INNER is non-nil if this is an
-inner tab. I.e. a tab which does come from the basic indentation
+is the first one. Each tab is of the form (COLUMN . INNER).
+COLUMN is the column of the tab. INNER is non-nil if this is an
+inner tab. I.e. a tab which does come from the basic indentation
and not from inner alignment points."
(save-excursion
(forward-line 0)
(save-match-data
(unless (looking-at (rst-re 'lin-end))
(back-to-indentation)
- ;; Current indentation is always the least likely tab
+ ;; Current indendation is always the least likely tab.
(let ((tabs (list (list (point) 0 nil)))) ; (POINT OFFSET INNER)
- ;; Push inner tabs more likely to continue writing
+ ;; Push inner tabs more likely to continue writing.
(cond
- ;; Item
+ ;; Item.
((looking-at (rst-re '(:grp itmany-tag hws-sta) '(:grp "\\S ") "?"))
(when (match-string 2)
(push (list (match-beginning 2) 0 t) tabs)))
- ;; Field
+ ;; Field.
((looking-at (rst-re '(:grp fld-tag) '(:grp hws-tag)
'(:grp "\\S ") "?"))
(unless (zerop rst-indent-field)
@@ -2829,22 +2815,22 @@
(push (list (match-end 2)
(if (string= (match-string 2) "") 1 0)
t) tabs))))
- ;; Directive
+ ;; Directive.
((looking-at (rst-re 'dir-sta-3 '(:grp "\\S ") "?"))
(push (list (match-end 1) 0 t) tabs)
(unless (string= (match-string 2) "")
(push (list (match-end 2) 0 t) tabs))
(when (match-string 4)
(push (list (match-beginning 4) 0 t) tabs)))
- ;; Footnote or citation definition
+ ;; Footnote or citation definition.
((looking-at (rst-re 'fnc-sta-2 '(:grp "\\S ") "?"))
(push (list (match-end 1) 0 t) tabs)
(when (match-string 3)
(push (list (match-beginning 3) 0 t) tabs)))
- ;; Comment
+ ;; Comment.
((looking-at (rst-re 'cmt-sta-1))
(push (list (point) rst-indent-comment t) tabs)))
- ;; Start of literal block
+ ;; Start of literal block.
(when (looking-at (rst-re 'lit-sta-2))
(let ((tab0 (first tabs)))
(push (list (first tab0)
@@ -2861,14 +2847,14 @@
(defun rst-compute-tabs (pt)
"Build the list of possible tabs for all lines above.
Search backwards from point PT to build the list of possible
-tabs. Return a list of tabs sorted by likeliness to continue
-writing like `rst-line-tabs'. Nearer lines have generally a
-higher likeliness than farther lines. Return nil if no tab is found
+tabs. Return a list of tabs sorted by likeliness to continue
+writing like `rst-line-tabs'. Nearer lines have generally a
+higher likeliness than farther lines. Return nil if no tab is found
in the text above."
(save-excursion
(goto-char pt)
- (let (leftmost ; Leftmost column found so far
- innermost ; Leftmost column for inner tab
+ (let (leftmost ; Leftmost column found so far.
+ innermost ; Leftmost column for inner tab.
tablist)
(while (and (zerop (forward-line -1))
(or (not leftmost)
@@ -2876,7 +2862,7 @@
(let* ((tabs (rst-line-tabs))
(leftcol (if tabs (apply 'min (mapcar 'car tabs)))))
(when tabs
- ;; Consider only lines indented less or same if not INNERMOST
+ ;; Consider only lines indented less or same if not INNERMOST.
(when (or (not leftmost)
(< leftcol leftmost)
(and (not innermost) (= leftcol leftmost)))
@@ -2894,7 +2880,7 @@
(not (memq newcol tablist)))
(push newcol tablist))))
(setq innermost (if (some 'identity
- (mapcar 'cdr tabs)) ; Has inner
+ (mapcar 'cdr tabs)) ; Has inner.
leftcol
innermost))
(setq leftmost leftcol)))))
@@ -2903,13 +2889,13 @@
(defun rst-indent-line (&optional dflt)
"Indent current line to next best reStructuredText tab.
The next best tab is taken from the tab list returned by
-`rst-compute-tabs' which is used in a cyclic manner. If the
-current indentation does not end on a tab use the first one. If
-the current indentation is on a tab use the next tab. This allows
+`rst-compute-tabs' which is used in a cyclic manner. If the
+current indentation does not end on a tab use the first one. If
+the current indentation is on a tab use the next tab. This allows
a repeated use of \\[indent-for-tab-command] to cycle through all
-possible tabs. If no indentation is possible return `noindent' or
-use DFLT. Return the indentation indented to. When point is in
-indentation it ends up at its end. Otherwise the point is kept
+possible tabs. If no indentation is possible return `noindent' or
+use DFLT. Return the indentation indented to. When point is in
+indentation it ends up at its end. Otherwise the point is kept
relative to the content."
(let* ((pt (point-marker))
(cur (current-indentation))
@@ -2936,46 +2922,46 @@
(defun rst-shift-region (beg end cnt)
"Shift region BEG to END by CNT tabs.
Shift by one tab to the right (CNT > 0) or left (CNT < 0) or
-remove all indentation (CNT = 0). An tab is taken from the text
-above. If no suitable tab is found `rst-indent-width' is used."
+remove all indentation (CNT = 0). A tab is taken from the text
+above. If no suitable tab is found `rst-indent-width' is used."
(interactive "r\np")
(let ((tabs (sort (rst-compute-tabs beg) (lambda (x y) (<= x y))))
(leftmostcol (rst-find-leftmost-column beg end)))
(when (or (> leftmostcol 0) (> cnt 0))
- ;; Apply the indent
+ ;; Apply the indent.
(indent-rigidly
beg end
(if (zerop cnt)
(- leftmostcol)
- ;; Find the next tab after the leftmost column
+ ;; Find the next tab after the leftmost column.
(let* ((cmp (if (> cnt 0) '> '<))
(tabs (if (> cnt 0) tabs (reverse tabs)))
(len (length tabs))
- (dir (signum cnt)) ; Direction to take
- (abs (abs cnt)) ; Absolute number of steps to take
- ;; Get the position of the first tab beyond leftmostcol
+ (dir (signum cnt)) ; Direction to take.
+ (abs (abs cnt)) ; Absolute number of steps to take.
+ ;; Get the position of the first tab beyond leftmostcol.
(fnd (position-if (lambda (elt)
(funcall cmp elt leftmostcol))
tabs))
- ;; Virtual position of tab
+ ;; Virtual position of tab.
(pos (+ (or fnd len) (1- abs)))
(tab (if (< pos len)
- ;; Tab exists - use it
+ ;; Tab exists - use it.
(nth pos tabs)
- ;; Column needs to be computed
+ ;; Column needs to be computed.
(let ((col (+ (or (car (last tabs)) leftmostcol)
- ;; Base on last known column
- (* (- pos (1- len)) ; Distance left
- dir ; Direction to take
+ ;; Base on last known column.
+ (* (- pos (1- len)) ; Distance left.
+ dir ; Direction to take.
rst-indent-width))))
(if (< col 0) 0 col)))))
(- tab leftmostcol)))))))
;; FIXME: A paragraph with an (incorrectly) indented second line is not filled
-;; correctly::
+;; correctly::
;;
-;; Some start
-;; continued wrong
+;; Some start
+;; continued wrong
(defun rst-adaptive-fill ()
"Return fill prefix found at point.
Value for `adaptive-fill-function'."
@@ -2983,9 +2969,9 @@
(match-string-no-properties 0))))
(if (save-match-data
(not (string-match comment-start-skip fnd)))
- ;; An non-comment prefix is fine
+ ;; An non-comment prefix is fine.
fnd
- ;; Matches a comment - return whitespace instead
+ ;; Matches a comment - return whitespace instead.
(make-string (-
(save-excursion
(goto-char (match-end 0))
@@ -2999,7 +2985,8 @@
(defun rst-comment-line-break (&optional soft)
"Break line and indent, continuing reStructuredText comment if within one.
-Value for `comment-line-break-function'."
+Value for `comment-line-break-function'. If SOFT use soft
+newlines as mandated by `comment-line-break-function'."
(if soft
(insert-and-inherit ?\n)
(newline 1))
@@ -3021,7 +3008,8 @@
(insert comment-start))
(defun rst-comment-region (beg end &optional arg)
- "Comment the current region or uncomment it if ARG is
\\[universal-argument]."
+ "Comment or uncomment the current region.
+Region is from from BEG to END. Uncomment if ARG."
(save-excursion
(if (consp arg)
(rst-uncomment-region beg end arg)
@@ -3038,7 +3026,7 @@
(defun rst-uncomment-region (beg end &optional arg)
"Uncomment the current region.
-ARG is ignored"
+Region is from BEG to END. ARG is ignored"
(save-excursion
(let (bol eol)
(goto-char beg)
@@ -3051,9 +3039,9 @@
;;------------------------------------------------------------------------------
-;; FIXME: these next functions should become part of a larger effort to redo
the
-;; bullets in bulleted lists. The enumerate would just be one of the possible
-;; outputs.
+;; FIXME: These next functions should become part of a larger effort to redo
+;; the bullets in bulleted lists. The enumerate would just be one of
+;; the possible outputs.
;;
;; FIXME: We need to do the enumeration removal as well.
@@ -3083,12 +3071,12 @@
(insert " ")
))
-;; FIXME: Does not deal with a varying number of digits appropriately
-;; FIXME: Does not deal with multiple levels independently
-;; FIXME: Does not indent a multiline item correctly
+;; FIXME: Does not deal with a varying number of digits appropriately.
+;; FIXME: Does not deal with multiple levels independently.
+;; FIXME: Does not indent a multiline item correctly.
(defun rst-convert-bullets-to-enumeration (beg end)
"Convert the bulleted and enumerated items in the region to enumerated lists.
-Renumber as necessary."
+Renumber as necessary. Region is from BEG to END."
(interactive "r")
(let* (;; Find items and convert the positions to markers.
(items (mapcar
@@ -3113,7 +3101,7 @@
(defun rst-line-block-region (rbeg rend &optional pfxarg)
"Toggle line block prefixes for a region.
-With prefix argument set the empty lines too."
+Region is from RBEG to REND. With PFXARG set the empty lines too."
(interactive "r\nP")
(let ((comment-start "| ")
(comment-end "")
@@ -3135,7 +3123,7 @@
(require 'font-lock)
-;; FIXME: The obsolete variables need to disappear
+;; FIXME: The obsolete variables need to disappear.
(defgroup rst-faces nil "Faces used in Rst Mode."
:group 'rst
@@ -3279,9 +3267,10 @@
:version "21.1")
(defun rst-set-level-default (sym val)
- "Set custom var SYM affecting section title text face and recompute the
faces."
+ "Set custom variable SYM affecting section title text face.
+Recompute the faces. VAL is the value to set."
(custom-set-default sym val)
- ;; Also defines the faces initially when all values are available
+ ;; Also defines the faces initially when all values are available.
(and (boundp 'rst-level-face-max)
(boundp 'rst-level-face-format-light)
(boundp 'rst-level-face-base-color)
@@ -3290,9 +3279,9 @@
(fboundp 'rst-define-level-faces)
(rst-define-level-faces)))
-;; Faces for displaying items on several levels; these definitions define
+;; Faces for displaying items on several levels. These definitions define
;; different shades of gray where the lightest one (i.e. least contrasting) is
-;; used for level 1
+;; used for level 1.
(defcustom rst-level-face-max 6
"Maximum depth of levels for which section title faces are defined."
:group 'rst-faces-defaults
@@ -3362,10 +3351,10 @@
:value-type (face))
:set-after '(rst-level-face-max))
-;; FIXME: It should be possible to give "#RRGGBB" type of color values
+;; FIXME: It should be possible to give "#RRGGBB" type of color values.
(defun rst-define-level-faces ()
"Define the faces for the section title text faces from the values."
- ;; All variables used here must be checked in `rst-set-level-default'
+ ;; All variables used here must be checked in `rst-set-level-default'.
(let ((i 1))
(while (<= i rst-level-face-max)
(let ((sym (intern (format "rst-level-%d-face" i)))
@@ -3387,19 +3376,20 @@
(defvar rst-font-lock-keywords
;; The reST-links in the comments below all relate to sections in
- ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+ ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
`(;; FIXME: Block markup is not recognized in blocks after explicit markup
- ;; start
+ ;; start.
;; Simple `Body Elements`_
;; `Bullet Lists`_
- ;; FIXME: A bullet directly after a field name is not recognized
+ ;; FIXME: A bullet directly after a field name is not recognized.
(,(rst-re 'lin-beg '(:grp bul-sta))
1 rst-block-face)
;; `Enumerated Lists`_
(,(rst-re 'lin-beg '(:grp enmany-sta))
1 rst-block-face)
- ;; `Definition Lists`_ FIXME: missing
+ ;; `Definition Lists`_
+ ;; FIXME: missing.
;; `Field Lists`_
(,(rst-re 'lin-beg '(:grp fld-tag) 'bli-sfx)
1 rst-external-face)
@@ -3408,11 +3398,12 @@
'(:alt "$" (:seq hws-prt "\\{2\\}")))
1 rst-block-face)
;; `Line Blocks`_
- ;; Only for lines containing no more bar - to distinguish from tables
+ ;; Only for lines containing no more bar - to distinguish from tables.
(,(rst-re 'lin-beg '(:grp "|" bli-sfx) "[^|\n]*$")
1 rst-block-face)
- ;; `Tables`_ FIXME: missing
+ ;; `Tables`_
+ ;; FIXME: missing
;; All the `Explicit Markup Blocks`_
;; `Footnotes`_ / `Citations`_
@@ -3434,11 +3425,11 @@
(,(rst-re 'lin-beg '(:grp "__") 'bli-sfx)
1 rst-definition-face)
- ;; All `Inline Markup`_ - most of them may be multiline though this is
- ;; uninteresting
+ ;; All `Inline Markup`_
+ ;; Most of them may be multiline though this is uninteresting.
;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented
- ;; `Strong Emphasis`_
+ ;; `Strong Emphasis`_.
(,(rst-re 'ilm-pfx '(:grp "\\*\\*" ilcast-tag "\\*\\*") 'ilm-sfx)
1 rst-emphasis2-face)
;; `Emphasis`_
@@ -3451,9 +3442,9 @@
(,(rst-re 'ilm-pfx '(:grp "_`" ilcbkq-tag "`") 'ilm-sfx)
1 rst-definition-face)
;; `Hyperlink References`_
- ;; FIXME: `Embedded URIs`_ not considered
+ ;; FIXME: `Embedded URIs`_ not considered.
;; FIXME: Directly adjacent marked up words are not fontified correctly
- ;; unless they are not separated by two spaces: foo_ bar_
+ ;; unless they are not separated by two spaces: foo_ bar_.
(,(rst-re 'ilm-pfx '(:grp (:alt (:seq "`" ilcbkq-tag "`")
(:seq "\\sw" (:alt "\\sw" "-") "+\\sw"))
"__?") 'ilm-sfx)
@@ -3470,19 +3461,20 @@
1 rst-reference-face)
;; `Substitution References`_
;; FIXME: References substitutions like |this|_ or |this|__ are not
- ;; fontified correctly
+ ;; fontified correctly.
(,(rst-re 'ilm-pfx '(:grp sub-tag) 'ilm-sfx)
1 rst-reference-face)
;; `Standalone Hyperlinks`_
- ;; FIXME: This takes it easy by using a whitespace as delimiter
+ ;; FIXME: This takes it easy by using a whitespace as delimiter.
(,(rst-re 'ilm-pfx '(:grp uri-tag ":\\S +") 'ilm-sfx)
1 rst-definition-face)
(,(rst-re 'ilm-pfx '(:grp sym-tag "@" sym-tag ) 'ilm-sfx)
1 rst-definition-face)
- ;; Do all block fontification as late as possible so 'append works
+ ;; Do all block fontification as late as possible so 'append works.
- ;; Sections_ / Transitions_ - for sections this is multiline
+ ;; Sections_ / Transitions_
+ ;; For sections this is multiline.
(,(rst-re 'ado-beg-2-1)
(rst-font-lock-handle-adornment-matcher
(rst-font-lock-handle-adornment-pre-match-form
@@ -3495,13 +3487,14 @@
;; FIXME: FACESPEC could be used instead of ordinary faces to set
;; properties on comments and literal blocks so they are *not*
- ;; inline fontified; see (elisp)Search-based Fontification
+ ;; inline fontified. See (elisp)Search-based Fontification.
;; FIXME: And / or use `syntax-propertize` functions as in `octave-mod.el`
- ;; and other V24 modes; may make `font-lock-extend-region`
- ;; superfluous
+ ;; and other V24 modes. May make `font-lock-extend-region`
+ ;; superfluous.
- ;; `Comments`_ - this is multiline
+ ;; `Comments`_
+ ;; This is multiline.
(,(rst-re 'lin-beg 'cmt-sta-1)
(1 rst-comment-face)
(rst-font-lock-find-unindented-line-match
@@ -3517,9 +3510,9 @@
(0 rst-comment-face append)))
;; FIXME: This is not rendered as comment::
- ;; .. .. list-table::
- ;; :stub-columns: 1
- ;; :header-rows: 1
+ ;; .. .. list-table::
+ ;; :stub-columns: 1
+ ;; :header-rows: 1
;; FIXME: This is rendered wrong::
;;
@@ -3535,7 +3528,8 @@
;; Indentation needs to be taken from the line with the ``::`` and not from
;; the first content line.
- ;; `Indented Literal Blocks`_ - this is multiline
+ ;; `Indented Literal Blocks`_
+ ;; This is multiline.
(,(rst-re 'lin-beg 'lit-sta-2)
(2 rst-block-face)
(rst-font-lock-find-unindented-line-match
@@ -3543,7 +3537,8 @@
nil
(0 rst-literal-face append)))
- ;; FIXME: `Quoted Literal Blocks`_ missing - this is multiline
+ ;; FIXME: `Quoted Literal Blocks`_ missing.
+ ;; This is multiline.
;; `Doctest Blocks`_
;; FIXME: This is wrong according to the specification:
@@ -3576,8 +3571,9 @@
(defvar font-lock-end)
(defun rst-font-lock-extend-region ()
- "Extend the region `font-lock-beg' / `font-lock-end' iff it may
-be in the middle of a multiline construct and return non-nil if so."
+ "Extend the font-lock region if it might be in a multi-line construct.
+Return non-nil if so. Font-lock region is from `font-lock-beg'
+to `font-lock-end'."
(let ((r (rst-font-lock-extend-region-internal font-lock-beg font-lock-end)))
(when r
(setq font-lock-beg (car r))
@@ -3585,7 +3581,7 @@
t)))
(defun rst-font-lock-extend-region-internal (beg end)
- "Check the region BEG / END for being in the middle of a multiline construct.
+ "Check the region BEG / END for being in the middle of a multi-line
construct.
Return nil if not or a cons with new values for BEG / END"
(let ((nbeg (rst-font-lock-extend-region-extend beg -1))
(nend (rst-font-lock-extend-region-extend end 1)))
@@ -3593,7 +3589,8 @@
(cons (or nbeg beg) (or nend end)))))
(defun rst-forward-line (&optional n)
- "Like `forward-line' but always end up in column 0 and return accordingly."
+ "Like `forward-line' but always end up in column 0 and return accordingly.
+Move N lines forward just as `forward-line'."
(let ((moved (forward-line n)))
(if (bolp)
moved
@@ -3616,41 +3613,41 @@
;;
;; The second group consists of the adornment cases.
(if (not (get-text-property pt 'font-lock-multiline))
- ;; Move only if we don't start inside a multiline construct already
+ ;; Move only if we don't start inside a multiline construct already.
(save-excursion
- (let (;; non-empty non-indented line, explicit markup tag or literal
- ;; block tag
+ (let (;; Non-empty non-indented line, explicit markup tag or literal
+ ;; block tag.
(stop-re (rst-re '(:alt "[^ \t\n]"
(:seq hws-tag exm-tag)
(:seq ".*" dcl-tag lin-end)))))
- ;; The comments below are for dir == -1 / dir == 1
+ ;; The comments below are for dir == -1 / dir == 1.
(goto-char pt)
(forward-line 0)
(setq pt (point))
(while (and (not (looking-at stop-re))
(zerop (rst-forward-line dir)))) ; try previous / next
- ; line if it exists
+ ; line if it exists.
(if (looking-at (rst-re 'ado-beg-2-1)) ; may be an underline /
- ; overline
+ ; overline.
(if (zerop (rst-forward-line dir))
(if (looking-at (rst-re 'ttl-beg)) ; title found, i.e.
; underline / overline
- ; found
+ ; found.
(if (zerop (rst-forward-line dir))
(if (not
(looking-at (rst-re 'ado-beg-2-1))) ; no
; overline /
- ; underline
+ ; underline.
(rst-forward-line (- dir)))) ; step back to title
- ; / adornment
- (if (< dir 0) ; keep downward adornment
- (rst-forward-line (- dir))))) ; step back to adornment
- (if (looking-at (rst-re 'ttl-beg)) ; may be a title
+ ; / adornment.
+ (if (< dir 0) ; keep downward adornment.
+ (rst-forward-line (- dir))))) ; step back to adornment.
+ (if (looking-at (rst-re 'ttl-beg)) ; may be a title.
(if (zerop (rst-forward-line dir))
(if (not
(looking-at (rst-re 'ado-beg-2-1))) ; no overline /
- ; underline
- (rst-forward-line (- dir)))))) ; step back to line
+ ; underline.
+ (rst-forward-line (- dir)))))) ; step back to line.
(if (not (= (point) pt))
(point))))))
@@ -3676,20 +3673,21 @@
(when (< (point) limit)
(setq beg (point))
(if (looking-at (rst-re 'lin-end))
- (setq cand (or cand beg)) ; An empty line is a candidate
+ (setq cand (or cand beg)) ; An empty line is a candidate.
(move-to-column clm)
;; FIXME: No indentation [(zerop clm)] must be handled in some
- ;; useful way - though it is not clear what this should mean at all
+ ;; useful way - though it is not clear what this should mean
+ ;; at all.
(if (string-match
(rst-re 'linemp-tag)
(buffer-substring-no-properties beg (point)))
- (setq cand nil) ; An indented line resets a candidate
+ (setq cand nil) ; An indented line resets a candidate.
(setq fnd (or cand beg)))))))
(goto-char (or fnd start))
fnd))
(defvar rst-font-lock-find-unindented-line-begin nil
- "Beginning of the match if `rst-font-lock-find-unindented-line-end'")
+ "Beginning of the match if `rst-font-lock-find-unindented-line-end'.")
(defvar rst-font-lock-find-unindented-line-end nil
"End of the match as determined by
`rst-font-lock-find-unindented-line-limit'.
@@ -3700,7 +3698,7 @@
"Find the next unindented line relative to indentation at IND-PNT.
Return this point, the end of the buffer or nil if nothing found.
If IND-PNT is `next' take the indentation from the next line if
-this is not empty and indented more than the current one. If
+this is not empty and indented more than the current one. If
IND-PNT is non-nil but not a number take the indentation from the
next non-empty line if this is indented more than the current
one."
@@ -3708,34 +3706,34 @@
(setq rst-font-lock-find-unindented-line-end
(save-excursion
(when (not (numberp ind-pnt))
- ;; Find indentation point in next line if any
+ ;; Find indentation point in next line if any.
(setq ind-pnt
;; FIXME: Should be refactored to two different functions
;; giving their result to this function, may be
- ;; integrated in caller
+ ;; integrated in caller.
(save-match-data
(let ((cur-ind (current-indentation)))
(if (eq ind-pnt 'next)
(when (and (zerop (forward-line 1))
(< (point) (point-max)))
- ;; Not at EOF
+ ;; Not at EOF.
(setq rst-font-lock-find-unindented-line-begin
(point))
(when (and (not (looking-at (rst-re 'lin-end)))
(> (current-indentation) cur-ind))
- ;; Use end of indentation if non-empty line
+ ;; Use end of indentation if non-empty line.
(looking-at (rst-re 'hws-tag))
(match-end 0)))
- ;; Skip until non-empty line or EOF
+ ;; Skip until non-empty line or EOF.
(while (and (zerop (forward-line 1))
(< (point) (point-max))
(looking-at (rst-re 'lin-end))))
(when (< (point) (point-max))
- ;; Not at EOF
+ ;; Not at EOF.
(setq rst-font-lock-find-unindented-line-begin
(point))
(when (> (current-indentation) cur-ind)
- ;; Indentation bigger than line of departure
+ ;; Indentation bigger than line of departure.
(looking-at (rst-re 'hws-tag))
(match-end 0))))))))
(when ind-pnt
@@ -3744,9 +3742,11 @@
(point-max))))))
(defun rst-font-lock-find-unindented-line-match (limit)
- "Set the match found by
+ "Set the match found earlier if match were found.
+Match has been found by
`rst-font-lock-find-unindented-line-limit' the first time called
-or nil."
+or no match is found. Return non-nil if match was found. LIMIT
+is not used but mandated by the caller."
(when rst-font-lock-find-unindented-line-end
(set-match-data
(list rst-font-lock-find-unindented-line-begin
@@ -3754,7 +3754,7 @@
(put-text-property rst-font-lock-find-unindented-line-begin
rst-font-lock-find-unindented-line-end
'font-lock-multiline t)
- ;; Make sure this is called only once
+ ;; Make sure this is called only once.
(setq rst-font-lock-find-unindented-line-end nil)
t))
@@ -3768,8 +3768,8 @@
(defun rst-adornment-level (key)
"Return section level for adornment KEY.
KEY is the first element of the return list of
-`rst-classify-adornment'. If KEY is not a cons return it. If KEY is found
-in the hierarchy return its level. Otherwise return a level one
+`rst-classify-adornment'. If KEY is not a cons return it. If KEY is found
+in the hierarchy return its level. Otherwise return a level one
beyond the existing hierarchy."
(if (not (consp key))
key
@@ -3783,15 +3783,16 @@
(defvar rst-font-lock-adornment-match nil
"Storage for match for current adornment.
-Set by `rst-font-lock-handle-adornment-pre-match-form'. Also used
+Set by `rst-font-lock-handle-adornment-pre-match-form'. Also used
as a trigger for `rst-font-lock-handle-adornment-matcher'.")
(defun rst-font-lock-handle-adornment-pre-match-form (ado ado-end)
- "Determine limit for adornments for font-locking section titles and
transitions.
-In fact determine all things necessary and put the result to
+ "Determine limit for adornments.
+Determine all things necessary for font-locking section titles
+and transitions and put the result to
`rst-font-lock-adornment-match' and
-`rst-font-lock-adornment-level'. ADO is the complete adornment
-matched. ADO-END is the point where ADO ends. Return the point
+`rst-font-lock-adornment-level'. ADO is the complete adornment
+matched. ADO-END is the point where ADO ends. Return the point
where the whole adorned construct ends.
Called as a PRE-MATCH-FORM in the sense of `font-lock-keywords'."
@@ -3802,16 +3803,19 @@
(setq rst-font-lock-adornment-level
(rst-adornment-level (car ado-data)))
(setq rst-font-lock-adornment-match (cdr ado-data))
- (goto-char (nth 1 ado-data)) ; Beginning of construct
- (nth 2 ado-data)))) ; End of construct
+ (goto-char (nth 1 ado-data)) ; Beginning of construct.
+ (nth 2 ado-data)))) ; End of construct.
(defun rst-font-lock-handle-adornment-matcher (limit)
- "Set the match found by `rst-font-lock-handle-adornment-pre-match-form'
-the first time called or nil.
+ "Set the match found earlier if match were found.
+Match has been found by
+`rst-font-lock-handle-adornment-pre-match-form' the first time
+called or no match is found. Return non-nil if match was found.
-Called as a MATCHER in the sense of `font-lock-keywords'."
+Called as a MATCHER in the sense of `font-lock-keywords'.
+LIMIT is not used but mandated by the caller."
(let ((match rst-font-lock-adornment-match))
- ;; May run only once - enforce this
+ ;; May run only once - enforce this.
(setq rst-font-lock-adornment-match nil)
(when match
(set-match-data match)
@@ -3847,12 +3851,12 @@
".pdf" nil)
(s5 ,(if (executable-find "rst2s5.py") "rst2s5.py" "rst2s5")
".html" nil))
- "Table describing the command to use for each toolset.
-An association list of the toolset to a list of the (command to use,
+ "Table describing the command to use for each tool-set.
+An association list of the tool-set to a list of the (command to use,
extension of produced filename, options to the tool (nil or a
string)) to be used for converting the document."
;; FIXME: These are not options but symbols which may be referenced by
- ;; `rst-compile-*-toolset` below
+ ;; `rst-compile-*-toolset` below.
:type '(alist :options (html latex newlatex pseudoxml xml pdf s5)
:key-type symbol
:value-type (list :tag "Specification"
@@ -3864,13 +3868,13 @@
:group 'rst
:version "24.1")
-;; FIXME: Must be `defcustom`
+;; FIXME: Must be `defcustom`.
(defvar rst-compile-primary-toolset 'html
- "The default toolset for `rst-compile'.")
+ "The default tool-set for `rst-compile'.")
-;; FIXME: Must be `defcustom`
+;; FIXME: Must be `defcustom`.
(defvar rst-compile-secondary-toolset 'latex
- "The default toolset for `rst-compile' with a prefix argument.")
+ "The default tool-set for `rst-compile' with a prefix argument.")
(defun rst-compile-find-conf ()
"Look for the configuration file in the parents of the current path."
@@ -3900,7 +3904,7 @@
"Compile command to convert reST document into some output file.
Attempts to find configuration file, if it can, overrides the
options. There are two commands to choose from, with USE-ALT,
-select the alternative toolset."
+select the alternative tool-set."
(interactive "P")
;; Note: maybe we want to check if there is a Makefile too and not do
anything
;; if that is the case. I dunno.
@@ -3934,13 +3938,15 @@
))
(defun rst-compile-alt-toolset ()
- "Compile command with the alternative toolset."
+ "Compile command with the alternative tool-set."
(interactive)
(rst-compile t))
(defun rst-compile-pseudo-region ()
- "Show the pseudo-XML rendering of the current active region,
-or of the entire buffer, if the region is not selected."
+ "Show pseudo-XML rendering.
+Rendering is done of the current active region, or of the entire
+buffer, if the region is not selected."
+ ;; FIXME: The region should be given interactively.
(interactive)
(with-output-to-temp-buffer "*pseudoxml*"
(shell-command-on-region
@@ -3949,7 +3955,7 @@
(cadr (assq 'pseudoxml rst-compile-toolsets))
standard-output)))
-;; FIXME: Should be `defcustom`
+;; FIXME: Should be `defcustom`.
(defvar rst-pdf-program "xpdf"
"Program used to preview PDF files.")
@@ -3966,7 +3972,7 @@
;; output.
))
-;; FIXME: Should be `defcustom` or use something like `browse-url`
+;; FIXME: Should be `defcustom` or use something like `browse-url`.
(defvar rst-slides-program "firefox"
"Program used to preview S5 slides.")
@@ -3987,10 +3993,9 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Generic text functions that are more convenient than the defaults.
-;; FIXME: Unbound command - should be bound or removed
+;; FIXME: Unbound command - should be bound or removed.
(defun rst-replace-lines (fromchar tochar)
- "Replace flush-left lines, consisting of multiple FROMCHAR characters,
-with equal-length lines of TOCHAR."
+ "Replace flush-left lines of FROMCHAR with equal-length lines of TOCHAR."
(interactive "\
cSearch for flush-left lines of char:
cand replace with char: ")
@@ -4005,14 +4010,14 @@
(insert-char tochar width)))
(message (format "%d lines replaced." found)))))
-;; FIXME: Unbound command - should be bound or removed
+;; FIXME: Unbound command - should be bound or removed.
(defun rst-join-paragraph ()
"Join lines in current paragraph into one line, removing end-of-lines."
(interactive)
- (let ((fill-column 65000)) ; some big number
+ (let ((fill-column 65000)) ; some big number.
(call-interactively 'fill-paragraph)))
-;; FIXME: Unbound command - should be bound or removed
+;; FIXME: Unbound command - should be bound or removed.
(defun rst-force-fill-paragraph ()
"Fill paragraph at point, first joining the paragraph's lines into one.
This is useful for filling list item paragraphs."
@@ -4021,14 +4026,14 @@
(fill-paragraph nil))
-;; FIXME: Unbound command - should be bound or removed
+;; FIXME: Unbound command - should be bound or removed.
;; Generic character repeater function.
;; For sections, better to use the specialized function above, but this can
;; be useful for creating separators.
(defun rst-repeat-last-character (use-next)
- "Fill the current line up to the length of the preceding line (if not
-empty), using the last character on the current line. If the preceding line is
-empty, we use the `fill-column'.
+ "Fill the current line using the last character on the current line.
+Fill up to the length of the preceding line or up to
+`fill-column' if preceding line is empty.
If USE-NEXT, use the next line rather than the preceding line.
@@ -4058,18 +4063,19 @@
)) )
(end-of-line)
(if (> (current-column) rightmost-column)
- ;; shave characters off the end
+ ;; Shave characters off the end.
(delete-region (- (point)
(- (current-column) rightmost-column))
(point))
- ;; fill with last characters
+ ;; Fill with last characters.
(insert-char (preceding-char)
(- rightmost-column (current-column))))
))
(defun rst-portable-mark-active-p ()
- "A portable function that returns non-nil if the mark is active."
+ "Return non-nil if the mark is active.
+This is a portable function."
(cond
((fboundp 'region-active-p) (region-active-p))
((boundp 'transient-mark-mode) (and transient-mark-mode mark-active))
@@ -4077,4 +4083,13 @@
(provide 'rst)
-;;; rst.el ends here
+
+;; LocalWords: docutils http sourceforge rst html wp svn svnroot txt reST
regex
+;; LocalWords: regexes alist seq alt grp keymap abbrev overline overlines toc
+;; LocalWords: XML PNT propertized referencable
+
+;; Local Variables:
+;; sentence-end-double-space: t
+;; End:
+
+;;; rst.el ends here.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r108425: Silence `checkdoc-ispell' errors where possible. Fix authors. Improve,
Stefan Merten <=