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 07:53:36 -0800

   What's the advantage of having one line in a doc string
   that doesn't fit the doc-string pattern (convention)?
   How is that more general and less of a special case?

"one line" to munge is more general than "one form".  put
another way: more tools know how to parse the former than
the latter.  we want to be nice to tools (for now; one
hopes some day they will reciprocate the kindness :--).

the "docstring pattern (convention)" is applicable for
viewing the docstring.  although the part under discussion
is technically included in the "string", it should be
semantically distinguished from the rest of the string
because it is not intended for direct viewing.

that part is markup, requiring further processing at the
presentation stage.  to conflate the presentation and the
generation is a step towards bad design.  a good middle
path would be to pool common presentation methods, as long
as those methods are not imposed on the phases uninvolved
w/ presentation.

keep the phase sep, bro!

thi