4 ms·
I saw somebody on Reddit describing reading the Emacs documentation as being forced to read an academic treatise… and I sympathise. I think thorough documentati
by kleiba 4y ago
I saw somebody on Reddit describing reading the Emacs documentation as being forced to read an academic treatise… and I sympathise. I think thorough documentation is important, but sometimes you don’t want to read about all the subtleties and edge cases, but just want a I HAVE A STRING HERE JUST FUCKING TELL ME WHAT TO DO WITH IT list of functions.
I couldn't disagree more.
I've done tons of Emacs lisp programming over the years, and IMO, the built-in documentation rocks. I find it at the exactly right level of detail for me: when programming, don't you want to know exactly about the edge-cases and subtleties?
Is it impossible to improve the documentation? Well, of course not. But as it stands, I find it pretty darn good.
Oh, and here's also a well-kept secret: if you have a string, and don't know what to do with it, besides C-h f there's also Google. Most likely, the best result will be a link back to the documentation, so together they cover a lot of ground: the doc has the infos, and Google helps with discoverability.
- krmboya 4y agoFor experts, a comprehensive manual is useful. For beginners, or people who occasionally dabble in elisp for some light customisation work, a whole treatise in elisp programming is probably an overkill
- gjadi 4y agoWell, that's why there is several documents: C-h i * Elisp: (elisp). The Emacs Lisp Reference Manual. * Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp * Emacs: (emacs). The extensible self-documenting text editor. * Emacs FAQ: (efaq). Frequently Asked Questions about Emacs. And that's not even looking at specialized documentation such as the one for Gnus, for Widget, for Dired-X, for Ediff, ... I agree with parent, Emacs documentation is some of the best I know and easily searchable.
- bhrgunatha 4y agoThe introspection via all the commands bound to C-h <key/s> is a major thing I miss from any other system. That includes the ability to view and debug the source code - including the base level commands written in C if you've configured it to do so. Plus, it's all right there _in emacs_ with all its facilities and your customisations while you're using it.
- veltas 4y agoIt's not about experts vs. beginners. Some people just don't like that style of documentation.
- karthink 4y ago> I HAVE A STRING HERE JUST FUCKING TELL ME WHAT TO DO WITH IT M-x shortdoc-display-group string
- KptMarchewa 4y agoReference vs documentation. First you need to find "shape" of thing that you're actually want to use in your current problem. Bunch of examples are the best aid here. If you find whatever you want, then it's time to understand all the subtleties.
- kleiba 4y agoBut isn't that exactly how Emacs' documentation is organized? For each topic, you get an entry page that gives an overview, followed by a more detailed API documentation.
- deleted 4y ago[deleted]
- veltas 4y agoIt's subjective. I am also a computer monk, but there are people out there who have irrational feelings about Real Documentation(TM), and ultimately they are worth accommodating.
- lopatin 4y agoI absolutely do not want to know about the edge cases and subtleties of my editor while I’m programming something else.
- kleiba 4y agoI know you mean that in a snarky way, but I just for clarity: we're talking about programming your editor here, i.e., writing code to extend Emacs' functionality, not using Emacs to write some unrelated program - which, of course, you probably do much more often, but then you don't need to look up the documentation we're talking about here.