Idea for improved outline-minor-mode support

[dhermanson]

First of all, thank you for all of the work on this package!

I'm trying to get better support for outline-minor-mode. To me, the tricky part about asciidoc is that you can't just tell outline-mode that = is your character to use, because asciidoc uses = for example blocks.

So my idea is to setup the outline-regexp so that only lines which have leading =, followed by at least one [[:blank:]] character, and then at least one [[:word:]] character. That way, example blocks would never get accidentally marked as headings if they have trailing whitespace.

The next step if to hook into the outline-head-from-level function which takes the desired level, the heading to be converted, and an alist parameter, which we aren't using. Basically, I've written an advice function which grabs the title portion of the heading and then prefixes it with the desired number of ='s. If attempting to move to level 0 or a level greater than 5, complain.

Also worth noting is that the outline-level function informs outline-mode what level the heading is at. We configure a function which counts the leading ='s to determine the level.

Here is my code I'm using to accomplish this.

(require 'adoc-mode)
(require 's)

(defun deh/modes/adoc/outline-level ()
      (s-count-matches "=" (match-string 0)))


(setq deh/modes/header-and-title-match-regexp "^\\(=+\\)\\(.*\\)")


(defun deh/advice/adoc-outline-head-from-level (orig-fun &rest args)
  (pcase major-mode
    ;; if in adoc-mode, run our code
    (adoc-mode
     (progn
       (let* (;; this is the desired level
              (level (car args))

              ;; this is the value of the heading "before" changing the level
              (head (nth 1 args)) 

              ;; this is the "title" portion of the heading. everything after the ='s
              (title (nth 2 (s-match deh/modes/header-and-title-match-regexp head))))
         (cond
          ((zerop level) (error "Already at top level of the outline"))
          ((< level 6) (concat (s-repeat level "=") title))
          (t (error "asciidoc only supports 5 levels of indentaion")))))
     )
    ;; if not in adoc-mode, then run the original function
    (default (apply orig-fun args))))
  

(advice-add 'outline-head-from-level :around #'deh/advice/adoc-outline-head-from-level)


(defun deh/adoc-mode-hook ()
  "My adoc mode hook."

  (setq-local outline-regexp "^=\\{1,5\\}[[:blank:]]+[[:word:]]+.*")
  (setq-local outline-level 'deh/modes/adoc/outline-level)
  (outline-minor-mode t))

(add-hook 'adoc-mode-hook 'deh/adoc-mode-hook)

(provide 'deh-adoc)

[dhermanson]

After using this for a few days, I've changed my tune a little bit. I no longer think it's a good idea to have the title of the heading be a party of the outline heading. What's not nice is when you insert a new heading below an existing on via something like <M-return> it copies the entire heading value. I now think it's a better tradeoff to just look for the blank line after the = and use that to determine what the headings are.

Here' my revised code, FWIW.

(require 'adoc-mode)
(require 's)

(defun deh/modes/adoc/outline-level ()
      (s-count-matches "=" (match-string 0)))

(defun deh/advice/adoc-outline-head-from-level (orig-fun &rest args)
  (pcase major-mode
    ;; if in adoc-mode, run our code
    (adoc-mode
     (progn
       (let* (;; this is the desired level
              (level (car args))

              ;; this is the value of the heading "before" changing the level
              (head (nth 1 args)))
         (cond
          ((zerop level) (error "Already at top level of the outline"))
          ((< level 6) (concat (s-repeat level "=") " "))
          (t (error "asciidoc only supports 5 levels of indentaion")))))
     )
    ;; if not in adoc-mode, then run the original function
    (default (apply orig-fun args))))
  

(advice-add 'outline-head-from-level :around #'deh/advice/adoc-outline-head-from-level)


(defun deh/adoc-mode-hook ()
  "My adoc mode hook."

  (setq-local outline-regexp "^=\\{1,5\\}[[:blank:]]")
  (setq-local outline-level 'deh/modes/adoc/outline-level)
  (outline-minor-mode t))

(add-hook 'adoc-mode-hook 'deh/adoc-mode-hook)


(provide 'deh-adoc)

[bbatsov]

Your approach seems reasonable to me, although you should keep in mind that # is valid for section headings as well. Perhaps @TobiasZawada might another idea how the detected might work.

[TobiasZawada]

Ah, that's a discussion! I almost missed this one. Looked for it in the issues.

@bbatsov Did you already see this one: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/spec/outline.adoc?ref_type=heads ?

Therein: Rudimentary spec of section titles: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/spec/outline.adoc?ref_type=heads#user-content-sections

Especially, the regexp matching section titles should include the mandatory blank line.
If it does that, then the optional block attributes must also be matched.

False matches in code blocks are also an issue.

[bbatsov]

Nope, I haven't. Seems a lot of syntax is getting removed from the official spec (including most of the Markdown compatibility stuff). We should probably create some tickets to track the syntax parts that were removed so we can align our mode to the official spec.