Tips for Documentation Groups

Documentation groups, available since Emacs 28, are useful to document functions of Lisp packages based on various groupings (see Documentation Groups). This section gives some tips on how you can define documentation groups in your Lisp package in a way such that users of different Emacs versions can equally well use these groups.

• To define documentation groups for your own Lisp package across different Emacs versions, you can use a boilerplate template along the lines of the following to make your package compile and load without errors:

  ;;; well-doc.el --- a well-documented package -*- lexical-binding: t; -*-
  
  ... package header and contents ...

  ;; Explicitly require shortdoc for Emacs 28, which does not have an
  ;; autoload for macro `define-short-documentation-group'.  And for
  ;; Emacs 30, so that we can redefine `shortdoc--check' later.
  (require 'shortdoc nil t)
  
  (eval-when-compile
  
    ;; Default macro `define-short-documentation-group' for Emacs 27
    ;; and older, which do not have the shortdoc feature at all.
    (unless (fboundp 'define-short-documentation-group)
      (defmacro define-short-documentation-group (&rest _)))
  
    ;; Disable too rigid shortdoc checks for Emacs 30, which let it
    ;; error out on newer shortdoc keywords.
    (when (eq emacs-major-version 30)
      (fset 'shortdoc--check #'ignore)))

  (define-short-documentation-group well-doc
    ...)
  
  ;;; well-doc.el ends here

  If you do not intend to support some of the Emacs versions mentioned above, you can safely omit the corresponding forms from the template. If you intend to support only Emacs 31 and newer, you do not need any of the above and can just use define-short-documentation-group.

• Newer Emacs versions might introduce newer documentation group features and keywords. However, these features or keywords will never break the display of a documentation group in older Emacs versions. Suppose you use a hypothetical group keyword :super-pretty-print, available in some future Emacs version, like this in your Lisp package well-doc.el:

  (define-short-documentation-group well-doc
    (well-doc-foo
     :eval (well-doc-foo)
     :super-pretty-print t))

  That future Emacs version will then supposedly super-pretty-print the example for function well-doc-foo. Older Emacs versions will silently ignore keyword :super-pretty-print and show the example according to their regular display rules.