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

[Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>]

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