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

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

[Drew Adams]

IIUC, it is make-docfile.c that adds the "(fn ..)" to a doc string, which
causes the displayed documentation to show the function's signature.

A while ago, I asked that this printed signature be wrapped. My motivation
was that a very long line can throw off window-fitting and frame-fitting
that might measure the longest line length, resulting in, say, wasted frame
space.

This was fixed - thanks.

However, I also recuperate doc strings using function `documentation' and
present them as completion candidates, and in this case the signature is
still one long line.

I would like the filling to be done at the point where the (fn...) is
generated, not just when it is displayed by `C-h f'. The entire doc string
is correctly within reasonable width limits, except for this one line, which
can get way out of hand.

Here, for instance is the (fn...) line for function `quail-define-package'
(the mailer will fill it, but imagine it unfilled):

(quail-define-package name language title &optional guidance docstring
translation-keys forget-last-selection deterministic kbd-translate
show-layout create-decode-map maximum-shortest overlay-plist
update-translation-function conversion-keys simple)

That's a line length of 250 characters!

AFAIK, the only purpose of this signature string is for documentation, that
is, for contexts in which a normal line length is expected. The fact that it
can be essentially limitless is, to me, a bug - it doesn't fit its use in a
doc string.

Could this please be fixed, so that functions such as `documentation' and
`documentation-property' return a doc string that has reasonable-length
lines? Thanks.

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

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> Could this please be fixed, so that functions such as `documentation' and
> `documentation-property' return a doc string that has reasonable-length
> lines? Thanks.

Why don't you just wrap them yourself, in the code that calls
`documentation'?  Wrapping is, in general, a display thing, so it seems
best to not add hair in more primitive code to worry about it.

-Miles

-- 
97% of everything is grunge

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

[Drew Adams]

> > Could this please be fixed, so that functions such as
> > `documentation' and `documentation-property' return a
> > doc string that has reasonable-length lines? Thanks.
>
> Why don't you just wrap them yourself, in the code that calls
> `documentation'?  Wrapping is, in general, a display thing, so it seems
> best to not add hair in more primitive code to worry about it.

1. It's not so easy in my particular context. But this is not about me. It's
about any code that uses doc strings (and cares about line length). Why
change all such code, instead of preventing the bug in the first place? Code
that generates user doc should be smart enough to respect the GNU Emacs
convention for line length. What's the big deal?

2. Pretty much all other lines of every doc string are correct in this
regard. Why should this be the lone exception and force all code that uses
doc-strings to patch things up after the fact? An ounce of prevention is
worth a pound of cure.

3. We have already added code to the `describe-*' commands to fix this at
their end. Fixing the problem where this text is automatically added to the
doc string, instead, will fix it for any and all code that uses doc strings,
present and future. And the band-aid code can then be removed from the help
functions, where it never really belonged anyway.

Doc strings are important, general constructs; they are not only for this or
that already existing `describe-*' command (or apropos command or...). That
was the wrong place to fix the problem, but it took me a while to discover
that.

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

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>> Why don't you just wrap them yourself, in the code that calls
>> `documentation'?  Wrapping is, in general, a display thing, so it seems
>> best to not add hair in more primitive code to worry about it.
>
> 1. It's not so easy in my particular context. But this is not about me. It's
> about any code that uses doc strings (and cares about line length). Why
> change all such code, instead of preventing the bug in the first place? Code
> that generates user doc should be smart enough to respect the GNU Emacs
> convention for line length. What's the big deal?

Why do you assume that applications _want_ it wrapped?  It's really not
part of the doc string as such, it's an interface description.  Wrapping
it simply introduces extra noise.

> 2. Pretty much all other lines of every doc string are correct in this
> regard. Why should this be the lone exception and force all code that uses
> doc-strings to patch things up after the fact?

See above.

-Miles

-- 
The car has become... an article of dress without which we feel uncertain,
unclad, and incomplete.  [Marshall McLuhan, Understanding Media, 1964]

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

[Drew Adams]

> >> Why don't you just wrap them yourself, in the code that calls
> >> `documentation'?  Wrapping is, in general, a display thing, so it
> >> seems best to not add hair in more primitive code to worry about it.
> >
> > Why change all such code, instead of preventing the bug in the
> > first place? Code that generates user doc should be smart
> > enough to respect the GNU Emacs convention for line length.
> > What's the big deal?
>
> Why do you assume that applications _want_ it wrapped?

It's a doc string. All lines in a doc string follow a convention, including
being within a max length. Why should this be the only exception?

> It's really not part of the doc string as such, it's an interface
> description.

That's a good feint. This part of the doc string isn't right, so to fix
things we'll just say it's not part of the doc string.

I don't agree. It is served up with `documentation' - there is no way around
that, except to try to parse the doc string after retrieval to remove that
part.

If it is not part of the doc string, then leave it out of `documentation',
and have a separate function to retrieve only the interface spec.

> Wrapping it simply introduces extra noise.

Needing to wrap it in multiple places (`describe-*',...) instead of one
because it was not written correctly in the first place introduces far more
noise.

> > 2. Pretty much all other lines of every doc string are correct in this
> > regard. Why should this be the lone exception and force all
> > code that uses doc-strings to patch things up after the fact?
>
> See above.

Oh, you mean where you simply declare it not to be part of the doc string?

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

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>> It's really not part of the doc string as such, it's an interface
>> description.
>
> That's a good feint. This part of the doc string isn't right, so to fix
> things we'll just say it's not part of the doc string.

No, it was always intended as a function signature, not a text string
for display.  It's put into the _raw_ docstring because that's a
convenient place to put it, but it is intended that this be filtered
appropriately for display.

> Oh, you mean where you simply declare it not to be part of the doc string?

No, the part where I tell you how things have been designed.

-Miles

-- 
`To alcohol!  The cause of, and solution to,
 all of life's problems' --Homer J. Simpson

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

[Drew Adams]

> >> It's really not part of the doc string as such, it's an interface
> >> description.
> >
> > That's a good feint. This part of the doc string isn't right, so to fix
> > things we'll just say it's not part of the doc string.
>
> No, it was always intended as a function signature, not a text string
> for display.  It's put into the _raw_ docstring because that's a
> convenient place to put it, but it is intended that this be filtered
> appropriately for display.

If the signature text is not intended as part of the doc string, then it and
the doc string should each be available separately, not joined at the hip
from birth. Function `documentation' (or some other function) should return
only the doc string per se, and some other function (e.g. `signature')
should return the signature (interface spec).

In my use of it, I display a buffer which includes function names and doc
strings of functions that match an input regexp. It can thus include all
defined functions. That's between 8000 and 9000 doc strings at the start of
an Emacs session, in my environment at least. I fit the buffer's frame
automatically, which takes into account the longest line (250 chars - from a
signature).

You can change your input regexp on the fly, and the matching function names
and doc strings are updated (and the frame is refit). It would be
unreasonable to examine each matching doc string, try to determine whether
it in fact contained a (fn...) signature, and, if so, fill that signature.
Unreasonable in terms of performance and, I maintain, unreasonable in terms
of Emacs design.

Currently, AFAIK, the only function I have available to retrieve the doc
string is `documentation', and that currently includes the problematic line
that you are saying should not be considered to be part of the doc string.
Practically speaking, it *is* part of the doc string (it is included by
`documentation'), but OK, it shouldn't be.

If you want to maintain the independence of the signature from the doc
string, fine. But in that case, please do it right - provide a separate
function that will retrieve only the doc string.

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

[Richard Stallman]

    I would like the filling to be done at the point where the (fn...) is
    generated, not just when it is displayed by `C-h f'.

It is better, more general, the way it is.

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

[Drew Adams]

>     I would like the filling to be done at the point where the (fn...) is
>     generated, not just when it is displayed by `C-h f'.
>
> It is better, more general, the way it is.

How is it more general? Why is it better?

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?

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

[Thien-Thi Nguyen]

() "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

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

[Drew Adams]

>    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.
>
> 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.

Fair enough. 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).

> 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.

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".

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.

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).

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

[Thien-Thi Nguyen]

() "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

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

[Drew Adams]

>    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?

I see, thank you. `help-split-fundoc' was apparently added in Emacs 22. I
can use that. I did not find any "others", but that one seems to work OK.

It's not foolproof (just matches "(fn ...)"), but if it's good enough for
`describe-function' then I guess it's good enough for me.

It makes the distinction you speak of only after the fact, however - it digs
out the signature (fn ...) after it was already embedded in the doc string.
I still say that it would be better to keep them separate and then put them
together when needed, instead of having to parse the combination like that.

And no, a string is not a good representation of a data structure with two
components. I agree that it can be better to have a single data structure
for this, with two components (doc and signature), but a string is not a
good choice for such a structure.

Oh well, sometimes Moh must go to the Mountain. In any case, thank you for
pointing me toward `help-split-fundoc'. I wasn't aware of it.

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

[Thien-Thi Nguyen]

() "Drew Adams" <drew.adams@oracle.com>
() Sat, 29 Dec 2007 16:04:22 -0800

   It makes the distinction you speak of only after the fact,

it makes the distinction at the time the distinction matters.

   And no, a string is not a good representation of a data
   structure with two components. I agree that it can be better to
   have a single data structure for this, with two components (doc
   and signature), but a string is not a good choice for such a
   structure.

we have text and we have other objects inside emacs.  outside of
emacs, we don't have other objects (at least, not in the same way
as inside emacs).  simulating them w/ text is the next best thing
when crossing the boundary.

   `help-split-fundoc'. I wasn't aware of it.

me neither.  i'm glad you found it's name.

thi

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

[Richard Stallman]

    >     I would like the filling to be done at the point where the (fn...) is
    >     generated, not just when it is displayed by `C-h f'.
    >
    > It is better, more general, the way it is.

    How is it more general? Why is it better?

It is better to have the raw data in a simpler and more regular
format.  If you want to fill that line, you can do so.  You can also
NOT fill it.

That is my decision, so please let's end this discussion.