lisp/textmodes/rst.el

   1 ;;; rst.el --- Mode for viewing and editing reStructuredText-documents.
   2
   3 ;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
   4 ;;   Free Software Foundation, Inc.
   5
   6 ;; Authors: Martin Blais <blais@furius.ca>,
   7 ;;          Stefan Merten <smerten@oekonux.de>,
   8 ;;          David Goodger <goodger@python.org>
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26
  27 ;; This package provides major mode rst-mode, which supports documents marked up
  28 ;; using the reStructuredText format.  Support includes font locking as well as
  29 ;; some convenience functions for editing.  It does this by defining a Emacs
  30 ;; major mode: rst-mode (ReST).  This mode is derived from text-mode (and
  31 ;; inherits much of it).  This package also contains:
  32 ;;
  33 ;; - Functions to automatically adjust and cycle the section underline
  34 ;;   decorations;
  35 ;; - A mode that displays the table of contents and allows you to jump anywhere
  36 ;;   from it;
  37 ;; - Functions to insert and automatically update a TOC in your source
  38 ;;   document;
  39 ;; - Font-lock highlighting of notable reStructuredText structures;
  40 ;; - Some other convenience functions.
  41 ;;
  42 ;; See the accompanying document in the docutils documentation about
  43 ;; the contents of this package and how to use it.
  44 ;;
  45 ;; For more information about reStructuredText, see
  46 ;; http://docutils.sourceforge.net/rst.html
  47 ;;
  48 ;; For full details on how to use the contents of this file, see
  49 ;; http://docutils.sourceforge.net/docs/user/emacs.html
  50 ;;
  51 ;;
  52 ;; There are a number of convenient keybindings provided by rst-mode.
  53 ;; The main one is
  54 ;;
  55 ;;    C-c C-a (also C-=): rst-adjust
  56 ;;
  57 ;; Updates or rotates the section title around point or promotes/demotes the
  58 ;; decorations within the region (see full details below).  Note that C-= is a
  59 ;; good binding, since it allows you to specify a negative arg easily with C--
  60 ;; C-= (easy to type), as well as ordinary prefix arg with C-u C-=.
  61 ;;
  62 ;; For more on bindings, see rst-mode-map below.  There are also many variables
  63 ;; that can be customized, look for defcustom and defvar in this file.
  64 ;;
  65 ;; If you use the table-of-contents feature, you may want to add a hook to
  66 ;; update the TOC automatically everytime you adjust a section title::
  67 ;;
  68 ;;   (add-hook 'rst-adjust-hook 'rst-toc-update)
  69 ;;
  70 ;; Syntax highlighting: font-lock is enabled by default.  If you want to turn
  71 ;; off syntax highlighting to rst-mode, you can use the following::
  72 ;;
  73 ;;   (setq font-lock-global-modes '(not rst-mode ...))
  74 ;;
  75
  76
  77 ;; CUSTOMIZATION
  78 ;;
  79 ;; rst
  80 ;; ---
  81 ;; This group contains some general customizable features.
  82 ;;
  83 ;; The group is contained in the wp group.
  84 ;;
  85 ;; rst-faces
  86 ;; ---------
  87 ;; This group contains all necessary for customizing fonts.  The default
  88 ;; settings use standard font-lock-*-face's so if you set these to your
  89 ;; liking they are probably good in rst-mode also.
  90 ;;
  91 ;; The group is contained in the faces group as well as in the rst group.
  92 ;;
  93 ;; rst-faces-defaults
  94 ;; ------------------
  95 ;; This group contains all necessary for customizing the default fonts used for
  96 ;; section title faces.
  97 ;;
  98 ;; The general idea for section title faces is to have a non-default background
  99 ;; but do not change the background.  The section level is shown by the
 100 ;; lightness of the background color.  If you like this general idea of
 101 ;; generating faces for section titles but do not like the details this group
 102 ;; is the point where you can customize the details.  If you do not like the
 103 ;; general idea, however, you should customize the faces used in
 104 ;; rst-adornment-faces-alist.
 105 ;;
 106 ;; Note: If you are using a dark background please make sure the variable
 107 ;; frame-background-mode is set to the symbol dark.  This triggers
 108 ;; some default values which are probably right for you.
 109 ;;
 110 ;; The group is contained in the rst-faces group.
 111 ;;
 112 ;; All customizable features have a comment explaining their meaning.
 113 ;; Refer to the customization of your Emacs (try ``M-x customize``).
 114
 115
 116 ;;; DOWNLOAD
 117
 118 ;; The latest version of this file lies in the docutils source code repository:
 119 ;;   http://svn.berlios.de/svnroot/repos/docutils/trunk/docutils/tools/editors/emacs/rst.el
 120
 121
 122 ;;; INSTALLATION
 123
 124 ;; Add the following lines to your `.emacs' file:
 125 ;;
 126 ;;   (require 'rst)
 127 ;;
 128 ;; If you are using `.txt' as a standard extension for reST files as
 129 ;; http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file
 130 ;; suggests you may use one of the `Local Variables in Files' mechanism Emacs
 131 ;; provides to set the major mode automatically.  For instance you may use::
 132 ;;
 133 ;;    .. -*- mode: rst -*-
 134 ;;
 135 ;; in the very first line of your file.  The following code is useful if you
 136 ;; want automatically enter rst-mode from any file with compatible extensions:
 137 ;;
 138 ;; (setq auto-mode-alist
 139 ;;       (append '(("\\.txt$" . rst-mode)
 140 ;;                 ("\\.rst$" . rst-mode)
 141 ;;                 ("\\.rest$" . rst-mode)) auto-mode-alist))
 142 ;;
 143
 144 ;;; BUGS
 145
 146 ;; - rst-enumeration-region: Select a single paragraph, with the top at one
 147 ;;   blank line before the beginning, and it will fail.
 148 ;; - The active region goes away when we shift it left or right, and this
 149 ;;   prevents us from refilling it automatically when shifting many times.
 150 ;; - The suggested decorations when adjusting should not have to cycle
 151 ;;   below one below the last section decoration level preceding the
 152 ;;   cursor.  We need to fix that.
 153
 154 ;;; TODO LIST
 155
 156 ;; rst-toc-insert features
 157 ;; ------------------------
 158 ;; - rst-toc-insert: We should parse the contents:: options to figure out how
 159 ;;   deep to render the inserted TOC.
 160 ;; - On load, detect any existing TOCs and set the properties for links.
 161 ;; - TOC insertion should have an option to add empty lines.
 162 ;; - TOC insertion should deal with multiple lines.
 163 ;; - There is a bug on redo after undo of adjust when rst-adjust-hook uses the
 164 ;;   automatic toc update.  The cursor ends up in the TOC and this is
 165 ;;   annoying.  Gotta fix that.
 166 ;; - numbering: automatically detect if we have a section-numbering directive in
 167 ;;   the corresponding section, to render the toc.
 168 ;;
 169 ;; bulleted and enumerated list items
 170 ;; ----------------------------------
 171 ;; - We need to provide way to rebullet bulleted lists, and that would include
 172 ;;   automatic enumeration as well.
 173 ;;
 174 ;; Other
 175 ;; -----
 176 ;; - It would be nice to differentiate between text files using
 177 ;;   reStructuredText_ and other general text files.  If we had a
 178 ;;   function to automatically guess whether a .txt file is following the
 179 ;;   reStructuredText_ conventions, we could trigger rst-mode without
 180 ;;   having to hard-code this in every text file, nor forcing the user to
 181 ;;   add a local mode variable at the top of the file.
 182 ;;   We could perform this guessing by searching for a valid decoration
 183 ;;   at the top of the document or searching for reStructuredText_
 184 ;;   directives further on.
 185 ;;
 186 ;; - We should support imenu in our major mode, with the menu filled with the
 187 ;;   section titles (this should be really easy).
 188 ;;
 189 ;; - We should rename "adornment" to "decoration" or vice-versa in this
 190 ;;   document (Stefan's code ("adornment") vs Martin ("decoration")), maybe some
 191 ;;   functions even overlap.
 192 ;;
 193 ;; - We need to automatically recenter on rst-forward-section movement commands.
 194
 195
 196 ;;; HISTORY
 197 ;;
 198
 199 ;;; Code:
 200
 201 \f
 202 (defgroup rst nil "Support for reStructuredText documents."
 203   :group 'wp
 204   :version "23.1"
 205   :link '(url-link "http://docutils.sourceforge.net/rst.html"))
 206
 207
 208
 209 \f
 210 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 211 ;; Define some generic support functions.
 212
 213 (eval-when-compile (require 'cl)) ;; We need this for destructuring-bind below.
 214
 215
 216 ;; From Emacs-22
 217 (unless (fboundp 'line-number-at-pos)
 218   (defun line-number-at-pos (&optional pos)
 219     "Return (narrowed) buffer line number at position POS.
 220     If POS is nil, use current buffer location."
 221     (let ((opoint (or pos (point))) start)
 222       (save-excursion
 223         (goto-char (point-min))
 224         (setq start (point))
 225         (goto-char opoint)
 226         (forward-line 0)
 227         (1+ (count-lines start (point)))))) )
 228
 229
 230 \f
 231 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 232 ;; Mode definition.
 233
 234 ;; Key bindings.
 235 (defvar rst-mode-map
 236   (let ((map (make-sparse-keymap)))
 237
 238     ;;
 239     ;; Section Decorations.
 240     ;;
 241     ;; The adjustment function that decorates or rotates a section title.
 242     (define-key map [(control c) (control a)] 'rst-adjust)
 243     (define-key map [(control c) (control ?=)] 'rst-adjust)
 244     (define-key map [(control ?=)] 'rst-adjust) ;; (Does not work on the Mac OSX.)
 245     ;; Display the hierarchy of decorations implied by the current document contents.
 246     (define-key map [(control c) (control h)] 'rst-display-decorations-hierarchy)
 247     ;; Homogeneize the decorations in the document.
 248     (define-key map [(control c) (control s)] 'rst-straighten-decorations)
 249 ;;    (define-key map [(control c) (control s)] 'rst-straighten-deco-spacing)
 250
 251     ;;
 252     ;; Section Movement and Selection.
 253     ;;
 254     ;; Mark the subsection where the cursor is.
 255     (define-key map [(control c) (control m)] 'rst-mark-section)
 256     ;; Move forward/backward between section titles.
 257     (define-key map [(control c) (control n)] 'rst-forward-section)
 258     (define-key map [(control c) (control p)] 'rst-backward-section)
 259
 260     ;;
 261     ;; Operating on Blocks of Text.
 262     ;;
 263     ;; Makes paragraphs in region as a bullet list.
 264     (define-key map [(control c) (control b)] 'rst-bullet-list-region)
 265     ;; Makes paragraphs in region as a enumeration.
 266     (define-key map [(control c) (control e)] 'rst-enumerate-region)
 267     ;; Converts bullets to an enumeration.
 268     (define-key map [(control c) (control v)] 'rst-convert-bullets-to-enumeration)
 269     ;; Makes region a line-block.
 270     (define-key map [(control c) (control d)] 'rst-line-block-region)
 271     ;; Make sure that all the bullets in the region are consistent.
 272     (define-key map [(control c) (control w)] 'rst-straighten-bullets-region)
 273     ;; Shift region left or right (taking into account of enumerations/bullets, etc.).
 274     (define-key map [(control c) (control l)] 'rst-shift-region-left)
 275     (define-key map [(control c) (control r)] 'rst-shift-region-right)
 276     ;; Comment/uncomment the active region.
 277     (define-key map [(control c) (control c)] 'comment-region)
 278
 279     ;;
 280     ;; Table-of-Contents Features.
 281     ;;
 282     ;; Enter a TOC buffer to view and move to a specific section.
 283     (define-key map [(control c) (control t)] 'rst-toc)
 284     ;; Insert a TOC here.
 285     (define-key map [(control c) (control i)] 'rst-toc-insert)
 286     ;; Update the document's TOC (without changing the cursor position).
 287     (define-key map [(control c) (control u)] 'rst-toc-update)
 288     ;; Got to the section under the cursor (cursor must be in TOC).
 289     (define-key map [(control c) (control f)] 'rst-goto-section)
 290
 291     ;;
 292     ;; Converting Documents from Emacs.
 293     ;;
 294     ;; Run one of two pre-configured toolset commands on the document.
 295     (define-key map [(control c) (?1)] 'rst-compile)
 296     (define-key map [(control c) (?2)] 'rst-compile-alt-toolset)
 297     ;; Convert the active region to pseudo-xml using the docutils tools.
 298     (define-key map [(control c) (?3)] 'rst-compile-pseudo-region)
 299     ;; Convert the current document to PDF and launch a viewer on the results.
 300     (define-key map [(control c) (?4)] 'rst-compile-pdf-preview)
 301     ;; Convert the current document to S5 slides and view in a web browser.
 302     (define-key map [(control c) (?5)] 'rst-compile-slides-preview)
 303
 304     map)
 305   "Keymap for reStructuredText mode commands.
 306 This inherits from Text mode.")
 307
 308
 309 ;; Abbrevs.
 310 (defvar rst-mode-abbrev-table nil
 311   "Abbrev table used while in Rst mode.")
 312 (define-abbrev-table 'rst-mode-abbrev-table
 313   (mapcar (lambda (x) (append x '(nil 0 system)))
 314           '(("contents" ".. contents::\n..\n   ")
 315             ("con" ".. contents::\n..\n   ")
 316             ("cont" "[...]")
 317             ("skip" "\n\n[...]\n\n  ")
 318             ("seq" "\n\n[...]\n\n  ")
 319             ;; FIXME: Add footnotes, links, and more.
 320             )))
 321
 322
 323 ;; Syntax table.
 324 (defvar rst-mode-syntax-table
 325   (let ((st (copy-syntax-table text-mode-syntax-table)))
 326
 327     (modify-syntax-entry ?$ "." st)
 328     (modify-syntax-entry ?% "." st)
 329     (modify-syntax-entry ?& "." st)
 330     (modify-syntax-entry ?' "." st)
 331     (modify-syntax-entry ?* "." st)
 332     (modify-syntax-entry ?+ "." st)
 333     (modify-syntax-entry ?. "_" st)
 334     (modify-syntax-entry ?/ "." st)
 335     (modify-syntax-entry ?< "." st)
 336     (modify-syntax-entry ?= "." st)
 337     (modify-syntax-entry ?> "." st)
 338     (modify-syntax-entry ?\\ "\\" st)
 339     (modify-syntax-entry ?| "." st)
 340     (modify-syntax-entry ?_ "." st)
 341
 342     st)
 343   "Syntax table used while in `rst-mode'.")
 344
 345
 346 (defcustom rst-mode-hook nil
 347   "Hook run when Rst mode is turned on.
 348 The hook for Text mode is run before this one."
 349   :group 'rst
 350   :type '(hook))
 351
 352
 353 (defcustom rst-mode-lazy t
 354   "If non-nil Rst mode tries to font-lock multi-line elements correctly.
 355 Because this is really slow it should be set to nil if neither `jit-lock-mode'
 356 not `lazy-lock-mode' and activated.
 357
 358 If nil, comments and literal blocks are font-locked only on the line they start.
 359
 360 The value of this variable is used when Rst mode is turned on."
 361   :group 'rst
 362   :type '(boolean))
 363
 364 ;; Use rst-mode for *.rst and *.rest files.  Many ReStructured-Text files
 365 ;; use *.txt, but this is too generic to be set as a default.
 366 ;;;###autoload (add-to-list 'auto-mode-alist (purecopy '("\\.re?st\\'" . rst-mode)))
 367 ;;;###autoload
 368 (define-derived-mode rst-mode text-mode "ReST"
 369   "Major mode for editing reStructuredText documents.
 370 \\<rst-mode-map>
 371 There are a number of convenient keybindings provided by
 372 Rst mode.  The main one is \\[rst-adjust], it updates or rotates
 373 the section title around point or promotes/demotes the
 374 decorations within the region (see full details below).
 375 Use negative prefix arg to rotate in the other direction.
 376
 377 Turning on `rst-mode' calls the normal hooks `text-mode-hook'
 378 and `rst-mode-hook'.  This mode also supports font-lock
 379 highlighting.  You may customize `rst-mode-lazy' to toggle
 380 font-locking of blocks.
 381
 382 \\{rst-mode-map}"
 383   :abbrev-table rst-mode-abbrev-table
 384   :syntax-table rst-mode-syntax-table
 385   :group 'rst
 386
 387   (set (make-local-variable 'paragraph-separate) paragraph-start)
 388   (set (make-local-variable 'indent-line-function) 'indent-relative-maybe)
 389   (set (make-local-variable 'paragraph-start)
 390        "\f\\|>*[ \t]*$\\|>*[ \t]*[-+*] \\|>*[ \t]*[0-9#]+\\. ")
 391   (set (make-local-variable 'adaptive-fill-mode) t)
 392
 393   ;; FIXME: No need to reset this.
 394   ;; (set (make-local-variable 'indent-line-function) 'indent-relative)
 395
 396   ;; The details of the following comment setup is important because it affects
 397   ;; auto-fill, and it is pretty common in running text to have an ellipsis
 398   ;; ("...") which trips because of the rest comment syntax (".. ").
 399   (set (make-local-variable 'comment-start) ".. ")
 400   (set (make-local-variable 'comment-start-skip) "^\\.\\. ")
 401   (set (make-local-variable 'comment-multi-line) nil)
 402
 403   ;; Special variables
 404   (make-local-variable 'rst-adornment-level-alist)
 405
 406   ;; Font lock
 407   (set (make-local-variable 'font-lock-defaults)
 408        '(rst-font-lock-keywords-function
 409          t nil nil nil
 410          (font-lock-mark-block-function . mark-paragraph)))
 411   ;; `jit-lock-mode' has been the default since Emacs-21.1, so there's no
 412   ;; point messing around with font-lock-support-mode any more.
 413   ;; (when (boundp 'font-lock-support-mode)
 414   ;;   ;; rst-mode has its own mind about font-lock-support-mode
 415   ;;   (make-local-variable 'font-lock-support-mode)
 416   ;;   ;; jit-lock-mode replaced lazy-lock-mode in GNU Emacs 21.
 417   ;;   (let ((jit-or-lazy-lock-mode
 418   ;;          (cond
 419   ;;           ((fboundp 'lazy-lock-mode) 'lazy-lock-mode)
 420   ;;           ((fboundp 'jit-lock-mode) 'jit-lock-mode)
 421   ;;           ;; if neither lazy-lock nor jit-lock is supported,
 422   ;;           ;; tell user and disable rst-mode-lazy
 423   ;;           (t (when rst-mode-lazy
 424   ;;                (message "Disabled lazy fontification, because no known support mode found.")
 425   ;;                (setq rst-mode-lazy nil))))))
 426   ;;     (cond
 427   ;;      ((and (not rst-mode-lazy) (not font-lock-support-mode)))
 428   ;;      ;; No support mode set and none required - leave it alone
 429   ;;      ((or (not font-lock-support-mode) ;; No support mode set (but required)
 430   ;;           (symbolp font-lock-support-mode)) ;; or a fixed mode for all
 431   ;;       (setq font-lock-support-mode
 432   ;;             (list (cons 'rst-mode (and rst-mode-lazy jit-or-lazy-lock-mode))
 433   ;;                (cons t font-lock-support-mode))))
 434   ;;      ((and (listp font-lock-support-mode)
 435   ;;            (not (assoc 'rst-mode font-lock-support-mode)))
 436   ;;       ;; A list of modes missing rst-mode
 437   ;;       (setq font-lock-support-mode
 438   ;;             (cons (cons 'rst-mode (and rst-mode-lazy jit-or-lazy-lock-mode))
 439   ;;                font-lock-support-mode))))))
 440
 441   )
 442
 443
 444 ;;;###autoload
 445 (define-minor-mode rst-minor-mode
 446   "ReST Minor Mode.
 447 Toggle ReST minor mode.
 448 With no argument, this command toggles the mode.
 449 Non-null prefix argument turns on the mode.
 450 Null prefix argument turns off the mode.
 451
 452 When ReST minor mode is enabled, the ReST mode keybindings
 453 are installed on top of the major mode bindings.  Use this
 454 for modes derived from Text mode, like Mail mode."
 455  ;; The initial value.
 456  nil
 457  ;; The indicator for the mode line.
 458  " ReST"
 459  ;; The minor mode bindings.
 460  rst-mode-map
 461  :group 'rst)
 462
 463 ;; FIXME: can I somehow install these too?
 464 ;;  :abbrev-table rst-mode-abbrev-table
 465 ;;  :syntax-table rst-mode-syntax-table
 466
 467
 468
 469
 470 \f
 471 ;; Bulleted item lists.
 472 (defcustom rst-bullets
 473   '(?- ?* ?+)
 474   "List of all possible bullet characters for bulleted lists."
 475   :group 'rst)
 476
 477
 478
 479 \f
 480 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 481 ;; Section Decoration Adjusment
 482 ;; ============================
 483 ;;
 484 ;; The following functions implement a smart automatic title sectioning feature.
 485 ;; The idea is that with the cursor sitting on a section title, we try to get as
 486 ;; much information from context and try to do the best thing automatically.
 487 ;; This function can be invoked many times and/or with prefix argument to rotate
 488 ;; between the various sectioning decorations.
 489 ;;
 490 ;; Definitions: the two forms of sectioning define semantically separate section
 491 ;; levels.  A sectioning DECORATION consists in:
 492 ;;
 493 ;;   - a CHARACTER
 494 ;;
 495 ;;   - a STYLE which can be either of 'simple' or 'over-and-under'.
 496 ;;
 497 ;;   - an INDENT (meaningful for the over-and-under style only) which determines
 498 ;;     how many characters and over-and-under style is hanging outside of the
 499 ;;     title at the beginning and ending.
 500 ;;
 501 ;; Important note: an existing decoration must be formed by at least two
 502 ;; characters to be recognized.
 503 ;;
 504 ;; Here are two examples of decorations (| represents the window border, column
 505 ;; 0):
 506 ;;
 507 ;;                                  |
 508 ;; 1. char: '-'   e                 |Some Title
 509 ;;    style: simple                 |----------
 510 ;;                                  |
 511 ;; 2. char: '='                     |==============
 512 ;;    style: over-and-under         |  Some Title
 513 ;;    indent: 2                     |==============
 514 ;;                                  |
 515 ;;
 516 ;; Some notes:
 517 ;;
 518 ;; - The underlining character that is used depends on context. The file is
 519 ;;   scanned to find other sections and an appropriate character is selected.
 520 ;;   If the function is invoked on a section that is complete, the character is
 521 ;;   rotated among the existing section decorations.
 522 ;;
 523 ;;   Note that when rotating the characters, if we come to the end of the
 524 ;;   hierarchy of decorations, the variable rst-preferred-decorations is
 525 ;;   consulted to propose a new underline decoration, and if continued, we cycle
 526 ;;   the decorations all over again.  Set this variable to nil if you want to
 527 ;;   limit the underlining character propositions to the existing decorations in
 528 ;;   the file.
 529 ;;
 530 ;; - A prefix argument can be used to alternate the style.
 531 ;;
 532 ;; - An underline/overline that is not extended to the column at which it should
 533 ;;   be hanging is dubbed INCOMPLETE.  For example::
 534 ;;
 535 ;;      |Some Title
 536 ;;      |-------
 537 ;;
 538 ;; Examples of default invocation:
 539 ;;
 540 ;;   |Some Title       --->    |Some Title
 541 ;;   |                         |----------
 542 ;;
 543 ;;   |Some Title       --->    |Some Title
 544 ;;   |-----                    |----------
 545 ;;
 546 ;;   |                         |------------
 547 ;;   | Some Title      --->    | Some Title
 548 ;;   |                         |------------
 549 ;;
 550 ;; In over-and-under style, when alternating the style, a variable is
 551 ;; available to select how much default indent to use (it can be zero).  Note
 552 ;; that if the current section decoration already has an indent, we don't
 553 ;; adjust it to the default, we rather use the current indent that is already
 554 ;; there for adjustment (unless we cycle, in which case we use the indent
 555 ;; that has been found previously).
 556
 557 (defgroup rst-adjust nil
 558   "Settings for adjustment and cycling of section title decorations."
 559   :group 'rst
 560   :version "21.1")
 561
 562 (defcustom rst-preferred-decorations '( (?= over-and-under 1)
 563                                          (?= simple 0)
 564                                          (?- simple 0)
 565                                          (?~ simple 0)
 566                                          (?+ simple 0)
 567                                          (?` simple 0)
 568                                          (?# simple 0)
 569                                          (?@ simple 0) )
 570   "Preferred ordering of section title decorations.
 571
 572 This sequence is consulted to offer a new decoration suggestion
 573 when we rotate the underlines at the end of the existing
 574 hierarchy of characters, or when there is no existing section
 575 title in the file."
 576   :group 'rst-adjust)
 577
 578
 579 (defcustom rst-default-indent 1
 580   "Number of characters to indent the section title.
 581
 582 This is used for when toggling decoration styles, when switching
 583 from a simple decoration style to a over-and-under decoration
 584 style."
 585   :group 'rst-adjust)
 586
 587
 588 (defvar rst-section-text-regexp "^[ \t]*\\S-*\\w\\S-*"
 589   "Regular expression for valid section title text.")
 590
 591
 592 (defun rst-line-homogeneous-p (&optional accept-special)
 593   "Return true if the line is homogeneous.
 594
 595 Predicate that returns the unique char if the current line is
 596 composed only of a single repeated non-whitespace character.
 597 This returns the char even if there is whitespace at the
 598 beginning of the line.
 599
 600 If ACCEPT-SPECIAL is specified we do not ignore special sequences
 601 which normally we would ignore when doing a search on many lines.
 602 For example, normally we have cases to ignore commonly occurring
 603 patterns, such as :: or ...; with the flag do not ignore them."
 604   (save-excursion
 605     (back-to-indentation)
 606     (unless (looking-at "\n")
 607       (let ((c (thing-at-point 'char)))
 608         (if (and (looking-at (format "[%s]+[ \t]*$" c))
 609                  (or accept-special
 610                      (and
 611                       ;; Common patterns.
 612                       (not (looking-at "::[ \t]*$"))
 613                       (not (looking-at "\\.\\.\\.[ \t]*$"))
 614                       ;; Discard one char line
 615                       (not (looking-at ".[ \t]*$"))
 616                       )))
 617             (string-to-char c))
 618         ))
 619     ))
 620
 621 (defun rst-line-homogeneous-nodent-p (&optional accept-special)
 622   "Return true if the line is homogeneous with no indent.
 623 See `rst-line-homogeneous-p' about ACCEPT-SPECIAL."
 624   (save-excursion
 625     (beginning-of-line)
 626     (if (looking-at "^[ \t]+")
 627         nil
 628       (rst-line-homogeneous-p accept-special)
 629       )))
 630
 631
 632 (defun rst-compare-decorations (deco1 deco2)
 633   "Compare decorations.
 634 Return true if both DECO1 and DECO2 decorations are equal,
 635 according to restructured text semantics (only the character and
 636 the style are compared, the indentation does not matter)."
 637   (and (eq (car deco1) (car deco2))
 638        (eq (cadr deco1) (cadr deco2))))
 639
 640
 641 (defun rst-get-decoration-match (hier deco)
 642   "Return the index (level) in hierarchy HIER of decoration DECO.
 643 This basically just searches for the item using the appropriate
 644 comparison and returns the index.  Return nil if the item is
 645 not found."
 646   (let ((cur hier))
 647     (while (and cur (not (rst-compare-decorations (car cur) deco)))
 648       (setq cur (cdr cur)))
 649     cur))
 650
 651
 652 (defun rst-suggest-new-decoration (alldecos &optional prev)
 653   "Suggest a new, different decoration from all that have been seen.
 654
 655 ALLDECOS is the set of all decorations, including the line numbers.
 656 PREV is the optional previous decoration, in order to suggest a
 657 better match."
 658
 659   ;; For all the preferred decorations...
 660   (let* (
 661          ;; If 'prev' is given, reorder the list to start searching after the
 662          ;; match.
 663          (fplist
 664           (cdr (rst-get-decoration-match rst-preferred-decorations prev)))
 665
 666          ;; List of candidates to search.
 667          (curpotential (append fplist rst-preferred-decorations)))
 668     (while
 669         ;; For all the decorations...
 670         (let ((cur alldecos)
 671               found)
 672           (while (and cur (not found))
 673             (if (rst-compare-decorations (car cur) (car curpotential))
 674                 ;; Found it!
 675                 (setq found (car curpotential))
 676               (setq cur (cdr cur))))
 677           found)
 678
 679       (setq curpotential (cdr curpotential)))
 680
 681     (copy-sequence (car curpotential))))
 682
 683 (defun rst-delete-entire-line ()
 684   "Delete the entire current line without using the `kill-ring'."
 685   (delete-region (line-beginning-position)
 686                  (line-beginning-position 2)))
 687
 688 (defun rst-update-section (char style &optional indent)
 689   "Unconditionally update the style of a section decoration.
 690
 691 Do this using the given character CHAR, with STYLE 'simple
 692 or 'over-and-under, and with indent INDENT.  If the STYLE
 693 is 'simple, whitespace before the title is removed (indent
 694 is always assumed to be 0).
 695
 696 If there are existing overline and/or underline from the
 697 existing decoration, they are removed before adding the
 698 requested decoration."
 699
 700   (interactive)
 701       (end-of-line)
 702   (let ((marker (point-marker))
 703         len)
 704
 705       ;; Fixup whitespace at the beginning and end of the line
 706       (if (or (null indent) (eq style 'simple))
 707           (setq indent 0))
 708       (beginning-of-line)
 709       (delete-horizontal-space)
 710       (insert (make-string indent ? ))
 711
 712       (end-of-line)
 713       (delete-horizontal-space)
 714
 715       ;; Set the current column, we're at the end of the title line
 716       (setq len (+ (current-column) indent))
 717
 718       ;; Remove previous line if it consists only of a single repeated character
 719       (save-excursion
 720         (forward-line -1)
 721         (and (rst-line-homogeneous-p 1)
 722              ;; Avoid removing the underline of a title right above us.
 723              (save-excursion (forward-line -1)
 724                              (not (looking-at rst-section-text-regexp)))
 725              (rst-delete-entire-line)))
 726
 727       ;; Remove following line if it consists only of a single repeated
 728       ;; character
 729       (save-excursion
 730         (forward-line +1)
 731         (and (rst-line-homogeneous-p 1)
 732              (rst-delete-entire-line))
 733         ;; Add a newline if we're at the end of the buffer, for the subsequence
 734         ;; inserting of the underline
 735         (if (= (point) (buffer-end 1))
 736             (newline 1)))
 737
 738       ;; Insert overline
 739       (if (eq style 'over-and-under)
 740           (save-excursion
 741             (beginning-of-line)
 742             (open-line 1)
 743             (insert (make-string len char))))
 744
 745       ;; Insert underline
 746       (forward-line +1)
 747       (open-line 1)
 748       (insert (make-string len char))
 749
 750       (forward-line +1)
 751       (goto-char marker)
 752       ))
 753
 754
 755 (defun rst-normalize-cursor-position ()
 756   "Normalize the cursor position.
 757 If the cursor is on a decoration line or an empty line , place it
 758 on the section title line (at the end).  Returns the line offset
 759 by which the cursor was moved.  This works both over or under a
 760 line."
 761   (if (save-excursion (beginning-of-line)
 762                       (or (rst-line-homogeneous-p 1)
 763                           (looking-at "^[ \t]*$")))
 764       (progn
 765         (beginning-of-line)
 766         (cond
 767          ((save-excursion (forward-line -1)
 768                           (beginning-of-line)
 769                           (and (looking-at rst-section-text-regexp)
 770                                (not (rst-line-homogeneous-p 1))))
 771           (progn (forward-line -1) -1))
 772          ((save-excursion (forward-line +1)
 773                           (beginning-of-line)
 774                           (and (looking-at rst-section-text-regexp)
 775                                (not (rst-line-homogeneous-p 1))))
 776           (progn (forward-line +1) +1))
 777          (t 0)))
 778     0 ))
 779
 780
 781 (defun rst-find-all-decorations ()
 782   "Find all the decorations in the file.
 783 Return a list of (line, decoration) pairs.  Each decoration
 784 consists in a (char, style, indent) triple.
 785
 786 This function does not detect the hierarchy of decorations, it
 787 just finds all of them in a file.  You can then invoke another
 788 function to remove redundancies and inconsistencies."
 789
 790   (let ((positions ())
 791         (curline 1))
 792     ;; Iterate over all the section titles/decorations in the file.
 793     (save-excursion
 794       (goto-char (point-min))
 795       (while (< (point) (buffer-end 1))
 796         (if (rst-line-homogeneous-nodent-p)
 797             (progn
 798               (setq curline (+ curline (rst-normalize-cursor-position)))
 799
 800               ;; Here we have found a potential site for a decoration,
 801               ;; characterize it.
 802               (let ((deco (rst-get-decoration)))
 803                 (if (cadr deco) ;; Style is existing.
 804                     ;; Found a real decoration site.
 805                     (progn
 806                       (push (cons curline deco) positions)
 807                       ;; Push beyond the underline.
 808                       (forward-line 1)
 809                       (setq curline (+ curline 1))
 810                       )))
 811               ))
 812         (forward-line 1)
 813         (setq curline (+ curline 1))
 814         ))
 815     (reverse positions)))
 816
 817
 818 (defun rst-infer-hierarchy (decorations)
 819   "Build a hierarchy of decorations using the list of given DECORATIONS.
 820
 821 This function expects a list of (char, style, indent) decoration
 822 specifications, in order that they appear in a file, and will
 823 infer a hierarchy of section levels by removing decorations that
 824 have already been seen in a forward traversal of the decorations,
 825 comparing just the character and style.
 826
 827 Similarly returns a list of (char, style, indent), where each
 828 list element should be unique."
 829
 830   (let ((hierarchy-alist (list)))
 831     (dolist (x decorations)
 832       (let ((char (car x))
 833             (style (cadr x)))
 834         (unless (assoc (cons char style) hierarchy-alist)
 835           (push (cons (cons char style) x) hierarchy-alist))
 836         ))
 837
 838     (mapcar 'cdr (nreverse hierarchy-alist))
 839     ))
 840
 841
 842 (defun rst-get-hierarchy (&optional alldecos ignore)
 843   "Return the hierarchy of section titles in the file.
 844
 845 Return a list of decorations that represents the hierarchy of
 846 section titles in the file.  Reuse the list of decorations
 847 already computed in ALLDECOS if present.  If the line number in
 848 IGNORE is specified, the decoration found on that line (if there
 849 is one) is not taken into account when building the hierarchy."
 850   (let ((all (or alldecos (rst-find-all-decorations))))
 851     (setq all (assq-delete-all ignore all))
 852     (rst-infer-hierarchy (mapcar 'cdr all))))
 853
 854
 855 (defun rst-get-decoration (&optional point)
 856   "Get the decoration at POINT.
 857
 858 Looks around point and finds the characteristics of the
 859 decoration that is found there.  Assumes that the cursor is
 860 already placed on the title line (and not on the overline or
 861 underline).
 862
 863 This function returns a (char, style, indent) triple.  If the
 864 characters of overline and underline are different, return
 865 the underline character.  The indent is always calculated.
 866 A decoration can be said to exist if the style is not nil.
 867
 868 A point can be specified to go to the given location before
 869 extracting the decoration."
 870
 871   (let (char style)
 872     (save-excursion
 873       (if point (goto-char point))
 874       (beginning-of-line)
 875       (if (looking-at rst-section-text-regexp)
 876           (let* ((over (save-excursion
 877                          (forward-line -1)
 878                          (rst-line-homogeneous-nodent-p)))
 879
 880                  (under (save-excursion
 881                           (forward-line +1)
 882                           (rst-line-homogeneous-nodent-p)))
 883                  )
 884
 885             ;; Check that the line above the overline is not part of a title
 886             ;; above it.
 887             (if (and over
 888                      (save-excursion
 889                        (and (equal (forward-line -2) 0)
 890                             (looking-at rst-section-text-regexp))))
 891                 (setq over nil))
 892
 893             (cond
 894              ;; No decoration found, leave all return values nil.
 895              ((and (eq over nil) (eq under nil)))
 896
 897              ;; Overline only, leave all return values nil.
 898              ;;
 899              ;; Note: we don't return the overline character, but it could
 900              ;; perhaps in some cases be used to do something.
 901              ((and over (eq under nil)))
 902
 903              ;; Underline only.
 904              ((and under (eq over nil))
 905               (setq char under
 906                     style 'simple))
 907
 908              ;; Both overline and underline.
 909              (t
 910               (setq char under
 911                     style 'over-and-under)))))
 912       ;; Return values.
 913       (list char style
 914             ;; Find indentation.
 915             (save-excursion (back-to-indentation) (current-column))))))
 916
 917
 918 (defun rst-get-decorations-around (&optional alldecos)
 919   "Return the decorations around point.
 920
 921 Given the list of all decorations ALLDECOS (with positions),
 922 find the decorations before and after the given point.
 923 A list of the previous and next decorations is returned."
 924   (let* ((all (or alldecos (rst-find-all-decorations)))
 925          (curline (line-number-at-pos))
 926          prev next
 927          (cur all))
 928
 929     ;; Search for the decorations around the current line.
 930     (while (and cur (< (caar cur) curline))
 931       (setq prev cur
 932             cur (cdr cur)))
 933     ;; 'cur' is the following decoration.
 934
 935     (if (and cur (caar cur))
 936         (setq next (if (= curline (caar cur)) (cdr cur) cur)))
 937
 938     (mapcar 'cdar (list prev next))
 939     ))
 940
 941
 942 (defun rst-decoration-complete-p (deco)
 943   "Return true if the decoration DECO around point is complete."
 944   ;; Note: we assume that the detection of the overline as being the underline
 945   ;; of a preceding title has already been detected, and has been eliminated
 946   ;; from the decoration that is given to us.
 947
 948   ;; There is some sectioning already present, so check if the current
 949   ;; sectioning is complete and correct.
 950   (let* ((char (car deco))
 951          (style (cadr deco))
 952          (indent (caddr deco))
 953          (endcol (save-excursion (end-of-line) (current-column)))
 954          )
 955     (if char
 956         (let ((exps (concat "^"
 957                             (regexp-quote (make-string (+ endcol indent) char))
 958                             "$")))
 959           (and
 960            (save-excursion (forward-line +1)
 961                            (beginning-of-line)
 962                            (looking-at exps))
 963            (or (not (eq style 'over-and-under))
 964                (save-excursion (forward-line -1)
 965                                (beginning-of-line)
 966                                (looking-at exps))))
 967           ))
 968     ))
 969
 970
 971 (defun rst-get-next-decoration
 972   (curdeco hier &optional suggestion reverse-direction)
 973   "Get the next decoration for CURDECO, in given hierarchy HIER.
 974 If suggesting, suggest for new decoration SUGGESTION.
 975 REVERSE-DIRECTION is used to reverse the cycling order."
 976
 977   (let* (
 978          (char (car curdeco))
 979          (style (cadr curdeco))
 980
 981          ;; Build a new list of decorations for the rotation.
 982          (rotdecos
 983           (append hier
 984                   ;; Suggest a new decoration.
 985                   (list suggestion
 986                         ;; If nothing to suggest, use first decoration.
 987                         (car hier)))) )
 988     (or
 989      ;; Search for next decoration.
 990      (cadr
 991       (let ((cur (if reverse-direction rotdecos
 992                    (reverse rotdecos))))
 993         (while (and cur
 994                     (not (and (eq char (caar cur))
 995                               (eq style (cadar cur)))))
 996           (setq cur (cdr cur)))
 997         cur))
 998
 999      ;; If not found, take the first of all decorations.
1000      suggestion
1001      )))
1002
1003
1004 (defun rst-adjust ()
1005   "Auto-adjust the decoration around point.
1006
1007 Adjust/rotate the section decoration for the section title
1008 around point or promote/demote the decorations inside the region,
1009 depending on if the region is active.  This function is meant to
1010 be invoked possibly multiple times, and can vary its behavior
1011 with a positive prefix argument (toggle style), or with a
1012 negative prefix argument (alternate behavior).
1013
1014 This function is the main focus of this module and is a bit of a
1015 swiss knife.  It is meant as the single most essential function
1016 to be bound to invoke to adjust the decorations of a section
1017 title in restructuredtext.  It tries to deal with all the
1018 possible cases gracefully and to do `the right thing' in all
1019 cases.
1020
1021 See the documentations of `rst-adjust-decoration' and
1022 `rst-promote-region' for full details.
1023
1024 Prefix Arguments
1025 ================
1026
1027 The method can take either (but not both) of
1028
1029 a. a (non-negative) prefix argument, which means to toggle the
1030    decoration style.  Invoke with a prefix arg for example;
1031
1032 b. a negative numerical argument, which generally inverts the
1033    direction of search in the file or hierarchy.  Invoke with C--
1034    prefix for example."
1035   (interactive)
1036
1037   (let* (;; Save our original position on the current line.
1038          (origpt (point-marker))
1039
1040          ;; Parse the positive and negative prefix arguments.
1041          (reverse-direction
1042           (and current-prefix-arg
1043                (< (prefix-numeric-value current-prefix-arg) 0)))
1044          (toggle-style
1045           (and current-prefix-arg (not reverse-direction))))
1046
1047     (if (rst-portable-mark-active-p)
1048         ;; Adjust decorations within region.
1049         (rst-promote-region current-prefix-arg)
1050       ;; Adjust decoration around point.
1051       (rst-adjust-decoration toggle-style reverse-direction))
1052
1053     ;; Run the hooks to run after adjusting.
1054     (run-hooks 'rst-adjust-hook)
1055
1056     ;; Make sure to reset the cursor position properly after we're done.
1057     (goto-char origpt)
1058
1059     ))
1060
1061 (defvar rst-adjust-hook nil
1062   "Hooks to be run after running `rst-adjust'.")
1063
1064 (defvar rst-new-decoration-down nil
1065   "Non-nil if new decoration is added deeper.
1066 If non-nil, a new decoration being added will be initialized to
1067 be one level down from the previous decoration.  If nil, a new
1068 decoration will be equal to the level of the previous
1069 decoration.")
1070
1071 (defun rst-adjust-decoration (&optional toggle-style reverse-direction)
1072 "Adjust/rotate the section decoration for the section title around point.
1073
1074 This function is meant to be invoked possibly multiple times, and
1075 can vary its behavior with a true TOGGLE-STYLE argument, or with
1076 a REVERSE-DIRECTION argument.
1077
1078 General Behavior
1079 ================
1080
1081 The next action it takes depends on context around the point, and
1082 it is meant to be invoked possibly more than once to rotate among
1083 the various possibilities.  Basically, this function deals with:
1084
1085 - adding a decoration if the title does not have one;
1086
1087 - adjusting the length of the underline characters to fit a
1088   modified title;
1089
1090 - rotating the decoration in the set of already existing
1091   sectioning decorations used in the file;
1092
1093 - switching between simple and over-and-under styles.
1094
1095 You should normally not have to read all the following, just
1096 invoke the method and it will do the most obvious thing that you
1097 would expect.
1098
1099
1100 Decoration Definitions
1101 ======================
1102
1103 The decorations consist in
1104
1105 1. a CHARACTER
1106
1107 2. a STYLE which can be either of 'simple' or 'over-and-under'.
1108
1109 3. an INDENT (meaningful for the over-and-under style only)
1110    which determines how many characters and over-and-under
1111    style is hanging outside of the title at the beginning and
1112    ending.
1113
1114 See source code for mode details.
1115
1116
1117 Detailed Behavior Description
1118 =============================
1119
1120 Here are the gory details of the algorithm (it seems quite
1121 complicated, but really, it does the most obvious thing in all
1122 the particular cases):
1123
1124 Before applying the decoration change, the cursor is placed on
1125 the closest line that could contain a section title.
1126
1127 Case 1: No Decoration
1128 ---------------------
1129
1130 If the current line has no decoration around it,
1131
1132 - search backwards for the last previous decoration, and apply
1133   the decoration one level lower to the current line.  If there
1134   is no defined level below this previous decoration, we suggest
1135   the most appropriate of the `rst-preferred-decorations'.
1136
1137   If REVERSE-DIRECTION is true, we simply use the previous
1138   decoration found directly.
1139
1140 - if there is no decoration found in the given direction, we use
1141   the first of `rst-preferred-decorations'.
1142
1143 The prefix argument forces a toggle of the prescribed decoration
1144 style.
1145
1146 Case 2: Incomplete Decoration
1147 -----------------------------
1148
1149 If the current line does have an existing decoration, but the
1150 decoration is incomplete, that is, the underline/overline does
1151 not extend to exactly the end of the title line (it is either too
1152 short or too long), we simply extend the length of the
1153 underlines/overlines to fit exactly the section title.
1154
1155 If the prefix argument is given, we toggle the style of the
1156 decoration as well.
1157
1158 REVERSE-DIRECTION has no effect in this case.
1159
1160 Case 3: Complete Existing Decoration
1161 ------------------------------------
1162
1163 If the decoration is complete (i.e. the underline (overline)
1164 length is already adjusted to the end of the title line), we
1165 search/parse the file to establish the hierarchy of all the
1166 decorations (making sure not to include the decoration around
1167 point), and we rotate the current title's decoration from within
1168 that list (by default, going *down* the hierarchy that is present
1169 in the file, i.e. to a lower section level).  This is meant to be
1170 used potentially multiple times, until the desired decoration is
1171 found around the title.
1172
1173 If we hit the boundary of the hierarchy, exactly one choice from
1174 the list of preferred decorations is suggested/chosen, the first
1175 of those decoration that has not been seen in the file yet (and
1176 not including the decoration around point), and the next
1177 invocation rolls over to the other end of the hierarchy (i.e. it
1178 cycles).  This allows you to avoid having to set which character
1179 to use.
1180
1181 If REVERSE-DIRECTION is true, the effect is to change the
1182 direction of rotation in the hierarchy of decorations, thus
1183 instead going *up* the hierarchy.
1184
1185 However, if there is a non-negative prefix argument, we do not
1186 rotate the decoration, but instead simply toggle the style of the
1187 current decoration (this should be the most common way to toggle
1188 the style of an existing complete decoration).
1189
1190
1191 Point Location
1192 ==============
1193
1194 The invocation of this function can be carried out anywhere
1195 within the section title line, on an existing underline or
1196 overline, as well as on an empty line following a section title.
1197 This is meant to be as convenient as possible.
1198
1199
1200 Indented Sections
1201 =================
1202
1203 Indented section titles such as ::
1204
1205    My Title
1206    --------
1207
1208 are invalid in restructuredtext and thus not recognized by the
1209 parser.  This code will thus not work in a way that would support
1210 indented sections (it would be ambiguous anyway).
1211
1212
1213 Joint Sections
1214 ==============
1215
1216 Section titles that are right next to each other may not be
1217 treated well.  More work might be needed to support those, and
1218 special conditions on the completeness of existing decorations
1219 might be required to make it non-ambiguous.
1220
1221 For now we assume that the decorations are disjoint, that is,
1222 there is at least a single line between the titles/decoration
1223 lines.
1224
1225
1226 Suggested Binding
1227 =================
1228
1229 We suggest that you bind this function on C-=.  It is close to
1230 C-- so a negative argument can be easily specified with a flick
1231 of the right hand fingers and the binding is unused in `text-mode'."
1232   (interactive)
1233
1234   ;; If we were invoked directly, parse the prefix arguments into the
1235   ;; arguments of the function.
1236   (if current-prefix-arg
1237       (setq reverse-direction
1238             (and current-prefix-arg
1239                  (< (prefix-numeric-value current-prefix-arg) 0))
1240
1241             toggle-style
1242             (and current-prefix-arg (not reverse-direction))))
1243
1244   (let* (;; Check if we're on an underline around a section title, and move the
1245          ;; cursor to the title if this is the case.
1246          (moved (rst-normalize-cursor-position))
1247
1248          ;; Find the decoration and completeness around point.
1249          (curdeco (rst-get-decoration))
1250          (char (car curdeco))
1251          (style (cadr curdeco))
1252          (indent (caddr curdeco))
1253
1254          ;; New values to be computed.
1255          char-new style-new indent-new
1256          )
1257
1258     ;; We've moved the cursor... if we're not looking at some text, we have
1259     ;; nothing to do.
1260     (if (save-excursion (beginning-of-line)
1261                         (looking-at rst-section-text-regexp))
1262         (progn
1263           (cond
1264            ;;-------------------------------------------------------------------
1265            ;; Case 1: No Decoration
1266            ((and (eq char nil) (eq style nil))
1267
1268             (let* ((alldecos (rst-find-all-decorations))
1269
1270                    (around (rst-get-decorations-around alldecos))
1271                    (prev (car around))
1272                    cur
1273
1274                    (hier (rst-get-hierarchy alldecos))
1275                    )
1276
1277               ;; Advance one level down.
1278               (setq cur
1279                     (if prev
1280                         (if (not reverse-direction)
1281                             (or (funcall (if rst-new-decoration-down 'cadr 'car)
1282                                          (rst-get-decoration-match hier prev))
1283                                 (rst-suggest-new-decoration hier prev))
1284                           prev)
1285                       (copy-sequence (car rst-preferred-decorations))))
1286
1287               ;; Invert the style if requested.
1288               (if toggle-style
1289                   (setcar (cdr cur) (if (eq (cadr cur) 'simple)
1290                                         'over-and-under 'simple)) )
1291
1292               (setq char-new (car cur)
1293                     style-new (cadr cur)
1294                     indent-new (caddr cur))
1295               ))
1296
1297            ;;-------------------------------------------------------------------
1298            ;; Case 2: Incomplete Decoration
1299            ((not (rst-decoration-complete-p curdeco))
1300
1301             ;; Invert the style if requested.
1302             (if toggle-style
1303                 (setq style (if (eq style 'simple) 'over-and-under 'simple)))
1304
1305             (setq char-new char
1306                   style-new style
1307                   indent-new indent))
1308
1309            ;;-------------------------------------------------------------------
1310            ;; Case 3: Complete Existing Decoration
1311            (t
1312             (if toggle-style
1313
1314                 ;; Simply switch the style of the current decoration.
1315                 (setq char-new char
1316                       style-new (if (eq style 'simple) 'over-and-under 'simple)
1317                       indent-new rst-default-indent)
1318
1319               ;; Else, we rotate, ignoring the decoration around the current
1320               ;; line...
1321               (let* ((alldecos (rst-find-all-decorations))
1322
1323                      (hier (rst-get-hierarchy alldecos (line-number-at-pos)))
1324
1325                      ;; Suggestion, in case we need to come up with something
1326                      ;; new
1327                      (suggestion (rst-suggest-new-decoration
1328                                   hier
1329                                   (car (rst-get-decorations-around alldecos))))
1330
1331                      (nextdeco (rst-get-next-decoration
1332                                 curdeco hier suggestion reverse-direction))
1333
1334                      )
1335
1336                 ;; Indent, if present, always overrides the prescribed indent.
1337                 (setq char-new (car nextdeco)
1338                       style-new (cadr nextdeco)
1339                       indent-new (caddr nextdeco))
1340
1341                 )))
1342            )
1343
1344           ;; Override indent with present indent!
1345           (setq indent-new (if (> indent 0) indent indent-new))
1346
1347           (if (and char-new style-new)
1348               (rst-update-section char-new style-new indent-new))
1349           ))
1350
1351
1352     ;; Correct the position of the cursor to more accurately reflect where it
1353     ;; was located when the function was invoked.
1354     (unless (= moved 0)
1355       (forward-line (- moved))
1356       (end-of-line))
1357
1358     ))
1359
1360 ;; Maintain an alias for compatibility.
1361 (defalias 'rst-adjust-section-title 'rst-adjust)
1362
1363
1364 (defun rst-promote-region (&optional demote)
1365   "Promote the section titles within the region.
1366
1367 With argument DEMOTE or a prefix argument, demote the section
1368 titles instead.  The algorithm used at the boundaries of the
1369 hierarchy is similar to that used by `rst-adjust-decoration'."
1370   (interactive)
1371
1372   (let* ((demote (or current-prefix-arg demote))
1373          (alldecos (rst-find-all-decorations))
1374          (cur alldecos)
1375
1376          (hier (rst-get-hierarchy alldecos))
1377          (suggestion (rst-suggest-new-decoration hier))
1378
1379          (region-begin-line (line-number-at-pos (region-beginning)))
1380          (region-end-line (line-number-at-pos (region-end)))
1381
1382          marker-list
1383          )
1384
1385     ;; Skip the markers that come before the region beginning
1386     (while (and cur (< (caar cur) region-begin-line))
1387       (setq cur (cdr cur)))
1388
1389     ;; Create a list of markers for all the decorations which are found within
1390     ;; the region.
1391     (save-excursion
1392       (let (line)
1393         (while (and cur (< (setq line (caar cur)) region-end-line))
1394           (goto-char (point-min))
1395           (forward-line (1- line))
1396           (push (list (point-marker) (cdar cur)) marker-list)
1397           (setq cur (cdr cur)) ))
1398
1399       ;; Apply modifications.
1400       (dolist (p marker-list)
1401         ;; Go to the decoration to promote.
1402         (goto-char (car p))
1403
1404         ;; Update the decoration.
1405         (apply 'rst-update-section
1406                ;; Rotate the next decoration.
1407                (rst-get-next-decoration
1408                 (cadr p) hier suggestion demote))
1409
1410         ;; Clear marker to avoid slowing down the editing after we're done.
1411         (set-marker (car p) nil))
1412       (setq deactivate-mark nil)
1413       )))
1414
1415
1416
1417 (defun rst-display-decorations-hierarchy (&optional decorations)
1418   "Display the current file's section title decorations hierarchy.
1419 This function expects a list of (char, style, indent) triples in
1420 DECORATIONS."
1421   (interactive)
1422
1423   (if (not decorations)
1424       (setq decorations (rst-get-hierarchy)))
1425   (with-output-to-temp-buffer "*rest section hierarchy*"
1426     (let ((level 1))
1427       (with-current-buffer standard-output
1428         (dolist (x decorations)
1429           (insert (format "\nSection Level %d" level))
1430           (apply 'rst-update-section x)
1431           (goto-char (point-max))
1432           (insert "\n")
1433           (incf level)
1434           ))
1435     )))
1436
1437 (defun rst-position (elem list)
1438   "Return position of ELEM in LIST or nil."
1439   (let ((tail (member elem list)))
1440     (if tail (- (length list) (length tail)))))
1441
1442 (defun rst-straighten-decorations ()
1443   "Redo all the decorations in the current buffer.
1444 This is done using our preferred set of decorations.  This can be
1445 used, for example, when using somebody else's copy of a document,
1446 in order to adapt it to our preferred style."
1447   (interactive)
1448   (save-excursion
1449     (let* ((alldecos (rst-find-all-decorations))
1450            (hier (rst-get-hierarchy alldecos))
1451
1452            ;; Get a list of pairs of (level . marker)
1453            (levels-and-markers (mapcar
1454                                 (lambda (deco)
1455                                   (cons (rst-position (cdr deco) hier)
1456                                         (progn
1457                                           (goto-char (point-min))
1458                                           (forward-line (1- (car deco)))
1459                                           (point-marker))))
1460                                 alldecos))
1461            )
1462       (dolist (lm levels-and-markers)
1463         ;; Go to the appropriate position
1464         (goto-char (cdr lm))
1465
1466         ;; Apply the new styule
1467         (apply 'rst-update-section (nth (car lm) rst-preferred-decorations))
1468
1469         ;; Reset the market to avoid slowing down editing until it gets GC'ed
1470         (set-marker (cdr lm) nil)
1471         )
1472     )))
1473
1474
1475
1476
1477 (defun rst-straighten-deco-spacing ()
1478   "Adjust the spacing before and after decorations in the entire document.
1479 The spacing will be set to two blank lines before the first two
1480 section levels, and one blank line before any of the other
1481 section levels."
1482 ;; FIXME: we need to take care of subtitle at some point.
1483   (interactive)
1484   (save-excursion
1485     (let* ((alldecos (rst-find-all-decorations)))
1486
1487       ;; Work the list from the end, so that we don't have to use markers to
1488       ;; adjust for the changes in the document.
1489       (dolist (deco (nreverse alldecos))
1490         ;; Go to the appropriate position.
1491         (goto-char (point-min))
1492         (forward-line (1- (car deco)))
1493         (insert "@\n")
1494 ;; FIXME: todo, we
1495         )
1496     )))
1497
1498
1499 (defun rst-find-pfx-in-region (beg end pfx-re)
1500   "Find all the positions of prefixes in region between BEG and END.
1501 This is used to find bullets and enumerated list items.  PFX-RE
1502 is a regular expression for matching the lines with items."
1503   (let ((pfx ()))
1504     (save-excursion
1505       (goto-char beg)
1506       (while (< (point) end)
1507         (back-to-indentation)
1508         (when (and
1509                (looking-at pfx-re)
1510                (let ((pfx-col (current-column)))
1511                  (save-excursion
1512                    (forward-line -1)
1513                    (back-to-indentation)
1514                    (or (looking-at "^[ \t]*$")
1515                        (> (current-column) pfx-col)
1516                        (and (= (current-column) pfx-col)
1517                             (looking-at pfx-re))))))
1518           (push (cons (point) (current-column))
1519                 pfx))
1520         (forward-line 1)) )
1521     (nreverse pfx)))
1522
1523 (defvar rst-re-bullets
1524   (format "\\([%s][ \t]\\)[^ \t]" (regexp-quote (concat rst-bullets)))
1525   "Regexp for finding bullets.")
1526
1527 ;; (defvar rst-re-enumerations
1528 ;;   "\\(\\(#\\|[0-9]+\\)\\.[ \t]\\)[^ \t]"
1529 ;;   "Regexp for finding bullets.")
1530
1531 (defvar rst-re-items
1532   (format "\\(%s\\|%s\\)[^ \t]"
1533           (format "[%s][ \t]" (regexp-quote (concat rst-bullets)))
1534           "\\(#\\|[0-9]+\\)\\.[ \t]")
1535   "Regexp for finding bullets.")
1536
1537 (defvar rst-preferred-bullets
1538   '(?- ?* ?+)
1539   "List of favourite bullets to set for straightening bullets.")
1540
1541 (defun rst-straighten-bullets-region (beg end)
1542   "Make all the bulleted list items in the region consistent.
1543 The region is specified between BEG and END.  You can use this
1544 after you have merged multiple bulleted lists to make them use
1545 the same/correct/consistent bullet characters.
1546
1547 See variable `rst-preferred-bullets' for the list of bullets to
1548 adjust.  If bullets are found on levels beyond the
1549 `rst-preferred-bullets' list, they are not modified."
1550   (interactive "r")
1551
1552   (let ((bullets (rst-find-pfx-in-region beg end
1553                                          rst-re-bullets))
1554         (levtable (make-hash-table :size 4)))
1555
1556     ;; Create a map of levels to list of positions.
1557     (dolist (x bullets)
1558       (let ((key (cdr x)))
1559         (puthash key
1560                   (append (gethash key levtable (list))
1561                           (list (car x)))
1562                   levtable)))
1563
1564     ;; Sort this map and create a new map of prefix char and list of positions.
1565     (let ((poslist ()))                 ; List of (indent . positions).
1566       (maphash (lambda (x y) (push (cons x y) poslist)) levtable)
1567
1568       (let ((bullets rst-preferred-bullets))
1569         (dolist (x (sort poslist 'car-less-than-car))
1570           (when bullets
1571             ;; Apply the characters.
1572             (dolist (pos (cdr x))
1573               (goto-char pos)
1574               (delete-char 1)
1575               (insert (string (car bullets))))
1576             (setq bullets (cdr bullets))))))))
1577
1578 (defun rst-rstrip (str)
1579   "Strips the whitespace at the end of string STR."
1580   (string-match "[ \t\n]*\\'" str)
1581   (substring str 0 (match-beginning 0)))
1582
1583 (defun rst-get-stripped-line ()
1584   "Return the line at cursor, stripped from whitespace."
1585   (re-search-forward "\\S-.*\\S-" (line-end-position))
1586   (buffer-substring-no-properties (match-beginning 0)
1587                                   (match-end 0)) )
1588
1589 (defun rst-section-tree (alldecos)
1590   "Get the hierarchical tree of section titles.
1591
1592 Returns a hierarchical tree of the sections titles in the
1593 document, for decorations ALLDECOS.  This can be used to generate
1594 a table of contents for the document.  The top node will always
1595 be a nil node, with the top level titles as children (there may
1596 potentially be more than one).
1597
1598 Each section title consists in a cons of the stripped title
1599 string and a marker to the section in the original text document.
1600
1601 If there are missing section levels, the section titles are
1602 inserted automatically, and the title string is set to nil, and
1603 the marker set to the first non-nil child of itself.
1604 Conceptually, the nil nodes--i.e. those which have no title--are
1605 to be considered as being the same line as their first non-nil
1606 child.  This has advantages later in processing the graph."
1607
1608   (let* ((hier (rst-get-hierarchy alldecos))
1609          (levels (make-hash-table :test 'equal :size 10))
1610          lines)
1611
1612     (let ((lev 0))
1613       (dolist (deco hier)
1614         ;; Compare just the character and indent in the hash table.
1615         (puthash (cons (car deco) (cadr deco)) lev levels)
1616         (incf lev)))
1617
1618     ;; Create a list of lines that contains (text, level, marker) for each
1619     ;; decoration.
1620     (save-excursion
1621       (setq lines
1622             (mapcar (lambda (deco)
1623                       (goto-char (point-min))
1624                       (forward-line (1- (car deco)))
1625                       (list (gethash (cons (cadr deco) (caddr deco)) levels)
1626                             (rst-get-stripped-line)
1627                             (progn
1628                               (beginning-of-line 1)
1629                               (point-marker))))
1630                     alldecos)))
1631
1632     (let ((lcontnr (cons nil lines)))
1633       (rst-section-tree-rec lcontnr -1))))
1634
1635
1636 (defun rst-section-tree-rec (decos lev)
1637   "Recursive guts of the section tree construction.
1638 DECOS is a cons cell whose cdr is the remaining list of
1639 decorations, and we change it as we consume them.  LEV is
1640 the current level of that node.  This function returns a
1641 pair of the subtree that was built.  This treats the DECOS
1642 list destructively."
1643
1644   (let ((ndeco (cadr decos))
1645         node
1646         children)
1647
1648     ;; If the next decoration matches our level
1649     (when (and ndeco (= (car ndeco) lev))
1650       ;; Pop the next decoration and create the current node with it
1651       (setcdr decos (cddr decos))
1652       (setq node (cdr ndeco)) )
1653     ;; Else we let the node title/marker be unset.
1654
1655     ;; Build the child nodes
1656     (while (and (cdr decos) (> (caadr decos) lev))
1657       (setq children
1658             (cons (rst-section-tree-rec decos (1+ lev))
1659                   children)))
1660     (setq children (reverse children))
1661
1662     ;; If node is still unset, we use the marker of the first child.
1663     (when (eq node nil)
1664       (setq node (cons nil (cdaar children))))
1665
1666     ;; Return this node with its children.
1667     (cons node children)
1668     ))
1669
1670
1671 (defun rst-section-tree-point (node &optional point)
1672   "Find tree node at point.
1673 Given a computed and valid section tree in NODE and a point
1674 POINT (default being the current point in the current buffer),
1675 find and return the node within the sectree where the cursor
1676 lives.
1677
1678 Return values: a pair of (parent path, container subtree).
1679 The parent path is simply a list of the nodes above the
1680 container subtree node that we're returning."
1681
1682   (let (path outtree)
1683
1684     (let* ((curpoint (or point (point))))
1685
1686       ;; Check if we are before the current node.
1687       (if (and (cadar node) (>= curpoint (cadar node)))
1688
1689           ;; Iterate all the children, looking for one that might contain the
1690           ;; current section.
1691           (let ((curnode (cdr node))
1692                 last)
1693
1694             (while (and curnode (>= curpoint (cadaar curnode)))
1695               (setq last curnode
1696                     curnode (cdr curnode)))
1697
1698             (if last
1699                 (let ((sub (rst-section-tree-point (car last) curpoint)))
1700                   (setq path (car sub)
1701                         outtree (cdr sub)))
1702               (setq outtree node))
1703
1704             )))
1705     (cons (cons (car node) path) outtree)
1706     ))
1707
1708
1709 (defgroup rst-toc nil
1710   "Settings for reStructuredText table of contents."
1711   :group 'rst
1712   :version "21.1")
1713
1714 (defcustom rst-toc-indent 2
1715   "Indentation for table-of-contents display.
1716 Also used for formatting insertion, when numbering is disabled."
1717   :group 'rst-toc)
1718
1719 (defcustom rst-toc-insert-style 'fixed
1720   "Insertion style for table-of-contents.
1721 Set this to one of the following values to determine numbering and
1722 indentation style:
1723 - plain: no numbering (fixed indentation)
1724 - fixed: numbering, but fixed indentation
1725 - aligned: numbering, titles aligned under each other
1726 - listed: numbering, with dashes like list items (EXPERIMENTAL)"
1727   :group 'rst-toc)
1728
1729 (defcustom rst-toc-insert-number-separator "  "
1730   "Separator that goes between the TOC number and the title."
1731   :group 'rst-toc)
1732
1733 ;; This is used to avoid having to change the user's mode.
1734 (defvar rst-toc-insert-click-keymap
1735   (let ((map (make-sparse-keymap)))
1736        (define-key map [mouse-1] 'rst-toc-mode-mouse-goto)
1737        map)
1738   "(Internal) What happens when you click on propertized text in the TOC.")
1739
1740 (defcustom rst-toc-insert-max-level nil
1741   "If non-nil, maximum depth of the inserted TOC."
1742   :group 'rst-toc)
1743
1744
1745 (defun rst-toc-insert (&optional pfxarg)
1746   "Insert a simple text rendering of the table of contents.
1747 By default the top level is ignored if there is only one, because
1748 we assume that the document will have a single title.
1749
1750 If a numeric prefix argument PFXARG is given, insert the TOC up
1751 to the specified level.
1752
1753 The TOC is inserted indented at the current column."
1754
1755   (interactive "P")
1756
1757   (let* (;; Check maximum level override
1758          (rst-toc-insert-max-level
1759           (if (and (integerp pfxarg) (> (prefix-numeric-value pfxarg) 0))
1760               (prefix-numeric-value pfxarg) rst-toc-insert-max-level))
1761
1762          ;; Get the section tree for the current cursor point.
1763          (sectree-pair
1764           (rst-section-tree-point
1765            (rst-section-tree (rst-find-all-decorations))))
1766
1767          ;; Figure out initial indent.
1768          (initial-indent (make-string (current-column) ? ))
1769          (init-point (point)))
1770
1771     (when (cddr sectree-pair)
1772       (rst-toc-insert-node (cdr sectree-pair) 0 initial-indent "")
1773
1774       ;; Fixup for the first line.
1775       (delete-region init-point (+ init-point (length initial-indent)))
1776
1777       ;; Delete the last newline added.
1778       (delete-char -1)
1779     )))
1780
1781 (defun rst-toc-insert-node (node level indent pfx)
1782   "Insert tree node NODE in table-of-contents.
1783 Recursive function that does printing of the inserted toc.
1784 LEVEL is the depth level of the sections in the tree.
1785 INDENT is the indentation string.  PFX is the prefix numbering,
1786 that includes the alignment necessary for all the children of
1787 level to align."
1788
1789   ;; Note: we do child numbering from the parent, so we start number the
1790   ;; children one level before we print them.
1791   (let ((do-print (> level 0))
1792         (count 1))
1793     (when do-print
1794       (insert indent)
1795       (let ((b (point)))
1796         (unless (equal rst-toc-insert-style 'plain)
1797           (insert pfx rst-toc-insert-number-separator))
1798         (insert (or (caar node) "[missing node]"))
1799         ;; Add properties to the text, even though in normal text mode it
1800         ;; won't be doing anything for now.  Not sure that I want to change
1801         ;; mode stuff.  At least the highlighting gives the idea that this
1802         ;; is generated automatically.
1803         (put-text-property b (point) 'mouse-face 'highlight)
1804         (put-text-property b (point) 'rst-toc-target (cadar node))
1805         (put-text-property b (point) 'keymap rst-toc-insert-click-keymap)
1806
1807         )
1808       (insert "\n")
1809
1810       ;; Prepare indent for children.
1811       (setq indent
1812             (cond
1813              ((eq rst-toc-insert-style 'plain)
1814               (concat indent (make-string rst-toc-indent ? )))
1815
1816              ((eq rst-toc-insert-style 'fixed)
1817               (concat indent (make-string rst-toc-indent ? )))
1818
1819              ((eq rst-toc-insert-style 'aligned)
1820               (concat indent (make-string (+ (length pfx) 2) ? )))
1821
1822              ((eq rst-toc-insert-style 'listed)
1823               (concat (substring indent 0 -3)
1824                       (concat (make-string (+ (length pfx) 2) ? ) " - ")))
1825              ))
1826       )
1827
1828     (if (or (eq rst-toc-insert-max-level nil)
1829             (< level rst-toc-insert-max-level))
1830         (let ((do-child-numbering (>= level 0))
1831               fmt)
1832           (if do-child-numbering
1833               (progn
1834                 ;; Add a separating dot if there is already a prefix
1835                 (if (> (length pfx) 0)
1836                     (setq pfx (concat (rst-rstrip pfx) ".")))
1837
1838                 ;; Calculate the amount of space that the prefix will require
1839                 ;; for the numbers.
1840                 (if (cdr node)
1841                     (setq fmt (format "%%-%dd"
1842                                       (1+ (floor (log10 (length
1843                                                          (cdr node))))))))
1844                 ))
1845
1846           (dolist (child (cdr node))
1847             (rst-toc-insert-node child
1848                                  (1+ level)
1849                                  indent
1850                                  (if do-child-numbering
1851                                      (concat pfx (format fmt count)) pfx))
1852             (incf count)))
1853
1854       )))
1855
1856
1857 (defun rst-toc-insert-find-delete-contents ()
1858   "Find and delete an existing comment after the first contents directive.
1859 Delete that region.  Return t if found and the cursor is left after the comment."
1860   (goto-char (point-min))
1861   ;; We look for the following and the following only (in other words, if your
1862   ;; syntax differs, this won't work.  If you would like a more flexible thing,
1863   ;; contact the author, I just can't imagine that this requirement is
1864   ;; unreasonable for now).
1865   ;;
1866   ;;   .. contents:: [...anything here...]
1867   ;;   ..
1868   ;;      XXXXXXXX
1869   ;;      XXXXXXXX
1870   ;;      [more lines]
1871   ;;
1872   (let ((beg
1873          (re-search-forward "^\\.\\. contents[ \t]*::\\(.*\\)\n\\.\\."
1874                             nil t))
1875         last-real)
1876     (when beg
1877       ;; Look for the first line that starts at the first column.
1878       (forward-line 1)
1879       (beginning-of-line)
1880       (while (and
1881               (< (point) (point-max))
1882               (or (and (looking-at "[ \t]+[^ \t]") (setq last-real (point)) t)
1883                   (looking-at "[ \t]*$")))
1884         (forward-line 1)
1885         )
1886       (if last-real
1887           (progn
1888             (goto-char last-real)
1889             (end-of-line)
1890             (delete-region beg (point)))
1891         (goto-char beg))
1892       t
1893       )))
1894
1895 (defun rst-toc-update ()
1896   "Automatically find the contents section of a document and update.
1897 Updates the inserted TOC if present.  You can use this in your
1898 file-write hook to always make it up-to-date automatically."
1899   (interactive)
1900   (let ((p (point)))
1901     (save-excursion
1902       (when (rst-toc-insert-find-delete-contents)
1903         (insert "\n    ")
1904         (rst-toc-insert)
1905         ))
1906     ;; Somehow save-excursion does not really work well.
1907     (goto-char p))
1908   ;; Note: always return nil, because this may be used as a hook.
1909   )
1910
1911 ;; Note: we cannot bind the TOC update on file write because it messes with
1912 ;; undo.  If we disable undo, since it adds and removes characters, the
1913 ;; positions in the undo list are not making sense anymore.  Dunno what to do
1914 ;; with this, it would be nice to update when saving.
1915 ;;
1916 ;; (add-hook 'write-contents-hooks 'rst-toc-update-fun)
1917 ;; (defun rst-toc-update-fun ()
1918 ;;   ;; Disable undo for the write file hook.
1919 ;;   (let ((buffer-undo-list t)) (rst-toc-update) ))
1920
1921 (defalias 'rst-toc-insert-update 'rst-toc-update) ;; backwards compat.
1922
1923 ;;------------------------------------------------------------------------------
1924
1925 (defun rst-toc-node (node level)
1926   "Recursive function that does insert NODE at LEVEL in the table-of-contents."
1927
1928   (if (> level 0)
1929       (let ((b (point)))
1930         ;; Insert line text.
1931         (insert (make-string (* rst-toc-indent (1- level)) ? ))
1932         (insert (or (caar node) "[missing node]"))
1933
1934         ;; Highlight lines.
1935         (put-text-property b (point) 'mouse-face 'highlight)
1936
1937         ;; Add link on lines.
1938         (put-text-property b (point) 'rst-toc-target (cadar node))
1939
1940         (insert "\n")
1941         ))
1942
1943   (dolist (child (cdr node))
1944     (rst-toc-node child (1+ level))))
1945
1946 (defun rst-toc-count-lines (node target-node)
1947   "Count the number of lines from NODE to the TARGET-NODE node.
1948 This recursive function returns a cons of the number of
1949 additional lines that have been counted for its node and
1950 children, and t if the node has been found."
1951
1952   (let ((count 1)
1953         found)
1954     (if (eq node target-node)
1955         (setq found t)
1956       (let ((child (cdr node)))
1957         (while (and child (not found))
1958           (let ((cl (rst-toc-count-lines (car child) target-node)))
1959             (setq count (+ count (car cl))
1960                   found (cdr cl)
1961                   child (cdr child))))))
1962     (cons count found)))
1963
1964 (defvar rst-toc-buffer-name "*Table of Contents*"
1965   "Name of the Table of Contents buffer.")
1966
1967 (defvar rst-toc-return-buffer nil
1968   "Buffer to which to return when leaving the TOC.")
1969
1970
1971 (defun rst-toc ()
1972   "Display a table-of-contents.
1973 Finds all the section titles and their decorations in the
1974 file, and displays a hierarchically-organized list of the
1975 titles, which is essentially a table-of-contents of the
1976 document.
1977
1978 The Emacs buffer can be navigated, and selecting a section
1979 brings the cursor in that section."
1980   (interactive)
1981   (let* ((curbuf (current-buffer))
1982
1983          ;; Get the section tree
1984          (alldecos (rst-find-all-decorations))
1985          (sectree (rst-section-tree alldecos))
1986
1987          (our-node (cdr (rst-section-tree-point sectree)))
1988          line
1989
1990          ;; Create a temporary buffer.
1991          (buf (get-buffer-create rst-toc-buffer-name))
1992          )
1993
1994     (with-current-buffer buf
1995       (let ((inhibit-read-only t))
1996         (rst-toc-mode)
1997         (delete-region (point-min) (point-max))
1998         (insert (format "Table of Contents: %s\n" (or (caar sectree) "")))
1999         (put-text-property (point-min) (point)
2000                            'face (list '(background-color . "gray")))
2001         (rst-toc-node sectree 0)
2002
2003         ;; Count the lines to our found node.
2004         (let ((linefound (rst-toc-count-lines sectree our-node)))
2005           (setq line (if (cdr linefound) (car linefound) 0)))
2006         ))
2007     (display-buffer buf)
2008     (pop-to-buffer buf)
2009
2010     ;; Save the buffer to return to.
2011     (set (make-local-variable 'rst-toc-return-buffer) curbuf)
2012
2013     ;; Move the cursor near the right section in the TOC.
2014     (goto-char (point-min))
2015     (forward-line (1- line))
2016     ))
2017
2018
2019 (defun rst-toc-mode-find-section ()
2020   "Get the section from text property at point."
2021   (let ((pos (get-text-property (point) 'rst-toc-target)))
2022     (unless pos
2023       (error "No section on this line"))
2024     (unless (buffer-live-p (marker-buffer pos))
2025       (error "Buffer for this section was killed"))
2026     pos))
2027
2028 (defun rst-goto-section (&optional kill)
2029   "Go to the section the current line describes."
2030   (interactive)
2031   (let ((pos (rst-toc-mode-find-section)))
2032     (when kill
2033       (kill-buffer (get-buffer rst-toc-buffer-name)))
2034     (pop-to-buffer (marker-buffer pos))
2035     (goto-char pos)
2036     ;; FIXME: make the recentering conditional on scroll.
2037     (recenter 5)))
2038
2039 (defun rst-toc-mode-goto-section ()
2040   "Go to the section the current line describes and kill the TOC buffer."
2041   (interactive)
2042   (rst-goto-section t))
2043
2044 (defun rst-toc-mode-mouse-goto (event)
2045   "In `rst-toc' mode, go to the occurrence whose line you click on.
2046 EVENT is the input event."
2047   (interactive "e")
2048   (let ((pos
2049     (with-current-buffer (window-buffer (posn-window (event-end event)))
2050       (save-excursion
2051         (goto-char (posn-point (event-end event)))
2052              (rst-toc-mode-find-section)))))
2053     (pop-to-buffer (marker-buffer pos))
2054     (goto-char pos)
2055     (recenter 5)))
2056
2057 (defun rst-toc-mode-mouse-goto-kill (event)
2058   "Same as `rst-toc-mode-mouse-goto', but kill TOC buffer as well."
2059   (interactive "e")
2060   (call-interactively 'rst-toc-mode-mouse-goto event)
2061   (kill-buffer (get-buffer rst-toc-buffer-name)))
2062
2063 (defun rst-toc-quit-window ()
2064   "Leave the current TOC buffer."
2065   (interactive)
2066   (quit-window)
2067   (pop-to-buffer rst-toc-return-buffer))
2068
2069 (defvar rst-toc-mode-map
2070   (let ((map (make-sparse-keymap)))
2071     (define-key map [mouse-1] 'rst-toc-mode-mouse-goto-kill)
2072     (define-key map [mouse-2] 'rst-toc-mode-mouse-goto)
2073     (define-key map "\C-m" 'rst-toc-mode-goto-section)
2074     (define-key map "f" 'rst-toc-mode-goto-section)
2075     (define-key map "q" 'rst-toc-quit-window)
2076     (define-key map "z" 'kill-this-buffer)
2077     map)
2078   "Keymap for `rst-toc-mode'.")
2079
2080 (put 'rst-toc-mode 'mode-class 'special)
2081
2082 ;; Could inherit from the new `special-mode'.
2083 (define-derived-mode rst-toc-mode nil "ReST-TOC"
2084   "Major mode for output from \\[rst-toc], the table-of-contents for the document."
2085   (setq buffer-read-only t))
2086
2087 ;; Note: use occur-mode (replace.el) as a good example to complete missing
2088 ;; features.
2089
2090
2091 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2092 ;;
2093 ;; Section movement commands.
2094 ;;
2095
2096 (defun rst-forward-section (&optional offset)
2097   "Skip to the next restructured text section title.
2098 OFFSET specifies how many titles to skip.  Use a negative OFFSET to move
2099 backwards in the file (default is to use 1)."
2100   (interactive)
2101   (let* (;; Default value for offset.
2102          (offset (or offset 1))
2103
2104          ;; Get all the decorations in the file, with their line numbers.
2105          (alldecos (rst-find-all-decorations))
2106
2107          ;; Get the current line.
2108          (curline (line-number-at-pos))
2109
2110          (cur alldecos)
2111          (idx 0)
2112          )
2113
2114     ;; Find the index of the "next" decoration w.r.t. to the current line.
2115     (while (and cur (< (caar cur) curline))
2116       (setq cur (cdr cur))
2117       (incf idx))
2118     ;; 'cur' is the decoration on or following the current line.
2119
2120     (if (and (> offset 0) cur (= (caar cur) curline))
2121         (incf idx))
2122
2123     ;; Find the final index.
2124     (setq idx (+ idx (if (> offset 0) (- offset 1) offset)))
2125     (setq cur (nth idx alldecos))
2126
2127     ;; If the index is positive, goto the line, otherwise go to the buffer
2128     ;; boundaries.
2129     (if (and cur (>= idx 0))
2130         (progn
2131           (goto-char (point-min))
2132           (forward-line (1- (car cur))))
2133       (if (> offset 0) (goto-char (point-max)) (goto-char (point-min))))
2134     ))
2135
2136 (defun rst-backward-section ()
2137   "Like `rst-forward-section', except move back one title."
2138   (interactive)
2139   (rst-forward-section -1))
2140
2141 (defun rst-mark-section (&optional arg allow-extend)
2142   "Select the section that point is currently in."
2143   ;; Cloned from mark-paragraph.
2144   (interactive "p\np")
2145   (unless arg (setq arg 1))
2146   (when (zerop arg)
2147     (error "Cannot mark zero sections"))
2148   (cond ((and allow-extend
2149               (or (and (eq last-command this-command) (mark t))
2150                   (rst-portable-mark-active-p)))
2151          (set-mark
2152           (save-excursion
2153             (goto-char (mark))
2154             (rst-forward-section arg)
2155             (point))))
2156         (t
2157          (rst-forward-section arg)
2158          (push-mark nil t t)
2159          (rst-forward-section (- arg)))))
2160
2161
2162
2163
2164
2165 \f
2166 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2167 ;; Functions to work on item lists (e.g. indent/dedent, enumerate), which are
2168 ;; always 2 or 3 characters apart horizontally with rest.
2169
2170 ;; (FIXME: there is currently a bug that makes the region go away when we do that.)
2171 (defvar rst-shift-fill-region nil
2172   "If non-nil, automatically re-fill the region that is being shifted.")
2173
2174 (defun rst-find-leftmost-column (beg end)
2175   "Find the leftmost column in the region."
2176   (let ((mincol 1000))
2177     (save-excursion
2178       (goto-char beg)
2179       (while (< (point) end)
2180         (back-to-indentation)
2181         (unless (looking-at "[ \t]*$")
2182           (setq mincol (min mincol (current-column))))
2183         (forward-line 1)
2184         ))
2185     mincol))
2186
2187
2188 ;; What we really need to do is compute all the possible alignment possibilities
2189 ;; and then select one.
2190 ;;
2191 ;; .. line-block::
2192 ;;
2193 ;;    a) sdjsds
2194 ;;
2195 ;;       - sdjsd jsjds
2196 ;;
2197 ;;           sdsdsjdsj
2198 ;;
2199 ;;               11. sjdss jddjs
2200 ;;
2201 ;; *  *  * * *   *   *
2202 ;;
2203 ;; Move backwards, accumulate the beginning positions, and also the second
2204 ;; positions, in case the line matches the bullet pattern, and then sort.
2205
2206 (defun rst-compute-bullet-tabs (&optional pt)
2207   "Build the list of possible horizontal alignment points.
2208 Search backwards from point (or point PT if specified) to
2209 build the list of possible horizontal alignment points that
2210 includes the beginning and contents of a restructuredtext
2211 bulleted or enumerated list item.  Return a sorted list
2212 of (COLUMN-NUMBER . LINE) pairs."
2213   (save-excursion
2214     (when pt (goto-char pt))
2215
2216     ;; We work our way backwards and towards the left.
2217     (let ((leftcol 100000) ;; Current column.
2218           (tablist nil) ;; List of tab positions.
2219           )
2220
2221       ;; Start by skipping the current line.
2222       (beginning-of-line 0)
2223
2224       ;; Search backwards for each line.
2225       (while (and (> (point) (point-min))
2226                   (> leftcol 0))
2227
2228         ;; Skip empty lines.
2229         (unless (looking-at "^[ \t]*$")
2230           ;; Inspect the current non-empty line
2231           (back-to-indentation)
2232
2233           ;; Skip lines that are beyond the current column (we want to move
2234           ;; towards the left).
2235           (let ((col (current-column)))
2236             (when (< col leftcol)
2237
2238               ;; Add the beginning of the line as a tabbing point.
2239               (unless (memq col (mapcar 'car tablist))
2240                 (push (cons col (point)) tablist))
2241
2242               ;; Look at the line to figure out if it is a bulleted or enumerate
2243               ;; list item.
2244               (when (looking-at
2245                       (concat
2246                        "\\(?:"
2247                        "\\(\\(?:[0-9a-zA-Z#]\\{1,3\\}[.):-]\\|[*+-]\\)[ \t]+\\)[^ \t\n]"
2248                        "\\|"
2249                        (format "\\(%s%s+[ \t]+\\)[^ \t\n]"
2250                                (regexp-quote (thing-at-point 'char))
2251                                (regexp-quote (thing-at-point 'char)))
2252                        "\\)"
2253                        ))
2254                 ;; Add the column of the contained item.
2255                 (let* ((matchlen (length (or (match-string 1) (match-string 2))))
2256                        (newcol (+ col matchlen)))
2257                   (unless (or (>= newcol leftcol)
2258                               (memq (+ col matchlen) (mapcar 'car tablist)))
2259                     (push (cons (+ col matchlen) (+ (point) matchlen))
2260                           tablist)))
2261                 )
2262
2263               (setq leftcol col)
2264               )))
2265
2266         ;; Move backwards one line.
2267         (beginning-of-line 0))
2268
2269       (sort tablist (lambda (x y) (<= (car x) (car y))))
2270       )))
2271
2272 (defun rst-debug-print-tabs (tablist)
2273   "Insert a line and place special characters at the tab points in TABLIST."
2274   (beginning-of-line)
2275   (insert (concat "\n" (make-string 1000 ? ) "\n"))
2276   (beginning-of-line 0)
2277   (dolist (col tablist)
2278     (beginning-of-line)
2279     (forward-char (car col))
2280     (delete-char 1)
2281     (insert "@")
2282     ))
2283
2284 (defun rst-debug-mark-found (tablist)
2285   "Insert a line and place special characters at the tab points in TABLIST."
2286   (dolist (col tablist)
2287     (when (cdr col)
2288       (goto-char (cdr col))
2289       (insert "@"))))
2290
2291
2292 (defvar rst-shift-basic-offset 2
2293   "Basic horizontal shift distance when there is no preceding alignment tabs.")
2294
2295 (defun rst-shift-region-guts (find-next-fun offset-fun)
2296   "(See `rst-shift-region-right' for a description)."
2297   (let* ((mbeg (copy-marker (region-beginning)))
2298          (mend (copy-marker (region-end)))
2299          (tabs (rst-compute-bullet-tabs mbeg))
2300          (leftmostcol (rst-find-leftmost-column (region-beginning) (region-end)))
2301          )
2302     ;; Add basic offset tabs at the end of the list.  This is a better
2303     ;; implementation technique than hysteresis and a basic offset because it
2304     ;; insures that movement in both directions is consistently using the same
2305     ;; column positions.  This makes it more predictable.
2306     (setq tabs
2307           (append tabs
2308                   (mapcar (lambda (x) (cons x nil))
2309                           (let ((maxcol 120)
2310                                 (max-lisp-eval-depth 2000))
2311                             (flet ((addnum (x)
2312                                            (if (> x maxcol)
2313                                                nil
2314                                              (cons x (addnum
2315                                                       (+ x rst-shift-basic-offset))))))
2316                               (addnum (or (caar (last tabs)) 0))))
2317                           )))
2318
2319     ;; (For debugging.)
2320     ;;; (save-excursion (goto-char mbeg) (forward-char -1) (rst-debug-print-tabs tabs))))
2321     ;;; (print tabs)
2322     ;;; (save-excursion (rst-debug-mark-found tabs))
2323
2324     ;; Apply the indent.
2325     (indent-rigidly
2326      mbeg mend
2327
2328      ;; Find the next tab after the leftmost columnt.
2329      (let ((tab (funcall find-next-fun tabs leftmostcol)))
2330
2331        (if tab
2332            (progn
2333              (when (cdar tab)
2334                (message "Aligned on '%s'"
2335                         (save-excursion
2336                           (goto-char (cdar tab))
2337                           (buffer-substring-no-properties
2338                            (line-beginning-position)
2339                            (line-end-position))))
2340                )
2341              (- (caar tab) leftmostcol)) ;; Num chars.
2342
2343          ;; Otherwise use the basic offset
2344          (funcall offset-fun rst-shift-basic-offset)
2345          )))
2346
2347     ;; Optionally reindent.
2348     (when rst-shift-fill-region
2349       (fill-region mbeg mend))
2350     ))
2351
2352 (defun rst-shift-region-right (pfxarg)
2353   "Indent region ridigly, by a few characters to the right.
2354 This function first computes all possible alignment columns by
2355 inspecting the lines preceding the region for bulleted or
2356 enumerated list items.  If the leftmost column is beyond the
2357 preceding lines, the region is moved to the right by
2358 `rst-shift-basic-offset'.  With a prefix argument, do not
2359 automatically fill the region."
2360   (interactive "P")
2361   (let ((rst-shift-fill-region
2362          (if (not pfxarg) rst-shift-fill-region)))
2363     (rst-shift-region-guts (lambda (tabs leftmostcol)
2364                              (let ((cur tabs))
2365                                (while (and cur (<= (caar cur) leftmostcol))
2366                                  (setq cur (cdr cur)))
2367                                cur))
2368                            'identity
2369                            )))
2370
2371 (defun rst-shift-region-left (pfxarg)
2372   "Like `rst-shift-region-right', except we move to the left.
2373 Also, if invoked with a negative prefix arg, the entire
2374 indentation is removed, up to the leftmost character in the
2375 region, and automatic filling is disabled."
2376   (interactive "P")
2377   (let ((mbeg (copy-marker (region-beginning)))
2378         (mend (copy-marker (region-end)))
2379         (leftmostcol (rst-find-leftmost-column
2380                       (region-beginning) (region-end)))
2381         (rst-shift-fill-region
2382          (if (not pfxarg) rst-shift-fill-region)))
2383
2384     (when (> leftmostcol 0)
2385       (if (and pfxarg (< (prefix-numeric-value pfxarg) 0))
2386           (progn
2387             (indent-rigidly (region-beginning) (region-end) (- leftmostcol))
2388             (when rst-shift-fill-region
2389               (fill-region mbeg mend))
2390             )
2391         (rst-shift-region-guts (lambda (tabs leftmostcol)
2392                                  (let ((cur (reverse tabs)))
2393                                    (while (and cur (>= (caar cur) leftmostcol))
2394                                      (setq cur (cdr cur)))
2395                                    cur))
2396                                '-
2397                                ))
2398       )))
2399
2400 (defmacro rst-iterate-leftmost-paragraphs
2401   (beg end first-only body-consequent body-alternative)
2402   "FIXME This definition is old and deprecated / we need to move
2403 to the newer version below:
2404
2405 Call FUN at the beginning of each line, with an argument that
2406 specifies whether we are at the first line of a paragraph that
2407 starts at the leftmost column of the given region BEG and END.
2408 Set FIRST-ONLY to true if you want to callback on the first line
2409 of each paragraph only."
2410   `(save-excursion
2411     (let ((leftcol (rst-find-leftmost-column ,beg ,end))
2412           (endm (copy-marker ,end)))
2413
2414       (do* (;; Iterate lines
2415             (l (progn (goto-char ,beg) (back-to-indentation))
2416                (progn (forward-line 1) (back-to-indentation)))
2417
2418             (previous nil valid)
2419
2420             (curcol (current-column)
2421                     (current-column))
2422
2423             (valid (and (= curcol leftcol)
2424                         (not (looking-at "[ \t]*$")))
2425                    (and (= curcol leftcol)
2426                         (not (looking-at "[ \t]*$"))))
2427             )
2428           ((>= (point) endm))
2429
2430         (if (if ,first-only
2431                 (and valid (not previous))
2432               valid)
2433             ,body-consequent
2434           ,body-alternative)
2435
2436         ))))
2437
2438
2439 (defmacro rst-iterate-leftmost-paragraphs-2 (spec &rest body)
2440   "Evaluate BODY for each line in region defined by BEG END.
2441 LEFTMOST is set to true if the line is one of the leftmost of the
2442 entire paragraph.  PARABEGIN is set to true if the line is the
2443 first of a paragraph."
2444   (declare (indent 1) (debug (sexp body)))
2445   (destructuring-bind
2446       (beg end parabegin leftmost isleftmost isempty) spec
2447
2448   `(save-excursion
2449      (let ((,leftmost (rst-find-leftmost-column ,beg ,end))
2450            (endm (copy-marker ,end)))
2451
2452       (do* (;; Iterate lines
2453             (l (progn (goto-char ,beg) (back-to-indentation))
2454                (progn (forward-line 1) (back-to-indentation)))
2455
2456             (empty-line-previous nil ,isempty)
2457
2458             (,isempty (looking-at "[ \t]*$")
2459                         (looking-at "[ \t]*$"))
2460
2461             (,parabegin (not ,isempty)
2462                         (and empty-line-previous
2463                              (not ,isempty)))
2464
2465             (,isleftmost (and (not ,isempty)
2466                               (= (current-column) ,leftmost))
2467                          (and (not ,isempty)
2468                               (= (current-column) ,leftmost)))
2469             )
2470           ((>= (point) endm))
2471
2472         (progn ,@body)
2473
2474         )))))
2475
2476
2477 ;;------------------------------------------------------------------------------
2478
2479 ;; FIXME: these next functions should become part of a larger effort to redo the
2480 ;; bullets in bulletted lists.  The enumerate would just be one of the possible
2481 ;; outputs.
2482 ;;
2483 ;; FIXME: TODO we need to do the enumeration removal as well.
2484
2485 (defun rst-enumerate-region (beg end)
2486   "Add enumeration to all the leftmost paragraphs in the given region.
2487 The region is specified between BEG and END.  With prefix argument,
2488 do all lines instead of just paragraphs."
2489   (interactive "r")
2490   (let ((count 0)
2491         (last-insert-len nil))
2492     (rst-iterate-leftmost-paragraphs
2493      beg end (not current-prefix-arg)
2494      (let ((ins-string (format "%d. " (incf count))))
2495        (setq last-insert-len (length ins-string))
2496        (insert ins-string))
2497      (insert (make-string last-insert-len ?\ ))
2498      )))
2499
2500 (defun rst-bullet-list-region (beg end)
2501   "Add bullets to all the leftmost paragraphs in the given region.
2502 The region is specified between BEG and END.  With prefix argument,
2503 do all lines instead of just paragraphs."
2504   (interactive "r")
2505   (rst-iterate-leftmost-paragraphs
2506    beg end (not current-prefix-arg)
2507    (insert "- ")
2508    (insert "  ")
2509    ))
2510
2511
2512 ;; FIXME: there are some problems left with the following function
2513 ;; implementation:
2514 ;;
2515 ;; * It does not deal with a varying number of digits appropriately
2516 ;; * It does not deal with multiple levels independently, and it should.
2517 ;;
2518 ;; I suppose it does 90% of the job for now.
2519
2520 (defun rst-convert-bullets-to-enumeration (beg end)
2521   "Convert all the bulleted items and enumerated items in the
2522 region to enumerated lists, renumbering as necessary."
2523   (interactive "r")
2524   (let* (;; Find items and convert the positions to markers.
2525          (items (mapcar
2526                  (lambda (x)
2527                    (cons (copy-marker (car x))
2528                          (cdr x)))
2529                  (rst-find-pfx-in-region beg end rst-re-items)))
2530          (count 1)
2531          )
2532     (save-excursion
2533       (dolist (x items)
2534         (goto-char (car x))
2535         (looking-at rst-re-items)
2536         (replace-match (format "%d. " count) nil nil nil 1)
2537         (incf count)
2538         ))
2539     ))
2540
2541
2542
2543 ;;------------------------------------------------------------------------------
2544
2545 (defun rst-line-block-region (rbeg rend &optional pfxarg)
2546   "Toggle line block prefixes for a region.
2547 With prefix argument set the empty lines too."
2548   (interactive "r\nP")
2549   (let ((comment-start "| ")
2550         (comment-end "")
2551         (comment-start-skip "| ")
2552         (comment-style 'indent)
2553         (force (not (not pfxarg))))
2554     (rst-iterate-leftmost-paragraphs-2
2555         (rbeg rend parbegin leftmost isleft isempty)
2556       (when (or force (not isempty))
2557         (move-to-column leftmost force)
2558         (delete-region (point) (+ (point) (- (current-indentation) leftmost)))
2559         (insert "| ")))))
2560
2561
2562 \f
2563 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2564
2565 (require 'font-lock)
2566
2567 (defgroup rst-faces nil "Faces used in Rst Mode."
2568   :group 'rst
2569   :group 'faces
2570   :version "21.1")
2571
2572 (defface rst-block '((t :inherit font-lock-keyword-face))
2573   "Face used for all syntax marking up a special block."
2574   :version "24.1"
2575   :group 'rst-faces)
2576
2577 (defcustom rst-block-face 'rst-block
2578   "All syntax marking up a special block."
2579   :version "24.1"
2580   :group 'rst-faces
2581   :type '(face))
2582 (make-obsolete-variable 'rst-block-face
2583                         "customize the face `rst-block' instead."
2584                         "24.1")
2585
2586 (defface rst-external '((t :inherit font-lock-type-face))
2587   "Face used for field names and interpreted text."
2588   :version "24.1"
2589   :group 'rst-faces)
2590
2591 (defcustom rst-external-face 'rst-external
2592   "Field names and interpreted text."
2593   :version "24.1"
2594   :group 'rst-faces
2595   :type '(face))
2596 (make-obsolete-variable 'rst-external-face
2597                         "customize the face `rst-external' instead."
2598                         "24.1")
2599
2600 (defface rst-definition '((t :inherit font-lock-function-name-face))
2601   "Face used for all other defining constructs."
2602   :version "24.1"
2603   :group 'rst-faces)
2604
2605 (defcustom rst-definition-face 'rst-definition
2606   "All other defining constructs."
2607   :version "24.1"
2608   :group 'rst-faces
2609   :type '(face))
2610 (make-obsolete-variable 'rst-definition-face
2611                         "customize the face `rst-definition' instead."
2612                         "24.1")
2613
2614 ;; XEmacs compatibility (?).
2615 (defface rst-directive (if (boundp 'font-lock-builtin-face)
2616                            '((t :inherit font-lock-builtin-face))
2617                          '((t :inherit font-lock-preprocessor-face)))
2618   "Face used for directives and roles."
2619   :version "24.1"
2620   :group 'rst-faces)
2621
2622 (defcustom rst-directive-face 'rst-directive
2623   "Directives and roles."
2624   :group 'rst-faces
2625   :type '(face))
2626 (make-obsolete-variable 'rst-directive-face
2627                         "customize the face `rst-directive' instead."
2628                         "24.1")
2629
2630 (defface rst-comment '((t :inherit font-lock-comment-face))
2631   "Face used for comments."
2632   :version "24.1"
2633   :group 'rst-faces)
2634
2635 (defcustom rst-comment-face 'rst-comment
2636   "Comments."
2637   :version "24.1"
2638   :group 'rst-faces
2639   :type '(face))
2640 (make-obsolete-variable 'rst-comment-face
2641                         "customize the face `rst-comment' instead."
2642                         "24.1")
2643
2644 (defface rst-emphasis1 '((t :inherit italic))
2645   "Face used for simple emphasis."
2646   :version "24.1"
2647   :group 'rst-faces)
2648
2649 (defcustom rst-emphasis1-face 'rst-emphasis1
2650   "Simple emphasis."
2651   :version "24.1"
2652   :group 'rst-faces
2653   :type '(face))
2654 (make-obsolete-variable 'rst-emphasis1-face
2655                         "customize the face `rst-emphasis1' instead."
2656                         "24.1")
2657
2658 (defface rst-emphasis2 '((t :inherit bold))
2659   "Face used for double emphasis."
2660   :version "24.1"
2661   :group 'rst-faces)
2662
2663 (defcustom rst-emphasis2-face 'rst-emphasis2
2664   "Double emphasis."
2665   :group 'rst-faces
2666   :type '(face))
2667 (make-obsolete-variable 'rst-emphasis2-face
2668                         "customize the face `rst-emphasis2' instead."
2669                         "24.1")
2670
2671 (defface rst-literal '((t :inherit font-lock-string-face))
2672   "Face used for literal text."
2673   :version "24.1"
2674   :group 'rst-faces)
2675
2676 (defcustom rst-literal-face 'rst-literal
2677   "Literal text."
2678   :version "24.1"
2679   :group 'rst-faces
2680   :type '(face))
2681 (make-obsolete-variable 'rst-literal-face
2682                         "customize the face `rst-literal' instead."
2683                         "24.1")
2684
2685 (defface rst-reference '((t :inherit font-lock-variable-name-face))
2686   "Face used for references to a definition."
2687   :version "24.1"
2688   :group 'rst-faces)
2689
2690 (defcustom rst-reference-face 'rst-reference
2691   "References to a definition."
2692   :version "24.1"
2693   :group 'rst-faces
2694   :type '(face))
2695 (make-obsolete-variable 'rst-reference-face
2696                         "customize the face `rst-reference' instead."
2697                         "24.1")
2698
2699 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2700
2701 (defgroup rst-faces-defaults nil
2702   "Values used to generate default faces for section titles on all levels.
2703 Tweak these if you are content with how section title faces are built in
2704 general but you do not like the details."
2705   :group 'rst-faces
2706   :version "21.1")
2707
2708 (defun rst-set-level-default (sym val)
2709   "Set custom var SYM affecting section title text face and recompute the faces."
2710   (custom-set-default sym val)
2711   ;; Also defines the faces initially when all values are available
2712   (and (boundp 'rst-level-face-max)
2713        (boundp 'rst-level-face-format-light)
2714        (boundp 'rst-level-face-base-color)
2715        (boundp 'rst-level-face-step-light)
2716        (boundp 'rst-level-face-base-light)
2717        (fboundp 'rst-define-level-faces)
2718        (rst-define-level-faces)))
2719
2720 ;; Faces for displaying items on several levels; these definitions define
2721 ;; different shades of grey where the lightest one (i.e. least contrasting) is
2722 ;; used for level 1
2723 (defcustom rst-level-face-max 6
2724   "Maximum depth of levels for which section title faces are defined."
2725   :group 'rst-faces-defaults
2726   :type '(integer)
2727   :set 'rst-set-level-default)
2728 (defcustom rst-level-face-base-color "grey"
2729   "The base name of the color to be used for creating background colors in
2730 section title faces for all levels."
2731   :group 'rst-faces-defaults
2732   :type '(string)
2733   :set 'rst-set-level-default)
2734 (defcustom rst-level-face-base-light
2735   (if (eq frame-background-mode 'dark)
2736       15
2737     85)
2738   "The lightness factor for the base color.  This value is used for level 1.
2739 The default depends on whether the value of `frame-background-mode' is
2740 `dark' or not."
2741   :group 'rst-faces-defaults
2742   :type '(integer)
2743   :set 'rst-set-level-default)
2744 (defcustom rst-level-face-format-light "%2d"
2745   "The format for the lightness factor appended to the base name of the color.
2746 This value is expanded by `format' with an integer."
2747   :group 'rst-faces-defaults
2748   :type '(string)
2749   :set 'rst-set-level-default)
2750 (defcustom rst-level-face-step-light
2751   (if (eq frame-background-mode 'dark)
2752       7
2753     -7)
2754   "The step width to use for the next color.
2755 The formula
2756
2757     `rst-level-face-base-light'
2758     + (`rst-level-face-max' - 1) * `rst-level-face-step-light'
2759
2760 must result in a color level which appended to `rst-level-face-base-color'
2761 using `rst-level-face-format-light' results in a valid color such as `grey50'.
2762 This color is used as background for section title text on level
2763 `rst-level-face-max'."
2764   :group 'rst-faces-defaults
2765   :type '(integer)
2766   :set 'rst-set-level-default)
2767
2768 (defcustom rst-adornment-faces-alist
2769   (let ((alist '((t . font-lock-keyword-face)
2770                  (nil . font-lock-keyword-face)))
2771         (i 1))
2772     (while (<= i rst-level-face-max)
2773       (nconc alist (list (cons i (intern (format "rst-level-%d-face" i)))))
2774       (setq i (1+ i)))
2775     alist)
2776   "Faces for the various adornment types.
2777 Key is a number (for the section title text of that level),
2778 t (for transitions) or nil (for section title adornment).
2779 If you generally do not like how section title text faces are
2780 set up tweak here.  If the general idea is ok for you but you do not like the
2781 details check the Rst Faces Defaults group."
2782   :group 'rst-faces
2783   :type '(alist
2784           :key-type
2785           (choice
2786            (integer
2787             :tag
2788             "Section level (may not be bigger than `rst-level-face-max')")
2789            (boolean :tag "transitions (on) / section title adornment (off)"))
2790           :value-type (face))
2791   :set-after '(rst-level-face-max))
2792
2793 (defun rst-define-level-faces ()
2794   "Define the faces for the section title text faces from the values."
2795   ;; All variables used here must be checked in `rst-set-level-default'
2796   (let ((i 1))
2797     (while (<= i rst-level-face-max)
2798       (let ((sym (intern (format "rst-level-%d-face" i)))
2799             (doc (format "Face for showing section title text at level %d" i))
2800             (col (format (concat "%s" rst-level-face-format-light)
2801                          rst-level-face-base-color
2802                          (+ (* (1- i) rst-level-face-step-light)
2803                             rst-level-face-base-light))))
2804         (make-empty-face sym)
2805         (set-face-doc-string sym doc)
2806         (set-face-background sym col)
2807         (set sym sym)
2808         (setq i (1+ i))))))
2809
2810 (rst-define-level-faces)
2811
2812 \f
2813 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2814 ;; Font lock
2815
2816 (defvar rst-use-char-classes
2817   (string-match "[[:alpha:]]" "b")
2818   "Non-nil if we can use the character classes in our regexps.")
2819
2820 (defun rst-font-lock-keywords-function ()
2821   "Return keywords to highlight in Rst mode according to current settings."
2822   ;; The reST-links in the comments below all relate to sections in
2823   ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
2824   (let* ( ;; This gets big - so let's define some abbreviations
2825          ;; horizontal white space
2826          (re-hws "[\t ]")
2827          ;; beginning of line with possible indentation
2828          (re-bol (concat "^" re-hws "*"))
2829          ;; Separates block lead-ins from their content
2830          (re-blksep1 (concat "\\(" re-hws "+\\|$\\)"))
2831          ;; explicit markup tag
2832          (re-emt "\\.\\.")
2833          ;; explicit markup start
2834          (re-ems (concat re-emt re-hws "+"))
2835          ;; inline markup prefix
2836          (re-imp1 (concat "\\(^\\|" re-hws "\\|[-'\"([{</:]\\)"))
2837          ;; inline markup suffix
2838          (re-ims1 (concat "\\(" re-hws "\\|[]-'\")}>/:.,;!?\\]\\|$\\)"))
2839          ;; symbol character
2840          (re-sym1 "\\(\\sw\\|\\s_\\)")
2841          ;; inline markup content begin
2842          (re-imbeg2 "\\(\\S \\|\\S \\([^")
2843
2844          ;; There seems to be a bug leading to error "Stack overflow in regexp
2845          ;; matcher" when "|" or "\\*" are the characters searched for
2846          (re-imendbeg "\\]\\|\\\\.")
2847          ;; inline markup content end
2848          (re-imend (concat re-imendbeg "\\)*[^\t \\\\]\\)"))
2849          ;; inline markup content without asterisk
2850          (re-ima2 (concat re-imbeg2 "*" re-imend))
2851          ;; inline markup content without backquote
2852          (re-imb2 (concat re-imbeg2 "`" re-imend))
2853          ;; inline markup content without vertical bar
2854          (re-imv2 (concat re-imbeg2 "|" re-imend))
2855          ;; Supported URI schemes
2856          (re-uris1 "\\(acap\\|cid\\|data\\|dav\\|fax\\|file\\|ftp\\|gopher\\|http\\|https\\|imap\\|ldap\\|mailto\\|mid\\|modem\\|news\\|nfs\\|nntp\\|pop\\|prospero\\|rtsp\\|service\\|sip\\|tel\\|telnet\\|tip\\|urn\\|vemmi\\|wais\\)")
2857          ;; Line starting with adornment and optional whitespace; complete
2858          ;; adornment is in (match-string 1); there must be at least 3
2859          ;; characters because otherwise explicit markup start would be
2860          ;; recognized
2861          (re-ado2 (concat "^\\(\\(["
2862                           (if rst-use-char-classes
2863                               "^[:word:][:space:][:cntrl:]" "^\\w \t\x00-\x1F")
2864                           "]\\)\\2\\2+\\)" re-hws "*$"))
2865          )
2866     (list
2867      ;; FIXME: Block markup is not recognized in blocks after explicit markup
2868      ;; start
2869
2870      ;; Simple `Body Elements`_
2871      ;; `Bullet Lists`_
2872      `(,(concat re-bol "\\([-*+]" re-blksep1 "\\)")
2873        1 rst-block-face)
2874      ;; `Enumerated Lists`_
2875      `(,(concat re-bol "\\((?\\(#\\|[0-9]+\\|[A-Za-z]\\|[IVXLCMivxlcm]+\\)[.)]"
2876                 re-blksep1 "\\)")
2877        1 rst-block-face)
2878      ;; `Definition Lists`_ FIXME: missing
2879      ;; `Field Lists`_
2880      `(,(concat re-bol "\\(:[^:\n]+:\\)" re-blksep1)
2881        1 rst-external-face)
2882      ;; `Option Lists`_
2883      `(,(concat re-bol "\\(\\(\\(\\([-+/]\\|--\\)\\sw\\(-\\|\\sw\\)*"
2884                "\\([ =]\\S +\\)?\\)\\(,[\t ]\\)?\\)+\\)\\($\\|[\t ]\\{2\\}\\)")
2885        1 rst-block-face)
2886
2887      ;; `Tables`_ FIXME: missing
2888
2889      ;; All the `Explicit Markup Blocks`_
2890      ;; `Footnotes`_ / `Citations`_
2891      `(,(concat re-bol "\\(" re-ems "\\[[^[\n]+\\]\\)" re-blksep1)
2892       1 rst-definition-face)
2893      ;; `Directives`_ / `Substitution Definitions`_
2894      `(,(concat re-bol "\\(" re-ems "\\)\\(\\(|[^|\n]+|[\t ]+\\)?\\)\\("
2895                 re-sym1 "+::\\)" re-blksep1)
2896        (1 rst-directive-face)
2897        (2 rst-definition-face)
2898        (4 rst-directive-face))
2899      ;; `Hyperlink Targets`_
2900      `(,(concat re-bol "\\(" re-ems "_\\([^:\\`\n]\\|\\\\.\\|`[^`\n]+`\\)+:\\)"
2901                 re-blksep1)
2902        1 rst-definition-face)
2903      `(,(concat re-bol "\\(__\\)" re-blksep1)
2904        1 rst-definition-face)
2905
2906      ;; All `Inline Markup`_
2907      ;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented
2908      ;; `Strong Emphasis`_
2909      `(,(concat re-imp1 "\\(\\*\\*" re-ima2 "\\*\\*\\)" re-ims1)
2910        2 rst-emphasis2-face)
2911      ;; `Emphasis`_
2912      `(,(concat re-imp1 "\\(\\*" re-ima2 "\\*\\)" re-ims1)
2913        2 rst-emphasis1-face)
2914      ;; `Inline Literals`_
2915      `(,(concat re-imp1 "\\(``" re-imb2 "``\\)" re-ims1)
2916        2 rst-literal-face)
2917      ;; `Inline Internal Targets`_
2918      `(,(concat re-imp1 "\\(_`" re-imb2 "`\\)" re-ims1)
2919        2 rst-definition-face)
2920      ;; `Hyperlink References`_
2921      ;; FIXME: `Embedded URIs`_ not considered
2922      `(,(concat re-imp1 "\\(\\(`" re-imb2 "`\\|\\(\\sw\\(\\sw\\|-\\)+\\sw\\)\\)__?\\)" re-ims1)
2923       2 rst-reference-face)
2924      ;; `Interpreted Text`_
2925      `(,(concat re-imp1 "\\(\\(:" re-sym1 "+:\\)?\\)\\(`" re-imb2 "`\\)\\(\\(:"
2926                 re-sym1 "+:\\)?\\)" re-ims1)
2927        (2 rst-directive-face)
2928        (5 rst-external-face)
2929        (8 rst-directive-face))
2930      ;; `Footnote References`_ / `Citation References`_
2931      `(,(concat re-imp1 "\\(\\[[^]]+\\]_\\)" re-ims1)
2932        2 rst-reference-face)
2933      ;; `Substitution References`_
2934      `(,(concat re-imp1 "\\(|" re-imv2 "|\\)" re-ims1)
2935        2 rst-reference-face)
2936      ;; `Standalone Hyperlinks`_
2937      `(;; FIXME: This takes it easy by using a whitespace as delimiter
2938        ,(concat re-imp1 "\\(" re-uris1 ":\\S +\\)" re-ims1)
2939        2 rst-definition-face)
2940      `(,(concat re-imp1 "\\(" re-sym1 "+@" re-sym1 "+\\)" re-ims1)
2941        2 rst-definition-face)
2942
2943      ;; Do all block fontification as late as possible so 'append works
2944
2945      ;; Sections_ / Transitions_
2946      (append
2947       (list
2948        re-ado2)
2949       (if (not rst-mode-lazy)
2950           '(1 rst-block-face)
2951         (list
2952          (list 'rst-font-lock-handle-adornment
2953                '(progn
2954                   (setq rst-font-lock-adornment-point (match-end 1))
2955                   (point-max))
2956                nil
2957                (list 1 '(cdr (assoc nil rst-adornment-faces-alist))
2958                      'append t)
2959                (list 2 '(cdr (assoc rst-font-lock-level
2960                                     rst-adornment-faces-alist))
2961                      'append t)
2962                (list 3 '(cdr (assoc nil rst-adornment-faces-alist))
2963                      'append t)))))
2964
2965      ;; `Comments`_
2966      (append
2967       (list
2968        (concat re-bol "\\(" re-ems "\\)\[^[|_]\\([^:\n]\\|:\\([^:\n]\\|$\\)\\)*$")
2969
2970        '(1 rst-comment-face))
2971       (if rst-mode-lazy
2972           (list
2973            (list 'rst-font-lock-find-unindented-line
2974                  '(progn
2975                     (setq rst-font-lock-indentation-point (match-end 1))
2976                     (point-max))
2977                  nil
2978                  '(0 rst-comment-face append)))))
2979      (append
2980       (list
2981        (concat re-bol "\\(" re-emt "\\)\\(\\s *\\)$")
2982        '(1 rst-comment-face)
2983        '(2 rst-comment-face))
2984       (if rst-mode-lazy
2985           (list
2986            (list 'rst-font-lock-find-unindented-line
2987                  '(progn
2988                     (setq rst-font-lock-indentation-point 'next)
2989                     (point-max))
2990                  nil
2991                  '(0 rst-comment-face append)))))
2992
2993      ;; `Literal Blocks`_
2994      (append
2995       (list
2996        (concat re-bol "\\(\\([^.\n]\\|\\.[^.\n]\\).*\\)?\\(::\\)$")
2997        '(3 rst-block-face))
2998       (if rst-mode-lazy
2999           (list
3000            (list 'rst-font-lock-find-unindented-line
3001                  '(progn
3002                     (setq rst-font-lock-indentation-point t)
3003                     (point-max))
3004                  nil
3005                  '(0 rst-literal-face append)))))
3006
3007     ;; `Doctest Blocks`_
3008     (append
3009      (list
3010       (concat re-bol "\\(>>>\\|\\.\\.\\.\\)\\(.+\\)")
3011       '(1 rst-block-face)
3012       '(2 rst-literal-face)))
3013     )))
3014
3015
3016
3017 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3018 ;; Indented blocks
3019
3020 (defun rst-forward-indented-block (&optional column limit)
3021   "Move forward across one indented block.
3022 Find the next non-empty line which is not indented at least to COLUMN (defaults
3023 to the column of the point).  Moves point to first character of this line or the
3024 first empty line immediately before it and returns that position.  If there is
3025 no such line before LIMIT (defaults to the end of the buffer) returns nil and
3026 point is not moved."
3027   (interactive)
3028   (let ((clm (or column (current-column)))
3029         (start (point))
3030         fnd beg cand)
3031     (if (not limit)
3032         (setq limit (point-max)))
3033     (save-match-data
3034       (while (and (not fnd) (< (point) limit))
3035         (forward-line 1)
3036         (when (< (point) limit)
3037           (setq beg (point))
3038           (if (looking-at "\\s *$")
3039               (setq cand (or cand beg)) ; An empty line is a candidate
3040             (move-to-column clm)
3041             ;; FIXME: No indentation [(zerop clm)] must be handled in some
3042             ;; useful way - though it is not clear what this should mean at all
3043             (if (string-match
3044                  "^\\s *$" (buffer-substring-no-properties beg (point)))
3045                 (setq cand nil) ; An indented line resets a candidate
3046               (setq fnd (or cand beg)))))))
3047     (goto-char (or fnd start))
3048     fnd))
3049
3050 ;; Stores the point where the current indentation ends if a number. If `next'
3051 ;; indicates `rst-font-lock-find-unindented-line' shall take the indentation
3052 ;; from the next line if this is not empty. If non-nil indicates
3053 ;; `rst-font-lock-find-unindented-line' shall take the indentation from the
3054 ;; next non-empty line. Also used as a trigger for
3055 ;; `rst-font-lock-find-unindented-line'.
3056 (defvar rst-font-lock-indentation-point nil)
3057
3058 (defun rst-font-lock-find-unindented-line (limit)
3059   (let* ((ind-pnt rst-font-lock-indentation-point)
3060          (beg-pnt ind-pnt))
3061     ;; May run only once - enforce this
3062     (setq rst-font-lock-indentation-point nil)
3063     (when (and ind-pnt (not (numberp ind-pnt)))
3064       ;; Find indentation point in next line if any
3065       (setq ind-pnt
3066             (save-excursion
3067               (save-match-data
3068                 (if (eq ind-pnt 'next)
3069                     (when (and (zerop (forward-line 1)) (< (point) limit))
3070                       (setq beg-pnt (point))
3071                       (when (not (looking-at "\\s *$"))
3072                         (looking-at "\\s *")
3073                         (match-end 0)))
3074                   (while (and (zerop (forward-line 1)) (< (point) limit)
3075                               (looking-at "\\s *$")))
3076                   (when (< (point) limit)
3077                     (setq beg-pnt (point))
3078                     (looking-at "\\s *")
3079                     (match-end 0)))))))
3080     (when ind-pnt
3081       (goto-char ind-pnt)
3082       ;; Always succeeds because the limit set by PRE-MATCH-FORM is the
3083       ;; ultimate point to find
3084       (goto-char (or (rst-forward-indented-block nil limit) limit))
3085       (save-excursion
3086         ;; Include subsequent empty lines in the font-lock block,
3087         ;; in case the user subsequently changes the indentation of the next
3088         ;; non-empty line to move it into the indented element.
3089         (skip-chars-forward " \t\n")
3090         (put-text-property beg-pnt (point) 'font-lock-multiline t))
3091       (set-match-data (list beg-pnt (point)))
3092       t)))
3093
3094 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3095 ;; Adornments
3096
3097 (defvar rst-font-lock-adornment-point nil
3098   "Stores the point where the current adornment ends.
3099 Also used as a trigger for `rst-font-lock-handle-adornment'.")
3100
3101 ;; Here `rst-font-lock-handle-adornment' stores the section level of the
3102 ;; current adornment or t for a transition.
3103 (defvar rst-font-lock-level nil)
3104
3105 ;; FIXME: It would be good if this could be used to markup section titles of
3106 ;; given level with a special key; it would be even better to be able to
3107 ;; customize this so it can be used for a generally available personal style
3108 ;;
3109 ;; FIXME: There should be some way to reset and reload this variable - probably
3110 ;; a special key
3111 ;;
3112 ;; FIXME: Some support for `outline-mode' would be nice which should be based
3113 ;; on this information
3114 (defvar rst-adornment-level-alist nil
3115   "Associates adornments with section levels.
3116 The key is a two character string.  The first character is the adornment
3117 character.  The second character distinguishes underline section titles (`u')
3118 from overline/underline section titles (`o').  The value is the section level.
3119
3120 This is made buffer local on start and adornments found during font lock are
3121 entered.")
3122
3123 ;; Returns section level for adornment key KEY. Adds new section level if KEY
3124 ;; is not found and ADD. If KEY is not a string it is simply returned.
3125 (defun rst-adornment-level (key &optional add)
3126   (let ((fnd (assoc key rst-adornment-level-alist))
3127         (new 1))
3128     (cond
3129      ((not (stringp key))
3130       key)
3131      (fnd
3132       (cdr fnd))
3133      (add
3134       (while (rassoc new rst-adornment-level-alist)
3135         (setq new (1+ new)))
3136       (setq rst-adornment-level-alist
3137             (append rst-adornment-level-alist (list (cons key new))))
3138       new))))
3139
3140 ;; Classifies adornment for section titles and transitions. ADORNMENT is the
3141 ;; complete adornment string as found in the buffer. END is the point after the
3142 ;; last character of ADORNMENT. For overline section adornment LIMIT limits the
3143 ;; search for the matching underline. Returns a list. The first entry is t for
3144 ;; a transition, or a key string for `rst-adornment-level' for a section title.
3145 ;; The following eight values forming four match groups as can be used for
3146 ;; `set-match-data'. First match group contains the maximum points of the whole
3147 ;; construct. Second and last match group matched pure section title adornment
3148 ;; while third match group matched the section title text or the transition.
3149 ;; Each group but the first may or may not exist.
3150 (defun rst-classify-adornment (adornment end limit)
3151   (save-excursion
3152     (save-match-data
3153       (goto-char end)
3154       (let ((ado-ch (aref adornment 0))
3155             (ado-re (regexp-quote adornment))
3156             (end-pnt (point))
3157             (beg-pnt (progn
3158                        (forward-line 0)
3159                        (point)))
3160             (nxt-emp
3161              (save-excursion
3162                (or (not (zerop (forward-line 1)))
3163                    (looking-at "\\s *$"))))
3164             (prv-emp
3165              (save-excursion
3166                (or (not (zerop (forward-line -1)))
3167                    (looking-at "\\s *$"))))
3168             key beg-ovr end-ovr beg-txt end-txt beg-und end-und)
3169         (cond
3170          ((and nxt-emp prv-emp)
3171           ;; A transition
3172           (setq key t)
3173           (setq beg-txt beg-pnt)
3174           (setq end-txt end-pnt))
3175          (prv-emp
3176           ;; An overline
3177           (setq key (concat (list ado-ch) "o"))
3178           (setq beg-ovr beg-pnt)
3179           (setq end-ovr end-pnt)
3180           (forward-line 1)
3181           (setq beg-txt (point))
3182           (while (and (< (point) limit) (not end-txt))
3183             (if (looking-at "\\s *$")
3184                 ;; No underline found
3185                 (setq end-txt (1- (point)))
3186               (when (looking-at (concat "\\(" ado-re "\\)\\s *$"))
3187                 (setq end-und (match-end 1))
3188                 (setq beg-und (point))
3189                 (setq end-txt (1- beg-und))))
3190             (forward-line 1)))
3191          (t
3192           ;; An underline
3193           (setq key (concat (list ado-ch) "u"))
3194           (setq beg-und beg-pnt)
3195           (setq end-und end-pnt)
3196           (setq end-txt (1- beg-und))
3197           (setq beg-txt (progn
3198                           (if (re-search-backward "^\\s *$" 1 'move)
3199                               (forward-line 1))
3200                           (point)))))
3201         (list key
3202               (or beg-ovr beg-txt beg-und)
3203               (or end-und end-txt end-und)
3204               beg-ovr end-ovr beg-txt end-txt beg-und end-und)))))
3205
3206 ;; Handles adornments for font-locking section titles and transitions. Returns
3207 ;; three match groups. First and last match group matched pure overline /
3208 ;; underline adornment while second group matched section title text. Each
3209 ;; group may not exist.
3210 (defun rst-font-lock-handle-adornment (limit)
3211   (let ((ado-pnt rst-font-lock-adornment-point))
3212     ;; May run only once - enforce this
3213     (setq rst-font-lock-adornment-point nil)
3214     (if ado-pnt
3215       (let* ((ado (rst-classify-adornment (match-string-no-properties 1)
3216                                           ado-pnt limit))
3217              (key (car ado))
3218              (mtc (cdr ado)))
3219         (setq rst-font-lock-level (rst-adornment-level key t))
3220         (goto-char (nth 1 mtc))
3221         (put-text-property (nth 0 mtc) (nth 1 mtc) 'font-lock-multiline t)
3222         (set-match-data mtc)
3223         t))))
3224
3225
3226
3227 \f
3228 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3229 ;; Support for conversion from within Emacs
3230
3231 (defgroup rst-compile nil
3232   "Settings for support of conversion of reStructuredText
3233 document with \\[rst-compile]."
3234   :group 'rst
3235   :version "21.1")
3236
3237 (defcustom rst-compile-toolsets
3238   `((html ,(if (executable-find "rst2html.py") "rst2html.py" "rst2html")
3239           ".html" nil)
3240     (latex ,(if (executable-find "rst2latex.py") "rst2latex.py" "rst2latex")
3241            ".tex" nil)
3242     (newlatex ,(if (executable-find "rst2newlatex.py") "rst2newlatex.py"
3243                  "rst2newlatex")
3244               ".tex" nil)
3245     (pseudoxml ,(if (executable-find "rst2pseudoxml.py") "rst2pseudoxml.py"
3246                   "rst2pseudoxml")
3247                ".xml" nil)
3248     (xml ,(if (executable-find "rst2xml.py") "rst2xml.py" "rst2xml")
3249          ".xml" nil)
3250     (pdf ,(if (executable-find "rst2pdf.py") "rst2pdf.py" "rst2pdf")
3251          ".pdf" nil)
3252     (s5 ,(if (executable-find "rst2s5.py") "rst2s5.py" "rst2s5")
3253         ".html" nil))
3254   "Table describing the command to use for each toolset.
3255 An association list of the toolset to a list of the (command to use,
3256 extension of produced filename, options to the tool (nil or a
3257 string)) to be used for converting the document."
3258   :type '(alist :options (html latex newlatex pseudoxml xml)
3259                 :key-type symbol
3260                 :value-type (list :tag "Specification"
3261                              (file :tag "Command")
3262                              (string :tag "File extension")
3263                              (choice :tag "Command options"
3264                                      (const :tag "No options" nil)
3265                                      (string :tag "Options"))))
3266   :group 'rst
3267   :version "24.1")
3268
3269 ;; Note for Python programmers not familiar with association lists: you can set
3270 ;; values in an alists like this, e.g. :
3271 ;; (setcdr (assq 'html rst-compile-toolsets)
3272 ;;      '("rst2html.py" ".htm" "--stylesheet=/docutils.css"))
3273
3274
3275 (defvar rst-compile-primary-toolset 'html
3276   "The default toolset for `rst-compile'.")
3277
3278 (defvar rst-compile-secondary-toolset 'latex
3279   "The default toolset for `rst-compile' with a prefix argument.")
3280
3281 (defun rst-compile-find-conf ()
3282   "Look for the configuration file in the parents of the current path."
3283   (interactive)
3284   (let ((file-name "docutils.conf")
3285         (buffer-file (buffer-file-name)))
3286     ;; Move up in the dir hierarchy till we find a change log file.
3287     (let* ((dir (file-name-directory buffer-file))
3288            (prevdir nil))
3289       (while (and (or (not (string= dir prevdir))
3290                       (setq dir nil)
3291                       nil)
3292                   (not (file-exists-p (concat dir file-name))))
3293         ;; Move up to the parent dir and try again.
3294         (setq prevdir dir)
3295         (setq dir (expand-file-name (file-name-directory
3296                                      (directory-file-name
3297                                       (file-name-directory dir)))))
3298         )
3299       (or (and dir (concat dir file-name)) nil)
3300     )))
3301
3302
3303 (require 'compile)
3304
3305 (defun rst-compile (&optional pfxarg)
3306   "Compile command to convert reST document into some output file.
3307 Attempts to find configuration file, if it can, overrides the
3308 options.  There are two commands to choose from, with a prefix
3309 argument, select the alternative toolset."
3310   (interactive "P")
3311   ;; Note: maybe we want to check if there is a Makefile too and not do anything
3312   ;; if that is the case.  I dunno.
3313   (let* ((toolset (cdr (assq (if pfxarg
3314                                  rst-compile-secondary-toolset
3315                                rst-compile-primary-toolset)
3316                         rst-compile-toolsets)))
3317          (command (car toolset))
3318          (extension (cadr toolset))
3319          (options (caddr toolset))
3320          (conffile (rst-compile-find-conf))
3321          (bufname (file-name-nondirectory buffer-file-name))
3322          (outname (file-name-sans-extension bufname)))
3323
3324     ;; Set compile-command before invocation of compile.
3325     (set (make-local-variable 'compile-command)
3326          (mapconcat 'identity
3327                     (list command
3328                           (or options "")
3329                           (if conffile
3330                               (concat "--config=\"" conffile "\"")
3331                             "")
3332                           bufname
3333                           (concat outname extension))
3334                     " "))
3335
3336     ;; Invoke the compile command.
3337     (if (or compilation-read-command current-prefix-arg)
3338         (call-interactively 'compile)
3339       (compile compile-command))
3340     ))
3341
3342 (defun rst-compile-alt-toolset ()
3343   "Compile command with the alternative toolset."
3344   (interactive)
3345   (rst-compile 't))
3346
3347 (defun rst-compile-pseudo-region ()
3348   "Show the pseudo-XML rendering of the current active region,
3349 or of the entire buffer, if the region is not selected."
3350   (interactive)
3351   (with-output-to-temp-buffer "*pseudoxml*"
3352     (shell-command-on-region
3353      (if mark-active (region-beginning) (point-min))
3354      (if mark-active (region-end) (point-max))
3355      (cadr (assq 'pseudoxml rst-compile-toolsets))
3356      standard-output)))
3357
3358 (defvar rst-pdf-program "xpdf"
3359   "Program used to preview PDF files.")
3360
3361 (defun rst-compile-pdf-preview ()
3362   "Convert the document to a PDF file and launch a preview program."
3363   (interactive)
3364   (let* ((tmp-filename (make-temp-file "rst-out" nil ".pdf"))
3365          (command (format "%s %s %s && %s %s"
3366                           (cadr (assq 'pdf rst-compile-toolsets))
3367          (command (format "rst2pdf.py %s %s && %s %s"
3368                           buffer-file-name tmp-filename
3369                           rst-pdf-program tmp-filename)))
3370     (start-process-shell-command "rst-pdf-preview" nil command)
3371     ;; Note: you could also use (compile command) to view the compilation
3372     ;; output.
3373     ))
3374
3375 (defvar rst-slides-program "firefox"
3376   "Program used to preview S5 slides.")
3377
3378 (defun rst-compile-slides-preview ()
3379   "Convert the document to an S5 slide presentation and launch a preview program."
3380   (interactive)
3381   (let* ((tmp-filename (make-temp-file "rst-slides" nil ".html"))
3382          (command (format "%s %s %s && %s %s"
3383                           (cadr (assq 's5 rst-compile-toolsets))
3384          (command (format "rst2s5.py %s %s && %s %s"
3385
3386                           buffer-file-name tmp-filename
3387                           rst-slides-program tmp-filename)))
3388     (start-process-shell-command "rst-slides-preview" nil command)
3389     ;; Note: you could also use (compile command) to view the compilation
3390     ;; output.
3391     ))
3392
3393
3394 \f
3395 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3396 ;;
3397 ;; Generic text functions that are more convenient than the defaults.
3398 ;;
3399
3400 (defun rst-replace-lines (fromchar tochar)
3401   "Replace flush-left lines, consisting of multiple FROMCHAR characters,
3402 with equal-length lines of TOCHAR."
3403   (interactive "\
3404 cSearch for flush-left lines of char:
3405 cand replace with char: ")
3406   (save-excursion
3407     (let ((searchre (concat "^" (regexp-quote (string fromchar)) "+\\( *\\)$"))
3408           (found 0))
3409       (while (search-forward-regexp searchre nil t)
3410         (setq found (1+ found))
3411         (goto-char (match-beginning 1))
3412         (let ((width (current-column)))
3413           (rst-delete-entire-line)
3414           (insert-char tochar width)))
3415       (message (format "%d lines replaced." found)))))
3416
3417 (defun rst-join-paragraph ()
3418   "Join lines in current paragraph into one line, removing end-of-lines."
3419   (interactive)
3420   (let ((fill-column 65000)) ; some big number
3421     (call-interactively 'fill-paragraph)))
3422
3423 (defun rst-force-fill-paragraph ()
3424   "Fill paragraph at point, first joining the paragraph's lines into one.
3425 This is useful for filling list item paragraphs."
3426   (interactive)
3427   (rst-join-paragraph)
3428   (fill-paragraph nil))
3429
3430
3431 ;; Generic character repeater function.
3432 ;; For sections, better to use the specialized function above, but this can
3433 ;; be useful for creating separators.
3434 (defun rst-repeat-last-character (&optional tofill)
3435   "Fill the current line up to the length of the preceding line (if not
3436 empty), using the last character on the current line.  If the preceding line is
3437 empty, we use the `fill-column'.
3438
3439 If a prefix argument is provided, use the next line rather than the preceding
3440 line.
3441
3442 If the current line is longer than the desired length, shave the characters off
3443 the current line to fit the desired length.
3444
3445 As an added convenience, if the command is repeated immediately, the alternative
3446 column is used (fill-column vs. end of previous/next line)."
3447   (interactive)
3448   (let* ((curcol (current-column))
3449          (curline (+ (count-lines (point-min) (point))
3450                      (if (eq curcol 0) 1 0)))
3451          (lbp (line-beginning-position 0))
3452          (prevcol (if (and (= curline 1) (not current-prefix-arg))
3453                       fill-column
3454                     (save-excursion
3455                       (forward-line (if current-prefix-arg 1 -1))
3456                       (end-of-line)
3457                       (skip-chars-backward " \t" lbp)
3458                       (let ((cc (current-column)))
3459                         (if (= cc 0) fill-column cc)))))
3460          (rightmost-column
3461           (cond (tofill fill-column)
3462                 ((equal last-command 'rst-repeat-last-character)
3463                  (if (= curcol fill-column) prevcol fill-column))
3464                 (t (save-excursion
3465                      (if (= prevcol 0) fill-column prevcol)))
3466                 )) )
3467     (end-of-line)
3468     (if (> (current-column) rightmost-column)
3469         ;; shave characters off the end
3470         (delete-region (- (point)
3471                           (- (current-column) rightmost-column))
3472                        (point))
3473       ;; fill with last characters
3474       (insert-char (preceding-char)
3475                    (- rightmost-column (current-column))))
3476     ))
3477
3478
3479 (defun rst-portable-mark-active-p ()
3480   "A portable function that returns non-nil if the mark is active."
3481   (cond
3482    ((fboundp 'region-active-p) (region-active-p))
3483    ((boundp 'transient-mark-mode) (and transient-mark-mode mark-active))
3484    (t mark-active)))
3485
3486 \f
3487 (provide 'rst)
3488
3489 ;;; rst.el ends here