Re: Scwm docstrings change

[mstachow at alum dot mit dot edu]

"Greg J. Badros" wrote:
> 
> You really need to figure out what's wrong with your mail-authoring
> software.

Argh. <crosses fingers and hopes this one comes out OK>

> >
> > So are you saying you will just run the program through CPP and out pops
> > the ready to use result, or that you will run it through cpp and then
> > postprocess the results in some way? If the latter, I don't see how having
> > to find function definitions is such a big deal.
> 
> Except that I'd like the post-processor to only have to deal with lines
> that start with, say, %%%% as guile-snarf and scwm-snarf now do.  I can
> actually get pretty darn close to the raw docstring output as it is w/o
> any substantial postprocessing, but my goal is to just make the
> postprocessing simple as it is fairly loosely coupled.

It sounds like that may place a lot of contstraints on where line
breaks may or must go in the macro calls.
  
> It's a solved problem one way, it's not solved the other way, and we
> agree it's largely a matter of aesthetics;  I'm planning on moving
> forward with the macro that keeps the coupling tighter and is more
> concise.

I hope we can reach some sort of consensus before you integrate this
with Guile.

> > However, (warning, quarter-baked thought approaching) perhaps it would
> > be better to make the macro include a scheme-style argument list, since
> > this would allower better control of how the formal parameter names will
> > look to the user. The function name is already written once in Scheme style
> > and once in C style. Indeed there are already cases in the Guile sources
> > where the Scheme and C names for functions or syntax do correspond in
> > the canonical way (`atapply' would normally become the Scheme `atapply'
> > rather than `@apply' for instance), and it may be the same thing might
> > be useful for formal parameters in some cases.
> 
> We already do this in scwmdoc.  foo_p turns into foo?, etc.

I know this translation happens. My point was regarding names that cannot
translate that way. `_p' to `?' at the end is a reasonable transformation.
Prefix `at' to prefix `@' is not, IMO, because a word could very well 
legitimately start with at - and there is no unambiguous way to
represent that Scheme identifier in the C style.
  
> I just don't buy the argument about code readability.  Function
> definitions *very* commonly exploit macros (see my research paper on an
> empirical study of C preprocessor use) and better-than-novice programs
> will only look twice before figuring out what's going on.

Pointer to paper please? I'm willing to recosider if this is widely used
existing practice. But I still think it looks better with the function
header separate.

 - Maciej