* Maintenance of *info* documentation of Emacs/Elisp @ 2020-02-23 19:46 Greg Hill 2020-02-23 20:16 ` Emanuel Berg via Users list for the GNU Emacs text editor ` (2 more replies) 0 siblings, 3 replies; 8+ messages in thread From: Greg Hill @ 2020-02-23 19:46 UTC (permalink / raw) To: help-gnu-emacs I'm still relatively new to all of this, mostly learning from the all the *info* documentation and a lot of experimentation. Very often I find that the documentation could easily be made a lot more helpful to a beginner like me simply by adding one or two sentences to a discussion of a particular topic. After doing maybe an hour or so of additional poking around in other parts of the *info* documentation I eventually find a missing detail that could have made my life a lot easier and saved me a lot of time had it only been mentioned in the right place. So my question is, is there someone who is in charge of keeping the *info* documentation up to date, to whom I could make occasional suggestions about how it could be improved with just a little tweak, like by adding one sentence here or there? ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 19:46 Maintenance of *info* documentation of Emacs/Elisp Greg Hill @ 2020-02-23 20:16 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-23 20:18 ` Eli Zaretskii 2020-02-23 22:00 ` Drew Adams 2 siblings, 0 replies; 8+ messages in thread From: Emanuel Berg via Users list for the GNU Emacs text editor @ 2020-02-23 20:16 UTC (permalink / raw) To: help-gnu-emacs Greg Hill wrote: > After doing maybe an hour or so of additional > poking around in other parts of the *info* > documentation I eventually find a missing > detail that could have made my life a lot > easier and saved me a lot of time had it only > been mentioned in the right place. Well, that's always the case. And the/a challenge of writing documentation is not everyone is the same (thanks heaven), so the comment that is the eye opener for you, doesn't necessarily have the same effect on the next guy. So what one does is try to find the golden ratio that explains the most, to the most of people. > So my question is, is there someone who is in > charge of keeping the *info* documentation up > to date What you refer to as the *info* documentation isn't a homogeneous body of documentation. `info' is just a interface to a bunch of files that are written in the texinfo format. So for the Emacs FAQ, which you can get to like this: (info "efaq") you can find the texinfo source with this function: (defun info-find-source () (interactive) (let ((file (concat Info-current-file ".info"))) (if (file-exists-p file) (find-file-read-only file) (message "no file: %s (did you gunzip the info files?)" file) ))) ; [1] If you are apt with Emacs, but never quite got the hang of the *info* interface, it is often a good idea to just search the texinfo file. But to answer you question who to turn to, since a provider of software X will also provide its documentation, well, sometimes with a little help from their friends, but anyway, it is to the provider of the software you should turn with your suggestions as to how to improve the documentation. With Emacs, if you read the Elisp manual, you can just use `report-emacs-bug'. (It doesn't matter if it isn't a bug report, just a suggestion how to improve it.) Also, with Emacs in particular, I think you will be better helped by the built-in/on-line help system (on-line = not on paper). `C-h f' (`describe-function') to get the interface and documentation (the so called docstring) for a function, `C-h k' (`describe-key') for a key, and so on. You can try this now: `C-h k C-h k' Good luck! And ask more if it didn't make sense :) We can sure use people who are passionate about documentation... [1] https://dataswamp.org/~incal/emacs-init/my-info.el -- underground experts united http://user.it.uu.se/~embe8573 https://dataswamp.org/~incal ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 19:46 Maintenance of *info* documentation of Emacs/Elisp Greg Hill 2020-02-23 20:16 ` Emanuel Berg via Users list for the GNU Emacs text editor @ 2020-02-23 20:18 ` Eli Zaretskii 2020-02-23 22:00 ` Drew Adams 2 siblings, 0 replies; 8+ messages in thread From: Eli Zaretskii @ 2020-02-23 20:18 UTC (permalink / raw) To: help-gnu-emacs > From: Greg Hill <gregoryohill@gmail.com> > Date: Sun, 23 Feb 2020 11:46:30 -0800 > > So my question is, is there someone who is in charge of keeping the *info* > documentation up to date, to whom I could make occasional suggestions about > how it could be improved with just a little tweak, like by adding one > sentence here or there? Yes, those are the Emacs maintainers. Use "M-x report-emacs-bug RET" to report issues with the Emacs Info manuals, like you would to report any other issue or bug. Thanks. ^ permalink raw reply [flat|nested] 8+ messages in thread
* RE: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 19:46 Maintenance of *info* documentation of Emacs/Elisp Greg Hill 2020-02-23 20:16 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-23 20:18 ` Eli Zaretskii @ 2020-02-23 22:00 ` Drew Adams 2020-02-23 23:48 ` Greg Hill 2 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2020-02-23 22:00 UTC (permalink / raw) To: Greg Hill, help-gnu-emacs > is there someone who is in charge of keeping the *info* > documentation up to date, to whom I could make occasional suggestions about > how it could be improved with just a little tweak, like by adding one > sentence here or there? It's great that you have specific suggestions for improving Emacs doc. For any Emacs Info manual, use `M-x report-emacs-bug' to report a problem or to suggest an improvement. That will guide you through preparing and sending a reporting email to Emacs developers, who will take a look. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 22:00 ` Drew Adams @ 2020-02-23 23:48 ` Greg Hill 2020-02-24 0:58 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-24 0:59 ` Drew Adams 0 siblings, 2 replies; 8+ messages in thread From: Greg Hill @ 2020-02-23 23:48 UTC (permalink / raw) To: Drew Adams, help-gnu-emacs Thank you, Drew, but I tried reporting my problems with documentation like that as a "bug" first, got a reply from Steve Berman (actually we exchanged several emails, and he helped me out a lot with answers to a number of other non- "bug" questions I had while we were at it), and my understanding of what he told me about my suggestions re: improving the documentation was that he couldn't really help me with that, so I should probably take it to help-gnu-emacs. On Sun, Feb 23, 2020 at 2:02 PM Drew Adams <drew.adams@oracle.com> wrote: > > is there someone who is in charge of keeping the *info* > > documentation up to date, to whom I could make occasional suggestions > about > > how it could be improved with just a little tweak, like by adding one > > sentence here or there? > > It's great that you have specific suggestions for > improving Emacs doc. > > For any Emacs Info manual, use `M-x report-emacs-bug' > to report a problem or to suggest an improvement. > That will guide you through preparing and sending a > reporting email to Emacs developers, who will take a look. > > > ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 23:48 ` Greg Hill @ 2020-02-24 0:58 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-24 0:59 ` Drew Adams 1 sibling, 0 replies; 8+ messages in thread From: Emanuel Berg via Users list for the GNU Emacs text editor @ 2020-02-24 0:58 UTC (permalink / raw) To: help-gnu-emacs Greg Hill wrote: > Thank you, Drew, but I tried reporting my > problems with documentation like that as > a "bug" first, got a reply from Steve Berman > (actually we exchanged several emails, and he > helped me out a lot with answers to a number > of other non- "bug" questions I had while we > were at it), and my understanding of what he > told me about my suggestions re: improving > the documentation was that he couldn't really > help me with that, so I should probably take > it to help-gnu-emacs. The formally correct method to suggest a hands-on improvement to Emacs documentation is `report-emacs-bug', if you want to bring it up on a mailing list, while it is certainly not off topic here, probably it is better still to bring it up at gmane.emacs.devel/emacs-devel <emacs-devel@gnu.org> -- underground experts united http://user.it.uu.se/~embe8573 https://dataswamp.org/~incal ^ permalink raw reply [flat|nested] 8+ messages in thread
* RE: Maintenance of *info* documentation of Emacs/Elisp 2020-02-23 23:48 ` Greg Hill 2020-02-24 0:58 ` Emanuel Berg via Users list for the GNU Emacs text editor @ 2020-02-24 0:59 ` Drew Adams 2020-02-24 3:38 ` Noam Postavsky 1 sibling, 1 reply; 8+ messages in thread From: Drew Adams @ 2020-02-24 0:59 UTC (permalink / raw) To: Greg Hill, help-gnu-emacs > Thank you, Drew, but I tried reporting my problems with documentation like that as a "bug" first, got a reply from Steve Berman (actually we exchanged several emails, and he helped me out a lot with answers to a number of other non- "bug" questions I had while we were at it), and my understanding of what he told me about my suggestions re: improving the documentation was that he couldn't really help me with that, so I should probably take it to help-gnu-emacs. Perhaps you misunderstood. Or perhaps Steve meant that _he_ couldn't help with that. But that doesn't mean that someone else can't. Is the bug you filed closed? If not then you can hope that someone will see it, agree about the problem, and have the time and will to fix it. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Maintenance of *info* documentation of Emacs/Elisp 2020-02-24 0:59 ` Drew Adams @ 2020-02-24 3:38 ` Noam Postavsky 0 siblings, 0 replies; 8+ messages in thread From: Noam Postavsky @ 2020-02-24 3:38 UTC (permalink / raw) To: Drew Adams; +Cc: Help Gnu Emacs mailing list, Greg Hill On Sun, 23 Feb 2020 at 20:00, Drew Adams <drew.adams@oracle.com> wrote: > > > Thank you, Drew, but I tried reporting my problems with documentation like that as a "bug" first, got a reply from Steve Berman (actually we exchanged several emails, and he helped me out a lot with answers to a number of other non- "bug" questions I had while we were at it), and my understanding of what he told me about my suggestions re: improving the documentation was that he couldn't really help me with that, so I should probably take it to help-gnu-emacs. > > Perhaps you misunderstood. Or perhaps Steve meant that _he_ couldn't help with that. But that doesn't mean that someone else can't. > > Is the bug you filed closed? If not then you can hope that someone will see it, agree about the problem, and have the time and will to fix it. It seems to be #39624 which is currently closed, but most of the discussion happened off-list. I'm sure concrete suggestions for improving the docs would be welcome there though. https://debbugs.gnu.org/39624 ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-02-24 3:38 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-02-23 19:46 Maintenance of *info* documentation of Emacs/Elisp Greg Hill 2020-02-23 20:16 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-23 20:18 ` Eli Zaretskii 2020-02-23 22:00 ` Drew Adams 2020-02-23 23:48 ` Greg Hill 2020-02-24 0:58 ` Emanuel Berg via Users list for the GNU Emacs text editor 2020-02-24 0:59 ` Drew Adams 2020-02-24 3:38 ` Noam Postavsky
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).