Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: address@hidden (Phillip Lord)
> Date: Fri, 12 Dec 2014 11:19:24 +0000
> Cc: address@hidden, address@hidden
> 
> I've always wondered, with the emacs doc about things like this...
> 
>  -- Function: current-buffer
>      This function returns the current buffer.
> 
>           (current-buffer)
>                ⇒ #<buffer buffers.texi>
> 
> 
> Now, this describes `current-buffer'. But the real documentation for
> this is here:
> 
> doc: /* Return the current buffer as a Lisp object.  */

There are 2 (sometimes more) "real documentations" for each Emacs
symbol.  You somehow assume there should be just one, but that's a
false assumption.

The documentation is worded differently in the manual and in the doc
string because it targets 2 different use cases: the latter is for
immediate references while using Emacs, the former is for learning
about Emacs.  Therefore, the manual can have longer and more detailed
descriptions, while the doc string needs to be concise and cut to the
cheese very quickly.

> How do you include docstring from a lisp function or var in texinfo?

What for?

> Go to the Emacs manual, and type "i", and "current-buffer". [No match].
> Which is strange, because there is documentation for current-buffer, in
> the elips manual.
> 
> So, the manuals already are isolated. The info index functionality is
> not really as rich as it seems.

Your conclusion is wrong.  We describe each symbol in the manual(s)
where they are relevant.  The variable current-buffer is not relevant
to Emacs users, unless they write Lisp code, in which case they should
look in the ELisp manual.

There's also a Help command to find the documentation no matter which
manual it is in: "C-h S".  This command allows to find the manual, any
manual, where some symbol is defined, and it in a way makes all the
manuals a single searchable database.  You can try it with
current-buffer, if you like.

There are also "C-h F" and "C-h K".  No similar command for variables
exists, but it could be added if deemed important.