bug#67615: Org-Mode story on how I gathered the list of Emacs-contained online-manuals

[Mekeor Melire]

2023-12-04 18:24 eliz@gnu.org:

> > From: Mekeor Melire <mekeor@posteo.de>
> > Date: Mon, 04 Dec 2023 15:51:32 +0000
> >
> > - Remove "gawk" and "mairix" manual-names from default value of
>
> Gawk and mairix are not parts of Emacs, they are separately-maintained
> programs.  So their manuals cannot be reached via the common base of
> the Emacs manuals, and therefore they should not be in that list,
> indeed.

For Gawk, my heuristics for gathering the list of manuals failed for an
unknown reason.

For mairix, it's "mairix" in
https://www.gnu.org/software/emacs/manual/mairix.html but "mairix-el" in
https://www.gnu.org/software/emacs/manual/html_node/mairix-el/index.html
but I don't know why. That's why my heuristics failed here too. But
yeah, "mairix-el" is the right one.

To ensure a complete list, I revisited my heuristics and wrote a little
story with Org Mode how I gathered the list of Emacs-included
online-manuals. Anyone who's really interested, can read the attachment.
:D

* Sources

Let's gather a list of Emacs-included manuals from different sources.

** Included of Guix-installed Emacs

Gather a list of manuals that an Guix-installed Emacs includes:

#+begin_src sh :results raw :wrap
for f in $(find $(guix package -I | grep emacs-next | cut -f 4)/share/info 
-type f); do
    basename $f | cut -d . -f 1
done | sort
#+end_src

#+NAME: from_guix
#+results:
#+begin_results
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results
rcirc
vtable
vhdl-mode
ses
ido
mh-e
ccmode
efaq
info
sieve
emacs-gnutls
mairix-el
calc
widget
message
transient
cl
forms
autotype
htmlfontify
elisp
pgg
ebrowse
wisent
auth
newsticker
pcl-cvs
erc
sc
org
nxml-mode
remember
ediff
vip
dired-x
bovine
emacs-mime
epa
edt
semantic
eshell
use-package
gnus
viper
ert
speedbar
srecode
eww
woman
idlwave
eudc
todo-mode
dbus
eieio
eintr
ede
eglot
modus-themes
octave-mode
url
flymake
smtpmail
emacs
sasl
reftex
tramp

** Mentioned on gnu.org

Gather a list of Emacs-included manuals by parsing 
https://www.gnu.org/software/emacs/manual/.

#+begin_src elisp
(string-join
  (sort
    (seq-map #'cadr
      (s-match-strings-all "href=\"\\([a-zA-Z0-9_-]+\\)\.html"
        (plz 'get "https://www.gnu.org/software/emacs/manual/";)))
    #'string<)
  "\n")
#+end_src

#+NAME: from_gnu_org
#+RESULTS:
#+begin_example
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_example

** Checked into emacs repository

Gather a list of Emacs-included manuals from Emacs' repository; from a local 
clone in particular.

#+begin_src sh :results raw :wrap
find ~/store/host/permanent/git/foreign/emacs/doc/misc/ -type f -iname '*.texi' 
-exec basename \{\} .texi \; | sort
#+end_src

#+NAME: from_repo
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
cc-mode
cl
dbus
dired-x
doclicense
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
gnus-faq
gpl
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
newsticker
nxml-mode
octave-mode
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
sem-user
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
trampver
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results

* Merge manual-lists from all sources

Merge all sources; make sure each manual-name is unique.

#+begin_src sh :var from_guix=from_guix :var from_gnu_org=from_gnu_org :var 
from_repo=from_repo :results raw :wrap
for m in $from_guix $from_gnu_org $from_repo; do
    echo $m
done | sort | uniq
#+end_src

#+NAME: merged
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
cc-mode
ccmode
cl
dbus
dired-x
doclicense
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
gnus-faq
gpl
htmlfontify
idlwave
ido
info
mairix
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
sem-user
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
trampver
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results

* Check online availability of each manual

** Filter manuals with "one page per node" online-manuals

#+begin_src sh :var manuals=merged :results raw :wrap
for m in $manuals; do
    if [ 200 = "$(curl -s -i 
https://www.gnu.org/software/emacs/manual/html_node/$m/index.html | head -n 1 | 
cut -d ' ' -f 2)" ]; then
        echo $m;
    fi
done
#+end_src

#+NAME: available_per_node
#+RESULTS:
#+begin_results
auth
autotype
bovine
calc
ccmode
cl
dbus
dired-x
ebrowse
ede
ediff
edt
efaq
efaq-w32
eglot
eieio
eintr
elisp
emacs
emacs-gnutls
emacs-mime
epa
erc
ert
eshell
eudc
eww
flymake
forms
gnus
htmlfontify
idlwave
ido
info
mairix-el
message
mh-e
modus-themes
newsticker
nxml-mode
octave-mode
org
pcl-cvs
pgg
rcirc
reftex
remember
sasl
sc
semantic
ses
sieve
smtpmail
speedbar
srecode
todo-mode
tramp
transient
url
use-package
vhdl-mode
vip
viper
vtable
widget
wisent
woman
#+end_results

** Filter manuals with "entirely on one page" online-manuals

Find out if there are manuals that do not have a "one page per node" 
online-manual, but have only a "entirely on one page" online-manual. It could 
be!

First, determine those manuals without "one page per node" online-manuals:

#+begin_src sh :var merged=merged :var available_per_node=available_per_node 
:results raw :wrap
for m in $merged $available_per_node; do echo $m; done | sort | uniq -c | grep 
' 1 ' | rev | cut -d ' ' -f 1 | rev
#+end_src

#+NAME: not_available_per_node
#+RESULTS:
#+begin_results
cc-mode
doclicense
gnus-faq
gpl
mairix
sem-user
trampver
#+end_results

Well, these manuals are known to not exist because of following reasons:

- cc-mode:    It's =cc-mode.texi= but =ccmode.info=: 
https://git.sv.gnu.org/cgit/emacs.git/tree/doc/misc/cc-mode.texi?h=88a6209a7f881b6cab5f1fd9761f1b8ae7cad6fa#n84
- doclicense: Only used via ~@include ....texi~
- gnus-faq:   Only used via ~@include ....texi~
- gpl:        Only used via ~@include ....texi~
- mairix:     It's "mairix" in 
https://www.gnu.org/software/emacs/manual/mairix.html but "mairix-el" in 
https://www.gnu.org/software/emacs/manual/html_node/mairix-el/index.html
- sem-user:   Only used via ~@include ....texi~
- trampver:   Only used via ~@include ....texi~

Thus, there is no (online-)manual for these texi-files, particularly no 
"entirely on one page" online-manual.

* Conclusion

See results named =available_per_node= for list of all Emacs-included online 
manuals.