info sucks

The .info format produced by GNU Texinfo kinda sucks. The info reader built into emacs is certainly the best way to view these files, but I find myself using the html produced by texinfo far more often than the info files.

The main reasons are that:

• I want proportional fonts for actual text, but apparently this is impossible.
• Info nodes are typically at a finer granularity than I want in a buffer.
  • I don’t want to have to remember the keybindings to page through a bunch of nodes in some hierarchy to quickly skim for what I’m looking for.
  • I already know how to efficiently navigate a buffer in emacs, and would much rather use my setup than info’s.
  • I want imenu and consult-* to actually be useful across a whole info manual.
  • Yes I know about info+ and this answer, but neither seem to preserve formatting very well.
• I want the same visual richness and better formatting that the html versions have.
  • See for example this section in the guix manual where the note has a nice red side bar.
  • Italicized words in the html format are quoted in the info format.
  • Monospaced code in the html format are fixed-pitch serif in the info format.
  • IMHO the worst of these issues is that emphasized words in the html format just goes to underscores in the info format.

I think it would be great if gnu projects adopted org markup for documentation instead. It’s been discussed enough times over the years that I have doubts if it’ll ever happen at this point unfortunately.

At this point I use eww to view the full html version of texinfo docs, but it’s not efficient and chokes on larger manuals like the elisp manual. Also the html versions of texinfo docs aren’t built or installed by default.

Here’s the start at my attempt to define some helper code to allow me to get the html docs installed on guix.

(use-modules (guix packages))
(use-modules (gnu packages texinfo))

(define (package-html-docs p)
  (package
    (inherit p)
    (name (string-append (package-name p) "-html-doc"))
    (inputs (modify-inputs (package-native-inputs p)
              (prepend texinfo)))
    (arguments
     '(#:phases (modify-phases %standard-phases
                  (delete 'build)
                  (delete 'check)
                  (delete 'patch-shebangs)
                  (delete 'strip)
                  (delete 'validate-runpath)
                  (delete 'validate-documentation-location)
                  (delete 'delete-info-dir-file)
                  (delete 'patch-dot-desktop-files)
                  (delete 'make-dynamic-linker-cache)
                  (delete 'install-license-files)
                  (delete 'reset-gzip-timestamps)
                  (delete 'compress-documentation)
                  (replace 'install 
                    (lambda* (#:key (make-flags '()) #:allow-other-keys)
                      (apply invoke "make" "install-html" make-flags))))))))

(package-html-docs hello)