Maintenance of *info* documentation of Emacs/Elisp

Maintenance of *info* documentation of Emacs/Elisp

[Greg Hill]

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?

Re: Maintenance of *info* documentation of Emacs/Elisp

[Emanuel Berg via Users list for the GNU Emacs text editor]

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

Re: Maintenance of *info* documentation of Emacs/Elisp

[Eli Zaretskii]

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

RE: Maintenance of *info* documentation of Emacs/Elisp

[Drew Adams]

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

Re: Maintenance of *info* documentation of Emacs/Elisp

[Greg Hill]

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

Re: Maintenance of *info* documentation of Emacs/Elisp

[Emanuel Berg via Users list for the GNU Emacs text editor]

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

RE: Maintenance of *info* documentation of Emacs/Elisp

[Drew Adams]

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

Re: Maintenance of *info* documentation of Emacs/Elisp

[Noam Postavsky]

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