Emacs GNU Texinfo Problems; Invalid HTML

By Xah Lee. Date:

The Texinfo software produces invalid HTML documents. The following gives some detail.

In around , i have created a HTML version of the GNU Emacs Lisp Reference Manual for my website, with corrections to the HTML and cleaned up CSS, so that the HTML are valid HTML documents and the CSS is handcrafted for better online presentation.

The version can be seen here: GNU Emacs Lisp Reference Manual. The story of my motivation is documented here (warning: rant): A Record of Frustration in IT Industry.

In the process of creating this cleaned up HTML version, there are several problems i found generated by the texinfo software outputing to HTML. Here's a summary. I hope others who want to convert GNU docs to valid HTML might benefit, or that texinfo developers might fix these problems.

Invalid HTML

Problems with texinfo generated HTML, with respect to HTML 4 transitional:

Problems with respect to HTML4 strict:

General HTML issues

Dead Links

In the elisp manual (one node per HTML page, roughly 850 HTML pages), there are 70 (local) links to other GNU documents. The local links are nice in that they provide cross-reference, but if one hosts only the elisp doc, all these local links will be dead.

Therefore, it would be nice, to have perhaps at texinfo level to embed markers to links that cross-ref to external docs, or perhaps at the HTML conversion level to provide a option to filter local links, so that local links can replaced as non-links (such as “See Emacs manual node on Abbrev”) or full http links to the right uri at gnu.org.

Vast majority of the 70 local links in the elisp doc are references to Emacs doc, but there are 6 that refers to widget, ses, cl, libc.

I presume that people who wishes to host GNU doc do not want to host the entire set of GNU's documentation.

Use of ASCII

Also, the texinfo still use the convention of backtick ` and straight single quote ' to emulate curly quotes “ ” or ‘ ’. It also use other ASCII kludge such as => instead of . The ability to display these chars has been widely available on commercial platforms since mid 1990s, and on Linuxes since about 2003 or so (emacs itself support Unicode to a practical degree since emacs 21, released in 2001). It is perhaps time to update GNU doc convention to utf8 and use the proper characters.

Emacs Modernization

  1. Simple Changes Emacs Should Adopt
  2. Why Emacs Keys are Painful
  3. Problems of the Scratch Buffer
  4. M-key Notation vs Alt+key Notation
  5. Menu Problem
  6. Mode Line Problem
  7. cua-mode Problems
  8. kill-buffer Induces Buffer Accumulation
  9. Emacs Form Feed ^L
  10. Inconsistency of Search Features
  11. Single Key to Delete Whole Line
  12. Emacs HTML Mode Sucks
  13. Emacs Does Not Support Viewing Images Files In Windows
  14. Emacs Spell Checker Problems
  15. Adopt HTML as Texinfo Replacement
  16. Support HTML Mail
  17. Problems of “man” Command
  18. Emacs Lisp Mode Syntax Coloring Problem
  19. Emacs Ahk Mode Problems
  20. Problems of Emacs's Manual
  21. Problems of Emacs's Manual; Examples
  22. Emacs: Have You Read Emacs Manual?
  23. Elisp: Ban Syntax Table
  24. Emacs: Make elisp-index-search use Current Symbol
  25. Emacs: Usability Problems of Mode Documentation
  26. Emacs GNU Texinfo Problems; Invalid HTML
  27. A Record of Frustration in IT Industry; Disappearing FSF URLs, 2006
  28. Emacs Manual Node Persistency Issues
  29. Emacs: dired-do-query-replace-regex Replace ALL (fixed)
  30. Problems of Emacs Supporting Obsolete Systems
  31. Elisp: Function to Copy/Delete a Dir Recursively (fixed)
  32. Thoughts on Common Lisp Scheme Lisp Based Emacs
  33. Text Editors Popularity and Market Research
  34. Text Editor's Cursor Movement Behavior (emacs, vi, Notepad++)
  35. GNU Emacs Development Inefficiency
  36. Emacs Dev Inefficiency and Emacs Web 2.0?
  37. Letter-Case Commands Usability Problems
  38. Emacs: Select Line, between Quotes, Extend Selection
  39. Emacs: isearch Current Word
  40. Suggestions on Line Wrap Commands
  41. Emacs: Single Key to Delete Whole Line
  42. Emacs Undo and Emacs Cult Problem

If you have a question, put $5 at patreon and message me.
Or Buy Xah Emacs Tutorial
Or buy a nice keyboard: Best Keyboards for Emacs


Emacs Lisp