Function: rst-adjust-section

rst-adjust-section is a byte-compiled function defined in rst.el.gz.

Signature

(rst-adjust-section TOGGLE-STYLE REVERSE)

Documentation

Adjust/rotate the section adornment for the section title around point.

The action this function takes depends on context around the point, and it is meant to be invoked possibly more than once to rotate among the various possibilities. Basically, this function deals with:

- adding an adornment if the title does not have one;

- adjusting the length of the underline characters to fit a
  modified title;

- rotating the adornment in the set of already existing
  sectioning adornments used in the file;

- switching between simple and over-and-under styles by giving
  TOGGLE-STYLE.

Return nil if the function did something. If the function were not able to do something return an argument list for message to inform the user about what failed.

The following is a detailed description but you should normally not have to read it.

Before applying the adornment change, the cursor is placed on the closest line that could contain a section title if such is found around the cursor. Then the following cases are distinguished.

* Case 1: No Adornment

  If the current line has no adornment around it,

  - search for a previous adornment, and apply this adornment (unless
    rst-new-adornment-down) or one level lower (otherwise) to the current
    line. If there is no defined level below this previous adornment, we
    suggest the most appropriate of the rst-preferred-adornments.

    If REVERSE is true, we simply use the previous adornment found
    directly.

  - if there is no adornment found in the given direction, we use the first of
    rst-preferred-adornments.

  TOGGLE-STYLE forces a toggle of the prescribed adornment style.

* Case 2: Incomplete Adornment

  If the current line does have an existing adornment, but the adornment is
  incomplete, that is, the underline/overline does not extend to exactly the
  end of the title line (it is either too short or too long), we simply extend
  the length of the underlines/overlines to fit exactly the section title.

  If TOGGLE-STYLE we toggle the style of the adornment as well.

  REVERSE has no effect in this case.

* Case 3: Complete Existing Adornment

  If the adornment is complete (i.e. the underline (overline) length is already
  adjusted to the end of the title line), we rotate the current title's
  adornment according to the adornment hierarchy found in the buffer. This is
  meant to be used potentially multiple times, until the desired adornment is
  found around the title.

  If we hit the boundary of the hierarchy, exactly one choice from the list of
  preferred adornments is suggested/chosen, the first of those adornment that
  has not been seen in the buffer yet, and the next invocation rolls over to
  the other end of the hierarchy (i.e. it cycles).

  If REVERSE is we go up in the hierarchy. Otherwise we go down.

  However, if TOGGLE-STYLE, we do not rotate the adornment, but instead simply
  toggle the style of the current adornment.

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/rst.el.gz
(defun rst-adjust-section (toggle-style reverse)
  ;; testcover: ok.
  "Adjust/rotate the section adornment for the section title around point.
The action this function takes depends on context around the
point, and it is meant to be invoked possibly more than once to
rotate among the various possibilities.  Basically, this function
deals with:

- adding an adornment if the title does not have one;

- adjusting the length of the underline characters to fit a
  modified title;

- rotating the adornment in the set of already existing
  sectioning adornments used in the file;

- switching between simple and over-and-under styles by giving
  TOGGLE-STYLE.

Return nil if the function did something.  If the function were
not able to do something return an argument list for `message' to
inform the user about what failed.

The following is a detailed description but you should normally
not have to read it.

Before applying the adornment change, the cursor is placed on the
closest line that could contain a section title if such is found
around the cursor.  Then the following cases are distinguished.

* Case 1: No Adornment

  If the current line has no adornment around it,

  - search for a previous adornment, and apply this adornment (unless
    `rst-new-adornment-down') or one level lower (otherwise) to the current
    line.  If there is no defined level below this previous adornment, we
    suggest the most appropriate of the `rst-preferred-adornments'.

    If REVERSE is true, we simply use the previous adornment found
    directly.

  - if there is no adornment found in the given direction, we use the first of
    `rst-preferred-adornments'.

  TOGGLE-STYLE forces a toggle of the prescribed adornment style.

* Case 2: Incomplete Adornment

  If the current line does have an existing adornment, but the adornment is
  incomplete, that is, the underline/overline does not extend to exactly the
  end of the title line (it is either too short or too long), we simply extend
  the length of the underlines/overlines to fit exactly the section title.

  If TOGGLE-STYLE we toggle the style of the adornment as well.

  REVERSE has no effect in this case.

* Case 3: Complete Existing Adornment

  If the adornment is complete (i.e. the underline (overline) length is already
  adjusted to the end of the title line), we rotate the current title's
  adornment according to the adornment hierarchy found in the buffer.  This is
  meant to be used potentially multiple times, until the desired adornment is
  found around the title.

  If we hit the boundary of the hierarchy, exactly one choice from the list of
  preferred adornments is suggested/chosen, the first of those adornment that
  has not been seen in the buffer yet, and the next invocation rolls over to
  the other end of the hierarchy (i.e. it cycles).

  If REVERSE is we go up in the hierarchy.  Otherwise we go down.

  However, if TOGGLE-STYLE, we do not rotate the adornment, but instead simply
  toggle the style of the current adornment."
  (rst-reset-section-caches)
  (let ((ttl (rst-ttl-at-point)))
    (if (not ttl)
	'("No section header or candidate at point")
      (cl-destructuring-bind
	  (hdr toggle-style &rest msg
	       &aux
	       (indent (rst-Ttl-indent ttl))
	       (moved (- (line-number-at-pos (rst-Ttl-get-title-beginning ttl))
			 (line-number-at-pos))))
	  (rst-adjust-new-hdr toggle-style reverse ttl)
	(if msg
	    msg
	  (when toggle-style
	    (setq hdr (rst-Hdr-new-invert (rst-Hdr-ado hdr) indent)))
	  ;; Override indent with present indent if there is some.
	  (when (> indent 0)
	    ;; Use lax since existing indent may not be valid for new style.
	    (setq hdr (rst-Hdr-new-lax (rst-Hdr-ado hdr) indent)))
	  (goto-char (rst-Ttl-get-title-beginning ttl))
	  (rst-update-section hdr)
	  ;; Correct the position of the cursor to more accurately reflect
	  ;; where it was located when the function was invoked.
	  (unless (zerop moved)
	    (1value ; No lines may be left to move.
	     (rst-forward-line-strict (- moved)))
	    (end-of-line))
	  nil)))))