Commit 57348c4d authored by Juanma Barranquero's avatar Juanma Barranquero

lisp/textmodes/rst.el: Implement missing but documented functionality.

(rst-arabic-to-roman, rst-roman-to-arabic):
Implement inserting into current buffer, documented in their docstrings.
(rst-define-key, rst-compare-adornments, rst-insert-list-new-item)
(rst-section-tree-point, rst-forward-section, rst-indent)
(rst-compute-tabs, rst-font-lock-find-unindented-line-end)
(rst-font-lock-find-unindented-line-limit, rst-adornment-level)
(rst-font-lock-handle-adornment-pre-match-form)
(rst-repeat-last-character): Reflow docstrings.
(rst-preferred-adornments, rst-update-section, rst-find-title-line)
(rst-adjust-adornment-work, rst-initial-items, rst-insert-list)
(rst-toc-insert-style, rst-toc-insert-node, rst-goto-section)
(rst-compile, rst-imenu-convert-cell, rst-imenu-create-index):
Fix docstring typos.
(rst-all-sections, rst-section-hierarchy, rst-adjust): Doc fixes.
(rst-uncomment-region, rst-font-lock-find-unindented-line-match)
(rst-font-lock-handle-adornment-matcher): Mark unused arguments.
parent 7ea9a62b
2014-03-16 Juanma Barranquero <lekktu@gmail.com>
* textmodes/rst.el (rst-arabic-to-roman, rst-roman-to-arabic):
Implement inserting into current buffer, documented in their docstrings.
(rst-define-key, rst-compare-adornments, rst-insert-list-new-item)
(rst-section-tree-point, rst-forward-section, rst-indent)
(rst-compute-tabs, rst-font-lock-find-unindented-line-end)
(rst-font-lock-find-unindented-line-limit, rst-adornment-level)
(rst-font-lock-handle-adornment-pre-match-form)
(rst-repeat-last-character): Reflow docstrings.
(rst-preferred-adornments, rst-update-section, rst-find-title-line)
(rst-adjust-adornment-work, rst-initial-items, rst-insert-list)
(rst-toc-insert-style, rst-toc-insert-node, rst-goto-section)
(rst-compile, rst-imenu-convert-cell, rst-imenu-create-index):
Fix docstring typos.
(rst-all-sections, rst-section-hierarchy, rst-adjust): Doc fixes.
(rst-uncomment-region, rst-font-lock-find-unindented-line-match)
(rst-font-lock-handle-adornment-matcher): Mark unused arguments.
2014-03-15 Juanma Barranquero <lekktu@gmail.com>
* term/ns-win.el (x-command-line-resources): Rename from ns-... version,
......
......@@ -608,8 +608,8 @@ After interpretation of ARGS the results are concatenated as for
(defun rst-define-key (keymap key def &rest deprecated)
"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."
definitions should be in vector notation. These are defined
as well but give an additional message."
(define-key keymap key def)
(when deprecated
(let* ((command-name (symbol-name def))
......@@ -994,10 +994,10 @@ for modes derived from Text mode, like Mail mode."
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
places t instead of a list stands for a transition.
`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
when we rotate the underlines at the end of the existing
......@@ -1034,8 +1034,8 @@ style."
(defun rst-compare-adornments (ado1 ado2)
"Compare adornments.
Return true if both ADO1 and ADO2 adornments are equal,
according to restructured text semantics (only the character and
the style are compared, the indentation does not matter)."
according to restructured text semantics (only the character
and the style are compared, the indentation does not matter)."
(and (eq (car ado1) (car ado2))
(eq (cadr ado1) (cadr ado2))))
......@@ -1091,9 +1091,9 @@ better match."
(defun rst-update-section (char style &optional indent)
"Unconditionally update the style of a section adornment.
Do this using the given character CHAR, with STYLE 'simple
or 'over-and-under, and with indent INDENT. If the STYLE
is 'simple, whitespace before the title is removed (indent
Do this using the given character CHAR, with STYLE `simple'
or `over-and-under', and with indent INDENT. If the STYLE
is `simple', whitespace before the title is removed (indent
is always assumed to be 0).
If there are existing overline and/or underline from the
......@@ -1270,8 +1270,8 @@ 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
the title line has no syntactically valid adornment STYLE is nil
in the first element. If there is no adornment around the title
the title line has no syntactically valid adornment, STYLE is nil
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
......@@ -1325,15 +1325,15 @@ are nil."
(defvar rst-all-sections nil
"All section adornments in the buffer as found by `rst-find-all-adornments'.
t when no section adornments were found.")
Set to t when no section adornments were found.")
(make-variable-buffer-local 'rst-all-sections)
;; FIXME: If this variable is set to a different value font-locking of section
;; 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
`rst-all-sections'.")
Set to t when no section adornments were found.
Value depends on `rst-all-sections'.")
(make-variable-buffer-local 'rst-section-hierarchy)
(rst-testcover-add-1value 'rst-reset-section-caches)
......@@ -1502,8 +1502,8 @@ REVERSE-DIRECTION is used to reverse the cycling order."
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
depending on whether the region is active. This function is meant
to be invoked possibly multiple times, and can vary its behavior
with a positive PFXARG (toggle style), or with a negative
PFXARG (alternate behavior).
......@@ -1609,7 +1609,7 @@ The adornments consist in
1. a CHARACTER
2. a STYLE which can be either of 'simple' or 'over-and-under'.
2. a STYLE which can be either `simple' or `over-and-under'.
3. an INDENT (meaningful for the over-and-under style only)
which determines how many characters and over-and-under
......@@ -1652,8 +1652,8 @@ Case 2: Incomplete Adornment
If the current line does have an existing adornment, but the
adornment is incomplete, that is, the underline/overline does
not extend to exactly the end of the title line (it is either too
short or too long), we simply extend the length of the
not extend to exactly the end of the title line (it is either
too short or too long), we simply extend the length of the
underlines/overlines to fit exactly the section title.
If TOGGLE-STYLE we toggle the style of the adornment as well.
......@@ -1922,7 +1922,7 @@ in order to adapt it to our preferred style."
Obviously, NUM must be greater than zero. Don't blame me, blame the
Romans, I mean \"what have the Romans ever _done_ for /us/?\" (with
apologies to Monty Python).
If optional prefix ARG is non-nil, insert in current buffer."
If optional ARG is non-nil, insert in current buffer."
(let ((map rst-arabic-to-roman)
res)
(while (and map (> num 0))
......@@ -1931,13 +1931,13 @@ If optional prefix ARG is non-nil, insert in current buffer."
(setq res (concat res (cdar map))
num (- num (caar map)))
(setq map (cdr map))))
res))
(if arg (insert (or res "")) res)))
(defun rst-roman-to-arabic (string &optional arg)
"Convert STRING of Roman numerals to an Arabic number.
If STRING contains a letter which isn't a valid Roman numeral, the rest
of the string from that point onwards is ignored.
If STRING contains a letter which isn't a valid Roman numeral,
the rest of the string from that point onwards is ignored.
Hence:
MMD == 2500
......@@ -1951,7 +1951,7 @@ If optional ARG is non-nil, insert in current buffer."
(setq res (+ res (caar map))
string (replace-match "" nil t string))
(setq map (cdr map))))
res))
(if arg (insert res) res)))
;=================================================
(defun rst-find-pfx-in-region (beg end pfx-re)
......@@ -2020,20 +2020,20 @@ Other situations are just ignored and left to users themselves."
;; FIXME: Isn't this a `defconst'?
(defvar rst-initial-items
(append (mapcar 'char-to-string rst-bullets) rst-initial-enums)
"List of initial items. It's collection of bullets and enumerations.")
"List of initial items. It's a collection of bullets and enumerations.")
(defun rst-insert-list-new-item ()
"Insert a new list item.
User is asked to select the item style first, for example (a), i), +. Use TAB
for completion and choices.
User is asked to select the item style first, for example (a), i), +.
Use TAB for completion and choices.
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
starting item, for example 'e' for 'A)' style. The position is also arranged by
`rst-insert-list-pos'."
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.
(let* ((itemstyle (completing-read
......@@ -2140,7 +2140,7 @@ for completion and choices.
The position of the new list is arranged according to whether or not the
current line and the previous line are blank lines.
2. When continuing a list, one thing need to be noticed:
2. When continuing a list, one thing needs to be noticed:
List style alphabetical list, such as 'a.', and roman numerical list, such as
'i.', have some overlapping items, for example 'v.' The function can deal with
......@@ -2271,13 +2271,11 @@ without UNPROCESSED."
"Return section containing POINT by returning the closest node in TREE.
TREE is a section tree as returned by `rst-section-tree'
consisting of (NODE CHILD...) entries. POINT defaults to the
current point. A NODE must have the structure (IGNORED MARKER
...).
current point. A NODE must have the structure (IGNORED MARKER...).
Return (PATH NODE CHILD...). NODE is the node where POINT is in
if any. PATH is a list of nodes from the top of the tree down to
and including NODE. List of CHILD are the children of NODE if
any."
and including NODE. List of CHILD are the children of NODE if any."
(setq point (or point (point)))
(let ((cur (car tree))
(children (cdr tree)))
......@@ -2318,10 +2316,10 @@ Also used for formatting insertion, when numbering is disabled."
"Insertion style for table-of-contents.
Set this to one of the following values to determine numbering and
indentation style:
- plain: no numbering (fixed indentation)
- fixed: numbering, but fixed indentation
- aligned: numbering, titles aligned under each other
- listed: numbering, with dashes like list items (EXPERIMENTAL)"
- `plain': no numbering (fixed indentation)
- `fixed': numbering, but fixed indentation
- `aligned': numbering, titles aligned under each other
- `listed': numbering, with dashes like list items (EXPERIMENTAL)"
:type '(choice (const plain)
(const fixed)
(const aligned)
......@@ -2384,7 +2382,7 @@ The TOC is inserted indented at the current column."
(defun rst-toc-insert-node (node level indent pfx)
"Insert tree node NODE in table-of-contents.
Recursive function that does printing of the inserted toc.
Recursive function that does printing of the inserted TOC.
LEVEL is the depth level of the sections in the tree.
INDENT is the indentation string. PFX is the prefix numbering,
that includes the alignment necessary for all the children of
......@@ -2611,7 +2609,7 @@ brings the cursor in that section."
;; paragraph.
(defun rst-goto-section (&optional kill)
"Go to the section the current line describes.
If KILL a toc buffer is destroyed."
If KILL a TOC buffer is destroyed."
(interactive)
(let ((pos (rst-toc-mode-find-section)))
(when kill
......@@ -2682,8 +2680,8 @@ EVENT is the input event."
(defun rst-forward-section (&optional offset)
"Skip to the next reStructuredText section title.
OFFSET specifies how many titles to skip. Use a negative OFFSET to move
backwards in the file (default is to use 1)."
OFFSET specifies how many titles to skip. Use a negative OFFSET
to move backwards in the file (default is to use 1)."
(interactive)
(rst-reset-section-caches)
(let* (;; Default value for offset.
......@@ -2848,10 +2846,9 @@ first of a paragraph."
(defgroup rst-indent nil "Settings for indentation in reStructuredText.
In reStructuredText indentation points are usually determined by
preceding lines. Sometimes the syntax allows arbitrary
indentation points such as where to start the first line
following a directive. These indentation widths can be customized
here."
preceding lines. Sometimes the syntax allows arbitrary indentation
points such as where to start the first line following a directive.
These indentation widths can be customized here."
:group 'rst
:package-version '(rst . "1.1.0"))
......@@ -2957,11 +2954,11 @@ and not from inner alignment points."
(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
in the text 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 in
the text above."
(save-excursion
(goto-char pt)
(let (leftmost ; Leftmost column found so far.
......@@ -3136,7 +3133,7 @@ Region is from from BEG to END. Uncomment if ARG."
(indent-line-to ind)
(insert (comment-string-strip comment-start t t))))))
(defun rst-uncomment-region (beg end &optional arg)
(defun rst-uncomment-region (beg end &optional _arg)
"Uncomment the current region.
Region is from BEG to END. ARG is ignored"
(save-excursion
......@@ -3774,8 +3771,7 @@ point is not moved."
(defvar rst-font-lock-find-unindented-line-end nil
"End of the match as determined by `rst-font-lock-find-unindented-line-limit'.
Also used as a trigger for
`rst-font-lock-find-unindented-line-match'.")
Also used as a trigger for `rst-font-lock-find-unindented-line-match'.")
(defun rst-font-lock-find-unindented-line-limit (ind-pnt)
"Find the next unindented line relative to indentation at IND-PNT.
......@@ -3783,8 +3779,7 @@ 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
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."
next non-empty line if this is indented more than the current one."
(setq rst-font-lock-find-unindented-line-begin ind-pnt)
(setq rst-font-lock-find-unindented-line-end
(save-excursion
......@@ -3824,12 +3819,11 @@ one."
(or (rst-forward-indented-block nil (point-max))
(point-max))))))
(defun rst-font-lock-find-unindented-line-match (limit)
(defun rst-font-lock-find-unindented-line-match (_limit)
"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 no match is found. Return non-nil if match was found. LIMIT
is not used but mandated by the caller."
Match has been found by `rst-font-lock-find-unindented-line-limit'
the first time called 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
......@@ -3850,10 +3844,9 @@ Either section level of the current adornment or t for a transition.")
(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
beyond the existing hierarchy."
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 beyond the existing hierarchy."
(if (not (consp key))
key
(let* ((hier (rst-get-hierarchy))
......@@ -3875,9 +3868,8 @@ 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.
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
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
where the whole adorned construct ends.
......@@ -3892,7 +3884,7 @@ Called as a PRE-MATCH-FORM in the sense of `font-lock-keywords'."
(goto-char (nth 1 ado-data)) ; Beginning of construct.
(nth 2 ado-data)))) ; End of construct.
(defun rst-font-lock-handle-adornment-matcher (limit)
(defun rst-font-lock-handle-adornment-matcher (_limit)
"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
......@@ -3989,7 +3981,7 @@ string)) to be used for converting the document."
(defun rst-compile (&optional use-alt)
"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,
options. There are two commands to choose from; with USE-ALT,
select the alternative tool-set."
(interactive "P")
;; Note: maybe we want to check if there is a Makefile too and not do anything
......@@ -4094,7 +4086,7 @@ buffer, if the region is not selected."
a))
(defun rst-imenu-convert-cell (elt adornments)
"Convert a cell ELT in a tree returned from `rst-section-tree' to imenu index.
"Convert a cell ELT in a tree returned from `rst-section-tree' to Imenu index.
ADORNMENTS is used as hint information for conversion."
(let* ((kar (car elt))
(kdr (cdr elt))
......@@ -4128,7 +4120,7 @@ ADORNMENTS is used as hint information for conversion."
;; FIXME: Document title and subtitle need to be handled properly. They should
;; get an own "Document" top level entry.
(defun rst-imenu-create-index ()
"Create index for imenu.
"Create index for Imenu.
Return as described for `imenu--index-alist'."
(rst-reset-section-caches)
(let ((tree (rst-section-tree))
......@@ -4190,8 +4182,8 @@ This is useful for filling list item paragraphs."
;; be useful for creating separators.
(defun rst-repeat-last-character (use-next)
"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.
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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment