Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Emacs Docs The modern documentation website Emacs deserves

emacsdocs.org

Post reply on HN
Print view View original

21–30 of 39 posts

Re: Emacs Docs The modern documentation website Emacs deserves

#21

Post by krageon »

na85 wrote: post #7
distantsounds wrote: post #6

Earlier quoted context omitted.

trying out common web tropes with emacs is the only way to keep it relevant and on the front page of hackernews

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 w…

> the emacs developers seem uninterested in making emacs more appealing to new users

Given that there are new users, clearly they are succeeding in appealing to some of them. Perhaps they are just at peace with the fact that this isn't everyone and they are not worshipping at some keynesian growth altar.

Re: Emacs Docs The modern documentation website Emacs deserves

#22

Post by aulin »

taeric wrote: post #11
anyfoo wrote: post #5

Earlier quoted context omitted.

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…

This is hilarious in modern context. So much documentation is effectively "what stack overflow has" that worrying about "man versus info" feels like a distraction.

I'd say a bit sad more than hilarious, sad for modern times I mean... you have an easily accessible, curated, well-thought and organized doc base where you could learn a lot more other than solving your little problem at hand, but you still resort to subpar answers on a qa website

Re: Emacs Docs The modern documentation website Emacs deserves

#23

Post by jonnycomputer »

casion wrote: post #2

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…

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.

Re: Emacs Docs The modern documentation website Emacs deserves

#24

Post by jonnycomputer »

nabilhat wrote: post #8

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

Re: Emacs Docs The modern documentation website Emacs deserves

#25

Post by jonnycomputer »

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.

Re: Emacs Docs The modern documentation website Emacs deserves

#27

Post by mssdvd »

jonnycomputer wrote: post #24
nabilhat wrote: post #8

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

Have you tried Info-index? It's bound to i in info buffers.

Re: Emacs Docs The modern documentation website Emacs deserves

#28

Post by klibertp »

NeutralForest wrote: post #26

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.

Re: Emacs Docs The modern documentation website Emacs deserves

#29

Post by klibertp »

tomjen3 wrote: post #9
neilv wrote: post #3

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.

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 t…

Tip: open the "HTML single page" version: http://www.gnu.org/software/emacs/manual/html_mono/emacs.htm... and press Ctrl+F. Works really well.

(EDIT: it's 4.4MB instead of 200KB though)

Re: Emacs Docs The modern documentation website Emacs deserves

#30

Post by eklitzke »

jonnycomputer wrote: post #25

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.

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.
Post reply on HN