This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Scwm docstrings change
"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