7 ms·

Emacs Docs The modern documentation website Emacs deserves

218 points by ageofwant 5y ago

nabilhat 5y ago
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).
- jonnycomputer 5y ago
  I agree. I'm trying to train myself to use Emacs internal docs more, but I frequently resort to searches in Firefox. I use Emacs daily, but still don't find their Help format particularly intuitive, though it might help to use it more.
  - mssdvd 5y ago
    Have you tried Info-index? It's bound to i in info buffers.
casion 5y ago
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.
- lelandfe 5y ago
  > try out some common web tropes on the emac docs If common web tropes are what some folks are used to learning with, all the better then!
- distantsounds 5y ago
  trying out common web tropes with emacs is the only way to keep it relevant and on the front page of hackernews
  - na85 5y ago
    I use emacs daily, and I really like it. A major part of the problem is that Emacs development is completely captured by the, shall we say, esoteric personality of its original author. Emacs is a political project first and foremost—this much is clear. The focus is not on making the best possible text editor/programmable environment. In fact several proposed improvements have died on the drafting board because they would e.g. improve the experience of emacs users on OSX or Windows, and we can't have those users having a better UX than the people using emacs on underpowered Lemote netbooks with 10-inch screens running Trisquel without a GUI, now can we? So, yes, Emacs sacrifices betterment in the name of ethical purity, and that's fine. It's their codebase to do with what they will. But there is an enormous disconnect, because if emacs is a political project (and it is), then surely its goal must be to convert more people to their cause? To increase the size of their flock? Of course emacs' original author is also exactly the wrong person you want for that sort of task, because he makes odious and repugnant remarks about all manner of subjects, he harasses women and holds disturbing views about bestiality and pedophilia. This man, who seemingly hasn't the self-awareness to realize his behavior directly hurts the credibility of his cause, is who the FSF apparently wants as the banner man leading their cause, and to whose judgment on many issues the emacs developers defer. But I believe there is a sizable component of the emacs userbase that likes emacs as an editor but wishes someone would create the canonical/sanctioned fork of emacs that dispenses with all the gross Stallman stuff and focuses on just being a good editor, so that we can have mailing list discussions without worrying about what some gross creepy old man who hasn't written a line of code in 20 years and eats his toenails on live television thinks about per-pixel scrolling. Anyways, to circle back to the point, I believe it's this latter part of the community that submits things like TFA, because they genuinely believe that emacs (the software) is awesome but in need of some love, but the emacs developers seem uninterested in making emacs more appealing to new users so we end up with websites for documentation instead of new features.
neilv 5y ago
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.
- anyfoo 5y ago
  This made me remember something I haven't thought about in a long time: info (i.e. TexInfo) is great, but back in the 90s, there was a push in the GNU world to move from man pages to info entirely. Annoyingly, during that time lots of GNU man pages would tell you to look at its info pages instead. Me, and apparently others, were not thrilled. While info is technically superior, the "one page" format of a man page, at least to me, felt quicker and more convenient for quickly looking up something than info's hypertext. info might be better for dedicated reading of documentation (and I like using it in emacs for that), but perceived as less so when you quickly, say, want to look up a flag for ls. This might be for complicated human reasons or even just habit... e.g. you can still do full text search in info pages across all subpages, both with the "info" command and in emacs' info mode: just hit the 's' key. I'm not sure what the state today is, I can't remember when I was last pointed to info instead of man (and I think I dimly remember some announcement that this would stop). But I also largely moved more towards BSD derivates rather than Linux, so I can't be sure.
  - dmortin 5y ago
    > info might be better for dedicated reading of documentation (and I like using it in emacs for that), but perceived as less so when you quickly, say, want to look up a flag for ls. You can search and navigate with info very efficiently. In your case searching for 'flags' should quickly show the relevant info.
    - anyfoo 5y ago
      Yeah, I also mentioned how I wasn't sure how well founded that argument is. On the other hand, especially for man pages that are not huge, you can get a good grasp and overview by just scrolling linearly through the man page. At least for me, who tends to think very visually, I then have the impression I got a better feeling for the structure and covered content of the document than if it was hierarchical. (Again, this breaks down once the document gets too large.) Overall, that annoyed "oh gosh, I just wanted a quick scroll through the man page" feeling when encountering a man page that was just a stub for the info document probably comes from somewhere after all.
chlorion 5y ago
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!
- epolanski 5y ago
  I think that's a sign of incomplete Emacs proficiency though because self documentation is extremely important in Emacs world. You can't even rely on web versions of package manuals because the most updated and relevant is always the one in your editor.
tvorog 5y ago
I like it! Thank you! I think it would be very useful at least for newcomers.
rhdxmr 5y ago
I like this change. Modern documentation makes me feel Emacs community is still alive and evolving continuously. So I welcome this approach! Thanks,
defanor 5y ago
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/ https://www.gnu.org/software/emacs/
marco_craveiro 5y ago
Great work. I think newcomers will appreciate this.
p2t2p 5y ago
I wanted for some time to have wiki compiled into man pages or info files and have all of it locally.
jonnycomputer 5y ago
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.
- eklitzke 5y ago
  It looks to me like it's generated from the existing texinfo docs, so I don't think maintaining it will be a large burden.
NeutralForest 5y ago
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.
- klibertp 5y ago
  That's especially nice if you have helpful and help+ installed. The formatting is great, additional important things are displayed, like the source code of a function or a value of customization or list of maps the function is set and under what key. Give helpful a try, it's going to change how you interact with Emacs' help. Ah, also, info+ is nice, too. Both the Emacs manual and Elisp reference manual are available as info books, under C-h i. info+ adds syntax highlighting to code snippets, improves search and navigation, and supports bookmarks.
timonoko 5y ago
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.
- timonoko 5y ago
  Swipe-scroll: (global-set-key (kbd "<mouse-4>") 'scroll-down-line) (global-set-key (kbd "<mouse-5>") 'scroll-up-line)
ossusermivami 5y ago
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

218 points by ageofwant 5y ago

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).

jonnycomputer 5y ago
I agree. I'm trying to train myself to use Emacs internal docs more, but I frequently resort to searches in Firefox. I use Emacs daily, but still don't find their Help format particularly intuitive, though it might help to use it more.
- mssdvd 5y ago
  Have you tried Info-index? It's bound to i in info buffers.

casion 5y ago

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.

lelandfe 5y ago
> try out some common web tropes on the emac docs If common web tropes are what some folks are used to learning with, all the better then!
distantsounds 5y ago
trying out common web tropes with emacs is the only way to keep it relevant and on the front page of hackernews
- na85 5y ago
  I use emacs daily, and I really like it. A major part of the problem is that Emacs development is completely captured by the, shall we say, esoteric personality of its original author. Emacs is a political project first and foremost—this much is clear. The focus is not on making the best possible text editor/programmable environment. In fact several proposed improvements have died on the drafting board because they would e.g. improve the experience of emacs users on OSX or Windows, and we can't have those users having a better UX than the people using emacs on underpowered Lemote netbooks with 10-inch screens running Trisquel without a GUI, now can we? So, yes, Emacs sacrifices betterment in the name of ethical purity, and that's fine. It's their codebase to do with what they will. But there is an enormous disconnect, because if emacs is a political project (and it is), then surely its goal must be to convert more people to their cause? To increase the size of their flock? Of course emacs' original author is also exactly the wrong person you want for that sort of task, because he makes odious and repugnant remarks about all manner of subjects, he harasses women and holds disturbing views about bestiality and pedophilia. This man, who seemingly hasn't the self-awareness to realize his behavior directly hurts the credibility of his cause, is who the FSF apparently wants as the banner man leading their cause, and to whose judgment on many issues the emacs developers defer. But I believe there is a sizable component of the emacs userbase that likes emacs as an editor but wishes someone would create the canonical/sanctioned fork of emacs that dispenses with all the gross Stallman stuff and focuses on just being a good editor, so that we can have mailing list discussions without worrying about what some gross creepy old man who hasn't written a line of code in 20 years and eats his toenails on live television thinks about per-pixel scrolling. Anyways, to circle back to the point, I believe it's this latter part of the community that submits things like TFA, because they genuinely believe that emacs (the software) is awesome but in need of some love, but the emacs developers seem uninterested in making emacs more appealing to new users so we end up with websites for documentation instead of new features.

neilv 5y ago

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.

anyfoo 5y ago
This made me remember something I haven't thought about in a long time: info (i.e. TexInfo) is great, but back in the 90s, there was a push in the GNU world to move from man pages to info entirely. Annoyingly, during that time lots of GNU man pages would tell you to look at its info pages instead. Me, and apparently others, were not thrilled. While info is technically superior, the "one page" format of a man page, at least to me, felt quicker and more convenient for quickly looking up something than info's hypertext. info might be better for dedicated reading of documentation (and I like using it in emacs for that), but perceived as less so when you quickly, say, want to look up a flag for ls. This might be for complicated human reasons or even just habit... e.g. you can still do full text search in info pages across all subpages, both with the "info" command and in emacs' info mode: just hit the 's' key. I'm not sure what the state today is, I can't remember when I was last pointed to info instead of man (and I think I dimly remember some announcement that this would stop). But I also largely moved more towards BSD derivates rather than Linux, so I can't be sure.
- dmortin 5y ago
  > info might be better for dedicated reading of documentation (and I like using it in emacs for that), but perceived as less so when you quickly, say, want to look up a flag for ls. You can search and navigate with info very efficiently. In your case searching for 'flags' should quickly show the relevant info.
  - anyfoo 5y ago
    Yeah, I also mentioned how I wasn't sure how well founded that argument is. On the other hand, especially for man pages that are not huge, you can get a good grasp and overview by just scrolling linearly through the man page. At least for me, who tends to think very visually, I then have the impression I got a better feeling for the structure and covered content of the document than if it was hierarchical. (Again, this breaks down once the document gets too large.) Overall, that annoyed "oh gosh, I just wanted a quick scroll through the man page" feeling when encountering a man page that was just a stub for the info document probably comes from somewhere after all.

chlorion 5y ago

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!

epolanski 5y ago
I think that's a sign of incomplete Emacs proficiency though because self documentation is extremely important in Emacs world. You can't even rely on web versions of package manuals because the most updated and relevant is always the one in your editor.

tvorog 5y ago

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

rhdxmr 5y ago

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

defanor 5y ago

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/ https://www.gnu.org/software/emacs/

marco_craveiro 5y ago

Great work. I think newcomers will appreciate this.

p2t2p 5y ago

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

jonnycomputer 5y ago

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.

eklitzke 5y ago
It looks to me like it's generated from the existing texinfo docs, so I don't think maintaining it will be a large burden.

NeutralForest 5y ago

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.

klibertp 5y ago
That's especially nice if you have helpful and help+ installed. The formatting is great, additional important things are displayed, like the source code of a function or a value of customization or list of maps the function is set and under what key. Give helpful a try, it's going to change how you interact with Emacs' help. Ah, also, info+ is nice, too. Both the Emacs manual and Elisp reference manual are available as info books, under C-h i. info+ adds syntax highlighting to code snippets, improves search and navigation, and supports bookmarks.

timonoko 5y ago

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.

timonoko 5y ago
Swipe-scroll: (global-set-key (kbd "<mouse-4>") 'scroll-down-line) (global-set-key (kbd "<mouse-5>") 'scroll-up-line)

ossusermivami 5y ago

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