Re: (fn ...) - please fill it at the point of generation

[Thien-Thi Nguyen <ttn@gnuvola.org>]

() "Drew Adams" <drew.adams@oracle.com>
() Sat, 29 Dec 2007 10:14:57 -0800

   If that is the intention, then, yes, it should be not only
   semantically but also practically distinguished from the rest
   of the string (which is presentation-ready). IOW, we should
   have separate retrieval functions for the doc string per se and
   the interface spec (signature).

what you seek has been done, just not where you seek it.  the
function `documentation' is called by others that make this
distinction.  why don't you look at using those, instead?  are
they deficient in some way?  if they are not, will changing
`documentation' behavior make them so?  will you fix those bugs
then?

i think if you let go of the desire to have `documentation' work
like these other functions, you may find the other functions
readily suitable for your needs.

   The only way currently to recuperate the doc string gives you
   all of it, including the part you consider not to be part of
   the doc string but "markup".

i don't see that as a problem.  the required treatment of that
string, to separate the parts, is not onerous.  if it feels
onerous, no worries, see my point above.

   If that last line (interface spec) is not part of the doc
   string, and you want to keep it unfilled because filling is
   presentation, then `documentation' (or some other function)
   should return only the doc string per se, not the whole kit and
   caboodle. Especially since `documentation' is written in C, so
   it can't be hacked without rebuilding Emacs.

you seek to change code, but what is better is to change your view
of the data that the code returns.  since the data is regular, any
wrangling required to fit it to your requirements can be purely
additive.  isn't that tantalizing enough for you?

   IOW, either the "interface spec" is part of the doc string or
   it is not. If it is, then it too should be presentation-ready,
   like the rest of the string. If it is not, then we should have
   a separate function that gives us only the doc string (without
   interface spec).

i see many SHOULD in your argument, but i don't understand why.
here are two perlis quotes that are relevant:

 If a program manipulates a large amount of data,
 it does so in a small number of ways.
 			-- Alan Perlis
 
 It is better to have 100 functions operate on one data
 structure than 10 functions on 10 data structures.
 			-- Alan Perlis

i'm afraid i cannot communicate the elegance of the current
system, but only my fear that you are proposing to wreak it.

thi