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

[David Kastrup]

Eli Zaretskii <address@hidden> writes:

>> From: address@hidden (Phillip Lord)
>> Date: Fri, 12 Dec 2014 14:50:00 +0000
>> Cc: address@hidden, Ludovic Courtès <address@hidden>,
>>      address@hidden
>> 
>> I don't want to put the docstring in. I want to put a reference to the
>> docstring.
>
> What for?  What problem would that solve?
>
>> I want to write "(current-buffer)" and have it evaled when the doc is
>> produced. This is the sort of thing that I expect when writing notes to
>> teach programming. Why would I not want it in Emacs?
>
> First, you _can_ do that in Emacs.  We have infrastructure and
> functions that return the doc strings.
>
> But for writing a manual, this is usually not the right thing to do.
> When you write a manual, you need to think differently than when you
> write a doc string, otherwise there will be little added value in the
> manual.
>
> Yes, I know about projects that generate Texinfo sources of their
> manuals from the doc strings.  But I consider those manuals of a lower
> quality than what we have in Emacs.

LilyPond does that in its reference appendices.  Of course, the
doc strings look Texinfoized in the source:

displayMusic =
#(define-music-function (parser location port music) ((output-port?) ly:music?)
   (_i "Display the internal representation of @var{music} to
@var{port}, default to the console.")
   (let ((port (or port (current-output-port))))
     (newline port)
     (display-scheme-music music port))
   music)

And are converted into
 @item @code{displayMusic} [music]  - @var{port} [output port] @var{music} 
(music)
@funindex displayMusic
Display the internal representation of @var{music} to
@var{port}, default to the console.

Basically, all LilyPond documentation strings are written in Texinfo.
Texinfo is lightweight enough not to make that annoying when you just
query the doc strings from Scheme.

-- 
David Kastrup