Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Tassilo Horn <tsdh@gnu.org>
> Cc: eggert@cs.ucla.edu,  liwei.ma@gmail.com,  emacs-devel@gnu.org,
>   kevin.legouguec@gmail.com
> Date: Fri, 03 Jul 2020 09:24:43 +0200
> 
> > 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.

The ELisp manual indeed carries the same information as the doc
strings, but it uses a very different style.

For example, the imperative style is IMO inappropriate for the manual
(think about reading the book), while the indicative style of the
manual wastes precious screen space if we'd use it in doc strings.

Moreover, the manual should (and does in many cases) intersperse
documentation with extended explanations of various aspects: the
rationale, the additional details, the relation to other functions or
variables, etc.

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

I suggest that you take a few doc strings and the corresponding manual
descriptions, and see how well your theory corresponds to practice.
IME, the differences are frequently significant, and cannot be
produced by programmatic text transformations.  But if I'm wrong, and
some significant amount of text can be produced in an automated way,
I'm of course for it.

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

If it works and makes the job easier for the contributors while still
keeping the documentation quality high enough, sure.