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.
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.
I think your comment is interesting, and I do think the FSF at times held back Emacs development when it thought to be against their political aims. Having said that:
a) I think its good that in this day and age where everything is market driven (for better or for worse), someone is willing to take a position purely on ethical grounds. If nothing else because we need a plurality of approaches in order to find the "right" one. Also, note that RMS is no longer involved in Emacs development, AFAIK, and hasn't been for a while. He may pop in the mailing lists frequently, but his "word" does not have to be implemented.
b) the very large Emacs community does not share the political vision in its entirety and thus is not constrained by it. As a long term Emacs user, I have never seen Emacs developing at the fast and furious pace it has today. And this is both in terms of the external code (MELPA et al.) as well as the core itself, for which we must thank the current maintainer.
In fact, I'd even go further: almost all of the historical problems I've had with Emacs have been addressed with the current work already released or in branches - e.g., LSP, DAP, native compilation, tree-sitter... I do not think Emacs' progress has been held by the political views; and even my concerns with copyright assignment as a factor that slows down development have been comprehensively proven wrong by the speed at which Emacs is developing. I noted a great step-change in Emacs velocity over the last 5 years, and if anything it seems to be accelerating.
> 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.
Emacs has tons of new features in every release, and one of them, introduced some time back, was the ability to use binaries compiled natively as modules (not sure if it's the default already, it was behind `configure --with-modules` for some time). That was one of the things Stallman really didn't want to lose, ie. the inability to use proprietary code in Emacs. The only thing he managed to get is that the module has to define a constant saying that this_module_is_GPL (or similar). While it still expresses a political opinion, now it's more of "you're saying you're a good guy, we believe you" instead of "No binary blobs in Emacs! NEVERRRR!!"
Also, the new features in the last couple of releases were not user-facing, but very exciting. Starting from `lexical-binding:`, generators, threading, new modules for hashes, keyword and assoc lists, fast JSON support, native compilation, dynamic modules - Elisp is getting modernized, and fast. While the per-pixel scroll is not likely to be a priority, the team still works on things that would make implementing that scroll, in the PGTK branch. It's a continuation of the work to date: first moving rendering to Cairo, then text shaping to harfbuzz, then all the widgets and GUI handling to GTK.
> because he makes odious and repugnant remarks about all manner of subjects, he harasses women and holds disturbing views about bestiality and pedophilia.
No. I'm sorry, but no. I've read his so-called "odious and repugnant remarks" when I last heard this accusation. I read his microblog(? something like that), with tens of thousands of said remarks, starting I think in 2003.
There is nothing odious, much less repugnant. Nothing. It's not even that he worded any of these badly. He is precise, and his reasoning is sound. There were statements that I personally wouldn't endorse, but he is well within his rights to say them. Again: there is NOTHING substantially wrong in his writing. The problem is: it doesn't matter in the age of cancel culture... One tweet seems to have an almost divine ability to appear as a fact, even though it clearly isn't.
Yes, Stallman is politically on the very far left. He's a hippie. Like, he's old enough to actually be a hippie. His whole philosophy rests on the principle of not harming others. Unfortunately for him, he adds a few other controversial elements, like saying that as long as they don't hurt anyone, people are generally free to do whatever. This also means giving an "OK" for any kind of love as long as nobody is harmed, all parties agree to it, all parties are able to disagree, and so on. But well, the various conditions wouldn't fit into a tweet, so they get helpfully omitted to make space for the Real Problem(tm) - that he's a pedophile! You know what he said in reality, in this particular case? Just that the age of consent could be lower, given how human body develops. He later learned more about how children grow up, so he retracted his earlier statement, and changed it in accordance with the scientific knowledge he had learned.
Now, for people who consider the above "odious and repugnant", it was very different. First, how could he, in 2006 btw, publish a text saying that teenagers, actually, do have sex anyway, so maybe you should fix the law to reflect reality. How dare he! "He wants to rape children!". I don't even. Anyway, second, how can he say that an age difference between spouses doesn't matter? As long as nobody is harmed, etc, etc. It's obvious he prepares ground for creation of a harem of young lolis! Then, third, how dare he retract his statement! Saying that in the first place made him trash, so he should act like one and silently take a beating. And fourth, his changed statement STILL is immoral and against all that's good and holy! He just admitted that only older teenagers should be able to have sex legally - which happens to be quite a popular opinion among sexologists. Oh no! Now he wants harem of high-school cheerleaders!
Harassing women. That's actually a nice one. You see, Stallman used to randomly ask females if they want to have sex with him. It was ok to do in the 70s, and it was still more or less ok in the 80s, as long as you minded the context. He never reacted badly to a refusal. Look, he used to ask tens of women a year (I think, as a minimum), so if he minded the refusals, his heart would crumble! But, moving on, asking women out to have consensual sex with him became wrong at some point. He should have stopped, right? Unfortunately, he's very much anti-censorship. So, when this-or-that conference said he can't do it there, he asked women from the other side of a street. That wasn't the brightest idea, so he started giving out cards with the same question. Who, and why, would say that's 'harassment'? You can't even start to make him a "predator who uses his position to threaten women to have sex with him" because, let's face it, how many women even know about his position? He's got no money, an old laptop, and a parrot (I think). What kind of power did he have over the women? If there wasn't anything like that, then him and his partner in conversation are equal, so if one perceives something as harassment, they can act as they wish.
The last thing was his "defence of a rapist". I don't remember the names right now, but it was a big case some time ago. Anyway, he said that it's unfair to label as a rapist a person who asked and was granted consent, just because someone else, without the knowledge of the guy in question, coaxes/threatens the woman to secure that consent. He wrote that the girl in this case APPEARED entirely willing, so it shouldn't be called rape. Of course, the one who actually threatened the girl is a criminal here. But no, the news sites I read said that "Stallman says a victim of rape was willing!!!"
This is so absurd. The only reason he gets hit with shit like this is because he refuses to play the game. No Twitter, no Facebook, just mailing lists and simple static HTML pages. He's different. Yes, he has an ideological axe to grind, obviously - that's the whole reason he is different. But no, neither his ideology, nor his writings, nor his behavior - none of it is particularly controversial, and contrary to many of people accusing him, he admits his mistakes and corrects his words if he's convinced to do so. Convinced, you know, in a civilized dialogue, not by tweeting how he's a terrible person. I mean, if you want to talk to him, you need to have to get off of twitter - he won't read (or even know that it exists) your opinion stated there.
EDIT, forgot:
> This man, who seemingly hasn't the self-awareness to realize his behavior directly hurts the credibility of his cause,
Oh, but he's very much aware and he's doing it on purpose. People who's favorite pastime is condemning strangers on the Internet to social death, are not the ones he wants to convince (though he never refuses a chat) and have around. Reading what's been happening around Chris Avelone this year, I can't say I disagree with his stance on this much.
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.
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
But somebody has to write those Stackoverflow answers. Perhaps for those who do the distinction between man pages and info is important. Or do you think that the source of Stackoverflow answers is just more Stackoverflow answers? Now that would be hilarious.
I wouldn't even mind GNU documentation moving to TexInfo, but I have repeatedly found man pages telling me to invoke "info <some-command>" only to then find there was no texinfo documentation for that command. It's not a huge problem, but every now and then, it's annoying.
> 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.
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.
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 love/hate info. On one side, info can be more than a manual page, and contain _usable_ references. I suppose you know about the "all in one" manpage bundles such as ffmpeg-all and zshall which are there just so you can search?
Yeah..
On the other side, "info cp" didn't bring up the _reference_ of cp for a frickin' loooong time. It was a usability nightmare for that reason, and that reason alone. Had it worked the way it's working now: bringing you to the command reference first, but allow to search the entire manual scope at once (and WORKING references!), I would have been SOLD from the first moment.
The fixed-width format is the last thing I wished would be removed. I disabled catpath and have full-width manpages, but I cannot do the same with info as the text is pre-formatted.
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.
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.