View Emacs ‘NEWS’ files as ‘Info’ manual too

Setting the context for this article

This article is a continuation of my earlier article View ‘info’, ‘texi’, ‘org’ and ‘md’ files as ‘Info’ manual.

That article talked about how you may view info, texi, org and md files as info manual.

The article claimed that browsing Emacs-related documentation is a fragmented and dis-orienting experience, and asserted that viewing all documentation as a info manual lends itself to perceptually uniform experience.

Unfortunately, that article left out one important documentation vehicle for Emacs, the NEWS files. This article will set right that omission, and talk about how one may view NEWS files as Info manual.

Emacs NEWS files contain documentation too

Apart from info, texi, org and md formats, Emacs documentation also comes in outline format, the NEWS files.

The NEWS files are either org files, or outline-mode files with org like outline headings. This means that viewing a NEWS file as an info manual is a no-brainer. So, I have enhanced my previous snippet, to handle NEWS files too.

Snippet for viewing ‘NEWS’, ‘info’, ‘texi’, ‘org’ and ‘md’ files as ‘Info’ manual

Elisp snippet for M-x view-text-file-as-info-manual

(defun view-text-file-as-info-manual ()
  "View ‘info’, ‘texi’, ‘org’, ‘md’ and 'NEWS' files as ‘Info’ manual."
  (interactive)
  (require 'rx)
  (require 'ox-texinfo)
  (when (buffer-file-name)
    (let* ((org-export-with-broken-links 'mark)
           (ext (file-name-extension (buffer-file-name))))
      (cond
       ;; A NEWS files
       ((string-match "NEWS" (file-name-nondirectory (buffer-file-name)))
        (with-current-buffer
            ;; NEWS files are likely to be in read-only directories.
            ;; So make a copy with an `.org' extension.  Most NEWS
            ;; file are `outline-mode' files with `org' like heading
            ;; structure.  Many of the recent files like ORG-NEWS are
            ;; proper `org' files.
            (find-file-noselect
             (make-temp-file
              (format "%s---" (file-name-nondirectory (buffer-file-name))) nil ".org"
              (buffer-substring-no-properties (point-min) (point-max))))
          (org-with-wide-buffer
           ;; `ox-texinfo' export fails if a headline ends with a
           ;; period (= ".").  So, strip those terminating periods.
           (goto-char (point-min))
           (while (re-search-forward (rx (and bol
                                              (one-or-more "*")
                                              " "
                                              (one-or-more any)
                                              (group ".")
                                              eol))
                                     (point-max) t)
             (replace-match "" t t nil 1))
           (goto-char (point-min))
           (while nil
             ;; TODO: If a NEWS file contains text which resemble a
             ;; LaTeX fragment, the `ox-texinfo' export wouldn't
             ;; succeed.  So, enclose the LaTeX fragment with Org's
             ;; verbatim `=' marker.
             )
           (save-buffer 0)
           (info (org-texinfo-export-to-info)))))
       ;; A `.info' file
       ((or (string= "info" ext))
        (info (buffer-file-name)))
       ;; A `.texi' file
       ((or (string= "texi" ext))
        (info (org-texinfo-compile (buffer-file-name))))
       ;; An `.org' file
       ((or (derived-mode-p 'org-mode)
            (string= "org" ext))
        (info (org-texinfo-export-to-info)))
       ;; A `.md' file
       ((or (derived-mode-p 'markdown-mode)
            (string= "md" ext))
        (let ((org-file-name (concat (file-name-sans-extension (buffer-file-name)) ".org")))
          (apply #'call-process "pandoc" nil standard-output nil
                 `("-f" "markdown"
                   "-t" "org"
                   "-o" ,org-file-name
                   ,(buffer-file-name)))
          (with-current-buffer (find-file-noselect org-file-name)
            (info (org-texinfo-export-to-info)))))
       (t (user-error "Don't know how to convert `%s' to an `info' file"
                      (buffer-file-name)))))))

(global-set-key (kbd "C-x x v") 'view-text-file-as-info-manual)

View ‘NEWS’, ‘info’, ‘texi’, ‘org’ and ‘md’ files as `Info’ manual

1. Visit any Emacs NEWS file. For example, you can visit the Emacs 29.2 NEWS with C-u C-h n 29.2
2. Do M-x view-text-file-as-info-manual or press C-x x v
3. Now you are viewing the NEWS file as an Info manual

Above command in action

Emacs 30 ‘NEWS’^🔗 file in ‘outline’ format viewed as an ‘Info’ manual

‘EGLOT-NEWS’^🔗 in ‘outline’ format viewed as an ‘Info’ manual

A ‘markdown’ article^🔗 from `company-mode’ repo viewed as an ‘Info’ manual

About NEWS files in Emacs

Here is a list of NEWS files that comes with vanilla Emacs.^🔗

NEWS files for other “big” Emacs Packages

• CALC-NEWS
• EGLOT-NEWS
• ERC-NEWS
• MH-E-NEWS
• NXML-NEWS
• ORG-NEWS

NEWS file for core Emacs

• NEWS
• NEWS.1-17
• NEWS.18
• NEWS.19
• NEWS.20
• NEWS.21
• NEWS.22
• NEWS.23
• NEWS.24
• NEWS.25
• NEWS.26
• NEWS.27
• NEWS.28
• NEWS.29

You can generate the above list with M-x view-emacs-NEWS-files.

Elisp snippet for M-x view-emacs-NEWS-files

(defalias 'view-emacs-NEWS-files
  (kmacro "C-h n C-x C-j % m N E W S <return> t k"))

Conclusion

Above recipe for viewing NEWS file assumes that the NEWS file are in outline-mode and uses ‘*’ character for opening an heading.

Unless the NEWS file is a well-formed org file, it is possible that it has text segments that looks like LaTeX fragments, which org parser may deem as “malformed”. In that case, the org info export may fail. To workaround this failure, you may have to pre-process the NEWS file, and quote the problematic text segments with org‘s verbatim marker, the ‘=’ character. If you carefully look at the snippet that I shared in this article, you will notice that it does some pre-processing of the NEWS fileand strips the terminating full-stop—the . character—in outline headings; this is to work around a bug in the ox-texinfo exporter.

Try this snippet, and let me know what you find.