from Hacker News

Emacs Docs The modern documentation website Emacs deserves

by ageofwant on 11/30/21, 12:45 AM with 38 comments

• by casion on 11/30/21, 3:12 AM

  I greatly appreciate efforts like these, however I don't understand the value here.

  From my perspective:

  - More difficult to search (single page manual is easy to ctrl-f, emacs built-in docs same)

  - Difficult to read, styling plugins don't work well.

  - MUCH more text on the screen at once. A single horizontal line is at least 2 separate contexts.

  - Menu animations :(

  - various styling errors (code blocks overlapping in safari for me)

  - code copy also copies repl output... not very useful!

  - font stylings reused but for different meanings

  etc...

  It feels like an interesting pet-project, but it doesn't feel like someone sat down and thought of a prioritized list of problems with the original documentation presentation... then fixed them.

  It feels like someone wanted to try out some common web tropes on the emac docs.

• by neilv on 11/30/21, 3:37 AM

  Any Emacs user who hasn't tried the Info documentation mode, and learned a few keys for navigating in it, might want to try.

  It's ancient (Emacs had hypertext way before the Web existed), but, for some purposes, it can be much more efficient than anything in a Web browser.

• by chlorion on 11/30/21, 6:20 AM

  I personally have a much easier time reading and digesting documentation in this format than the normal format that is presented from inside of Emacs, so this is really nice for me. Thanks for working on this!

• by defanor on 11/30/21, 8:46 AM

  Apparently I'm not the target audience, being rather happy with the Emacs info viewer and the texinfo-generated HTML, but I noticed that some sections aren't clickable, possibly requiring JS (but not mentioning it); apparently it's the ones with ">", but that is not visible when global CSS is used (disabling background images, among other things). Search doesn't work (at least without JS) either. Perhaps it should degrade more gracefully.

  But generally looks like a potentially useful addition to other documentation output formats: they are supposed to be usable with different setups and under different conditions, and covering different preferences seems useful too. Even the Emacs web page [1] is in that "modern" style now, after all.

  [1] https://www.gnu.org/software/emacs/

• by timonoko on 11/30/21, 2:52 PM

  Not related, but browsing through this, I suddenly realized how to use termux-emacs with touchscreen.

      (xterm-mouse-mode 1)
  

  No special keyboard layout with arrow keys anymore. No pecking character-per-character those tiny keys.

  I would consider accepting Nobel-prize for this discovery.

• by nabilhat on 11/30/21, 5:32 AM

  Should "Will it open in vanilla emacs / eww without exploding" be a criticism of emacs documentation? There doesn't seem to be a shortage of emacs documentation that's more or less inaccessible from within emacs (of course, that varying depending on one's level of stubborness).

• by NeutralForest on 11/30/21, 1:32 PM

  I think having more ways to present the docs is excellent. I usually just C-h [k|v|f] nowadays or look at the bare HTML docs but alternatives are most welcome.

• by rhdxmr on 11/30/21, 8:27 AM

  I like this change. Modern documentation makes me feel Emacs community is still alive and evolving continuously. So I welcome this approach! Thanks,

• by jonnycomputer on 11/30/21, 1:16 PM

  Funnily enough my greatest concern with this project isn't that it requires JS, or the aesthetics, or the menu animations, or any of the small UI problems.

  I just worry that the documentation won't be kept up to date. Also, its nice to have versioned documentation available.

• by tvorog on 11/30/21, 7:36 AM

  I like it! Thank you! I think it would be very useful at least for newcomers.

• by marco_craveiro on 11/30/21, 9:55 AM

  Great work. I think newcomers will appreciate this.

• by p2t2p on 11/30/21, 10:24 AM

  I wanted for some time to have wiki compiled into man pages or info files and have all of it locally.

• by ossusermivami on 12/1/21, 8:44 AM

  i am old emacs user, ~25 year old experience, and will be using this.. I find it more clear than reading thru this than "C-h i"

  good work whoever did that