Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 06:12 PM, Eli Zaretskii wrote:

> Once you allow rephrasing, you already allow deviation.  And there
> really is no way around allowing it, because a manual that includes
> only the doc strings with a minimum "glue" is much less palatable.
> You can look at Guile as one example; GnuTLS is another.  Such manuals
> are much less useful, IME, than what we have in Emacs.

I'd rather minimize rephrasing in the manuals, while still allowing the 
"glue" text. Instead of having two ways to describe each important 
variable, I'd rather have just the docstrings, which could be adjusted 
to be more approachable. That would require some new Texinfo syntax to 
"insert the docstring here".

The narrative can still be free-form, but at least there would be one 
fewer source of duplication.

> One thing that you will never find in doc strings is a discussion of
> merits and demerits of different ways of solving some problem,
> especially if such a discussion requires to jump back and forth
> between these ways, in order to make some point.

The counterpart to "glue" text outside of the manuals is the Commentary 
section usually. While they're also terse usually (but not always), they 
aren't bound by the limitation that a docstring has to relate to a 
particular symbol.

> IOW, writing a good manual is still a human activity that cannot be
> easily automated.  Ideally, doc strings should be phrased like
> reference material, covering all the traits as tersely as possible,
> while the manual should provide an easier reading with more continuity
> text and even some explanations why things are the way they are.  At
> least IMO.

That sounds fine, and maybe this way is best for the more complex 
subjects, but in general I'd prefer to see docstrings also written with 
readability in mind. Then, when writing a manual section, you'll only 
need to write the "glue" text, and pick which symbol references, with 
docstrings, to add, and in which order.