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

[Phillip Lord]

Richard Stallman <address@hidden> writes:
>   > I meant as a pointer. So
>
>   >     @defdocstring{current-buffer}
>
>   > would appear as 
>
>   >     Return the current buffer as a Lisp object.
>
>   > In the output format.
>
> There are two reasons we don't want to do this.
>
> 1. We want the manual text to be specified in the manual sources,
> not referred to some other file.
>
> 2. The text that makes a good doc string is not good for the manual.
>
> A feature to facilitate using the same text for both is inherently not
> a good idea.

It's probably worth looking at dash.el. The definition of -map for
instance looks like this:


-map (fn list)

Return a new list consisting of the result of applying fn to the items in list.

(-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
(-map 'square '(1 2 3 4)) ;; => '(1 4 9 16)
(--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)


After the definition there are some useful examples, which you can look
at if you do not understand the definition. And, here is the nice
thing -- these examples are actually generated from the test cases; if
the -map does not work in the way that these examples suggest the tests
will fail.

There are quite a few places where the text in the emacs manual is
similar to the docstrings. So a more programmatic documentation format
is worth thinking about.

Phil