Adding examples in the doc (was: Some ideas with Emacs)

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> AFACT, currently we have some examples in the Elisp manual and very
>> few examples in docstrings.
>> It might be a good idea to encourage the addition of examples either in
>> docstrings or in the Elisp manual (or both).
> Personally, I don't like docstring to be too verbose.

I tend to agree.  Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's also simply
the impact on the visual distance between the function header and the code.

Another issue w.r.t examples is that editing Elisp code within
docstrings is a PITA (you don't get the usual
completion/indentation/... plus you have to be careful with escaping
' and friends so they don't get "shaped").

Also, docstrings have no formal structure and usually contain text, so
if we want to add examples in docstrings, I would prefer we first design
a structure to clearly distinguish text from code so we can render it
more elegantly.

Maybe examples should simply live *outside* of the function definition,
e.g. with

    (defexamples ...)

This might also have the benefit of being able to associate an example
with several functions (when the example shows how to combine calls to
various functions to get a particular result).

> Usually, when a function is documented with both docstrings and
> a manual, I prefer to put the examples in the manual.

I find code in texi files to be less convenient to edit/use.


        Stefan