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.
Can't say I agree about the styling, or aesthetics.
Single page text is easy to search, but it can yield irrelevant results. Hierarchical organization can be problematic, but it does give important clues to the organization of the content. Like a table of contents vs an index.
BTW, the site's search function seems to work pretty well.
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.
I always hated info pages because they were so dog slow (or felt that way) to navigate. So many clicks and often a page would have only a few paragraphs on it.
Maybe they are a better experience locally, but I never bothered to find out.
The patological fear that it appeared the info system had of ever producing a webpage with 200kb+ text on it, that I can search for and click links without delay essentially ruined the experience for me. Who cares if the download would take 5 seconds, when I would spend 20 minutes reading through it?
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!
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.
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).
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.
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.
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.
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.
[+] [-] casion|4 years ago|reply
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.
[+] [-] jonnycomputer|4 years ago|reply
Single page text is easy to search, but it can yield irrelevant results. Hierarchical organization can be problematic, but it does give important clues to the organization of the content. Like a table of contents vs an index.
BTW, the site's search function seems to work pretty well.
[+] [-] lelandfe|4 years ago|reply
If common web tropes are what some folks are used to learning with, all the better then!
[+] [-] distantsounds|4 years ago|reply
[+] [-] neilv|4 years ago|reply
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|4 years ago|reply
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.
[+] [-] tomjen3|4 years ago|reply
Maybe they are a better experience locally, but I never bothered to find out.
The patological fear that it appeared the info system had of ever producing a webpage with 200kb+ text on it, that I can search for and click links without delay essentially ruined the experience for me. Who cares if the download would take 5 seconds, when I would spend 20 minutes reading through it?
[+] [-] chlorion|4 years ago|reply
[+] [-] epolanski|4 years ago|reply
You can't even rely on web versions of package manuals because the most updated and relevant is always the one in your editor.
[+] [-] defanor|4 years ago|reply
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/
[+] [-] timonoko|4 years ago|reply
I would consider accepting Nobel-prize for this discovery.
[+] [-] timonoko|4 years ago|reply
[+] [-] nabilhat|4 years ago|reply
[+] [-] jonnycomputer|4 years ago|reply
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.
[+] [-] NeutralForest|4 years ago|reply
[+] [-] klibertp|4 years ago|reply
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.
[+] [-] rhdxmr|4 years ago|reply
[+] [-] jonnycomputer|4 years ago|reply
I just worry that the documentation won't be kept up to date. Also, its nice to have versioned documentation available.
[+] [-] eklitzke|4 years ago|reply
[+] [-] tvorog|4 years ago|reply
[+] [-] marco_craveiro|4 years ago|reply
[+] [-] p2t2p|4 years ago|reply
[+] [-] ossusermivami|4 years ago|reply
good work whoever did that