Re: When will emacs 27.1 be officially released?

[Tassilo Horn]

Eli Zaretskii <eliz@gnu.org> writes:

>> What would also be nice was a way to write something like
>> 
>>   @IncludeEmacsDefunDocs{my-function}{lisp/my.el}
>> 
>> which would be replaced by
>> 
>>   @defun my-function arg
>>   Docstring of my-function where ARG is replaced with @{arg}.
>>   @end defun
>> 
>> because at least in the Elisp manual, most function and variable
>> descriptions are (almost) identical to the corresponding docstrings
>> anyway.
>
> I think "most" and "almost identical" is inaccurate here.  IME, most
> of the descriptions in the manual are quite different from the doc
> strings.

It's an exaggeration for sure.  But I think we can settle on "they carry
the same information using different writing styles."  Well, for
commands the manual is usually much simpler relying on the fact that the
`interactive' spec guides the user through the proper usage.  But I'm
talking more about the technical Elisp manual.

> Doc strings have some limitations you need to observe: the first line
> has to be a complete sentence and should mention the arguments; the
> text should be short enough; there are some subtle rules for
> referencing symbols that shouldn't produce hyperlinks; etc.  Living
> with these limitations in the manual as well will produce suboptimal
> text, IMO.

I think the docstring rules aren't bad for the manual per-se and the
formatting rules can probably be transformed to equivalent texinfo
constructs.

> The (quite extreme, IMO) result of doing what you propose is the GNU
> Guile manual: the Guile build procedure "snarfs" the doc strings from
> the source code and produces 90% of the manual's text from them.  The
> result is not a very good manual, at least IMO.  Just compare it with
> the ELisp manual, and make your own conclusions about quality.

I didn't have a look yet but I didn't want to suggest that our manuals
be only collection of docstrings!  But at least in the more technical
documentation like the Elisp manual I see no big problem in embedding
them _while still_ surrounding them with prose and examples (as we
already do).

> And then there's the user manual, where the doc strings are definitely
> not the way to go, I hope you will agree.

Yes, I do.

>> BTW, I just looked at the docs and it seems that in large parts the
>> function descriptions in the manual read
>> 
>>   This function takes a @var{coin} and returns a @var{beer}.
>> 
>> (indicative) whereas the docstring reads
>> 
>>   Take a COIN and return a BEER.
>> 
>> (imperative).  I know the latter is our convention for function
>> docstrings.  Is the former our convention for documenting functions
>> in the manual?
>
> Yes.  Just one of those minor stylistic differences that make the
> manual a good reading, whereas the doc strings are terse and
> functional.

Agreed, but still work some might find unnecessary or burdensome.  I
mean, we're hackers no English linguists, frequently not even native
speakers. ;-)

And to make it clear: I'm actually in favor of a "no major change
without appropriate documentation" policy.  I'm just looking for
possibilities to make that easier.  For example, such a hypothetical
@IncludeEmacsDefunDocs thingy could also act the same way as a missing
+++ in NEWS where someone else could replace that placeholder later with
stylistically correct manual documentation.

Bye,
Tassilo