Lisp primitive doc strings

[Steve Youngs <steve@xxxxxxxxxxx>]

Recognise this...

,----
| DEFUN("invocation-name", Finvocation_name, 0, 0, 0, /*
| Return the program name that was used to run SXEmacs.
| Any directory names are omitted.
|                                                      */
|       ())
| {
|       return Fcopy_sequence(Vinvocation_name);
| }
`----

...not the function itself, but how it is constructed.  That C comment
becomes the doc string for the lisp function `invocation-name'.
Before I get to the couple of issues I'm really writing about, I was
wondering if anyone had any ideas up their sleeves about it?

You see, I think it's a little on the "evil hack" side of things and
was thinking maybe we could use some other method in the C code?  But
I suppose having it as a comment means that it really isn't in the
code once the compiler is finished with it.  But if anyone does have
any ideas, I'd love to hear them.

Anyway, back to what I wanted to talk about.

Sadly, my wonderful idea of running indent(1) over the C code to save
time in re-indenting seems to be causing a few problems.  Most
notably, these bloody comment/doc strings.

That example DEFUN above is how it looks _after_ I had manually fixed
the indent(1) fuckerage.  After indent it looked like...

DEFUN("invocation-name", Finvocation_name, 0, 0, 0, /*
                                                      Return the program name 
that was used to run SXEmacs.
                                                      Any directory names are 
omitted.
                                                     */
      ())
{
        return Fcopy_sequence(Vinvocation_name);
}

And doing `C-h f invocation-name' dutifully reproduced all that
leading whitespace in the describe-function buffer.  I couldn't think
of a safe way to fix it automatically, so could I please ask that
whenever you find yourself hacking (or even looking) at the C code,
scan through whatever file you are in and fix up any occurrences of
this mess.

Don't worry about meticulous logs for this kind of change.  A simple
`tla commit -s "whitespace cleanup" would be totally cool.

There is, however, more to it than that.  Primitive variables are in a
worse situation.

,----
| void complex_vars_of_emacs(void)
| {
|       /* This is all related to path searching. */
| 
|       DEFVAR_LISP("emacs-program-name", &Vemacs_program_name /*
| *Name of the Emacs variant.
| For example, this may be \"sxemacs\" or \"infodock\".
| This is mainly meant for use in path searching.
|                                                              */ );
`----

The same problem is present for these as is for the DEFUN's (the
whitespace breakage), but the mechanism of extracting the doc strings
is too limited (in my book, broken) to find them.

Why?

Because if the `DEFVAR_LISP' is more than 2 chars from column zero, it
doesn't get found. Which means that _all_ of the built-in variables
show up as "not documented as a variable".  Bad bad bad.  This is
annoying because I really don't want to compromise on coding style.

I was wondering if one of you C gurus (hello Evgeny) could take a
look at `lib-src/make-docfile.c' and see what we can do about this.

Thanks!

-- 
|---<Steve Youngs>---------------<GnuPG KeyID: A94B3003>---|
|                        In space,                         |
|             No one can hear you rip a stinky             |
|------------------------------------<steve@xxxxxxxxxxx>---|

pgpFqRf0I8J97.pgp
Description: PGP signature