Documentation with GCC3.1, (was: build error on solaris)

[Alexander Klimov]

On Mon, 12 Mar 2001, Alexander Klimov wrote:
> The makeinfo is the same, so it looks like reason is guile-doc-snarf, and
> more specifically "gcc -E" in it. I'll try to look what is the problem
> exactly.

In the new version of gcc the preprocessor is greatly changed (mostly
due to merging it with the compiler), so preprocessed result is also
changed. The main chnages are (as I see from comporation of outputs):
o reduced number of empty lines
o reduced number of line-breakes

I almost shure, that such changes allowed by C standard, so we can't claim
it is a bug in gcc. You could take a look on
http://gcc.gnu.org/onlinedocs/cpp_1.html#SEC46
where following stated:
  Preservation of the form of whitespace between tokens is unlikely to
  change from current behavior (section C Preprocessor Output), but you
  are advised not to rely on it.

The change which broke guile documentation is that if previously we
have (example for assq-ref, from alist.c:221):
<<<<<
 SCM_SNARF_INIT_START  scm_make_gsubr (s_scm_assq_ref ,   2 ,   0 ,   0 , (SCM 
(*)() )  scm_assq_ref );    SCM_SNARF_DOC_STARTP   "assq-ref"  "(SCM alist, SCM 
key)" |   2  |   0  |   0  | "./alist.c": 232 | SCM_SNARF_DOCSTRING_START  
            "@deffnx primitive assv-ref alist key\n"
            "@deffnx primitive assoc-ref alist key\n"
            "Like @code{assq}, @code{assv} and @code{assoc}, except that only 
the\n"
            "value associated with @var{key} in @var{alist} is returned.  
These\n"
            "functions are equivalent to\n\n"
            "@lisp\n"
            "(let ((ent (@var{associator} @var{key} @var{alist})))\n"
            "  (and ent (cdr ent)))\n"
            "@end lisp\n\n"
            "where @var{associator} is one of @code{assq}, @code{assv} or 
@code{assoc}."  SCM_SNARF_DOCSTRING_END    
>>>>>
but now we have just one line:
<<<<<
SCM_SNARF_INIT_START scm_make_gsubr (s_scm_assq_ref, 2, 0, 0, (SCM (*)()) 
scm_assq_ref);SCM_SNARF_DOC_STARTP "assq-ref" "(SCM alist, SCM key)" | 2 | 0 | 
0 | "./alist.c":221 | SCM_SNARF_DOCSTRING_START "@deffnx primitive assv-ref 
alist key\n" "@deffnx primitive assoc-ref alist key\n" "Like @code{assq}, 
@code{assv} and @code{assoc}, except that only the\n" "value associated with 
@var{key} in @var{alist} is returned.  These\n" "functions are equivalent 
to\n\n" "@lisp\n" "(let ((ent (@var{associator} @var{key} @var{alist})))\n" "  
(and ent (cdr ent)))\n" "@end lisp\n\n" "where @var{associator} is one of 
@code{assq}, @code{assv} or @code{assoc}." SCM_SNARF_DOCSTRING_END
>>>>>

As a result in the .doc file we have (I remove `cut' from guile-doc-snarf,
because lines now are much longer):
<<<<<
assq-ref
@c snarfed from alist.c:221
@deffn primitive assq-ref alist key
@deffnx primitive assv-ref alist key\n" "@deffnx primitive assoc-ref alist 
key\n" "Like @code{assq}, @code{assv} and @code{assoc}, except that only the\n" 
"value associated with @var{key} in @var{alist} is returned.  These\n" 
"functions are equivalent to
 "@lisp\n" "(let ((ent (@var{associator} @var{key} @var{alist})))\n" "  (and 
ent (cdr ent)))\n" "@end lisp
 "where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
@end deffn
>>>>>

Which is the result of bug in `guile-snarf.awk'.

BTW: What is the reason for this complication of usage of the preprocessor
and then awk script? I look thru the source code, and it seams to me that
usage of SCM_DEFINE is very consistent (I mean line breakes), so why not
use the code directly for awk processing?

Regards,
ASK