doc snarfing does not work with Sun Forte preprocessor

[Matthias Koeppe]

The doc-snarfing procedure using the C preprocessor and the
guile-snarf.awk script does not work if one uses the preprocessor of
the Sun Forte compilers instead of gcc's. 

The reason is that the preprocessor puts all doc-string fragments on
one long line like one shown at the end of this article.  This causes
two problems: 

1) This format is not handled by the AWK script, but this can be
   solved easily by the patch below.

2) guile-doc-snarf truncates lines in the preprocessed source to 1024
   characters via cut before feeding it to the AWK script; therefore
   the snarfer tags are cut off for long doc strings like the one
   below.  The result is garbage in the doc strings. 

   Removing the truncation solves this problem for me, but I guess
   there must have been a reason to introduce it (I haven't found a
   note on this anywhere).

I guess one should replace the preprocessor/awk snarfing method with a
more robust Scheme implementation.  I see there is a scripts/doc-snarf
file; shouldn't it be used to build the documentation files?  (There
is no bootstrapping problem since one can run Guile directly from the
build directory.)

Matthias

------------ long line sample ------------
 SCM_SNARF_INIT_START scm_make_gsubr ( s_scm_dynamic_wind , 3 , 0 , 0 , ( SCM ( 
* ) ( ) ) scm_dynamic_wind ) ; SCM_SNARF_DOC_STARTP "dynamic-wind" "(SCM 
in_guard, SCM thunk, SCM out_guard)" | 3 | 0 | 0 | "dynwind.c" : 121 | 
SCM_SNARF_DOCSTRING_START "All three arguments must be 0-argument 
procedures.\n" "@var{in_guard} is called, then @var{thunk}, then\n" 
"@var{out_guard}.\n" "\n" "If, any time during the execution of @var{thunk}, 
the\n" "continuation of the @code{dynamic_wind} expression is escaped\n" 
"non-locally, @var{out_guard} is called.  If the continuation of\n" "the 
dynamic-wind is re-entered, @var{in_guard} is called.  Thus\n" "@var{in_guard} 
and @var{out_guard} may be called any number of\n" "times.\n" "@lisp\n" 
"(define x 'normal-binding)\n" "@result{} x\n" "(define a-cont  
(call-with-current-continuation \n" "                 (lambda (escape)\n" "     
         (let ((old-x x))\n" "                     (dynamic-wind\n" "           
              ;; in-guard:\n" "                       ;;\n" "                   
      (lambda () (set! x 'special-binding))\n" "\n" "                         
;; thunk\n" "                   ;;\n" "                         (lambda () 
(display x) (newline)\n" "                              
(call-with-current-continuation escape)\n" "                                    
(display x) (newline)\n" "                              x)\n" "\n" "            
             ;; out-guard:\n" "                      ;;\n" "                    
     (lambda () (set! x old-x)))))))\n" "\n" ";; Prints: \n" 
"special-binding\n" ";; Evaluates to:\n" "@result{} a-cont\n" "x\n" "@result{} 
normal-binding\n" "(a-cont #f)\n" ";; Prints:\n" "special-binding\n" ";; 
Evaluates to:\n" "@result{} a-cont  ;; the value of the (define a-cont...)\n" 
"x\n" "@result{} normal-binding\n" "a-cont\n" "@result{} special-binding\n" 
"@end lisp" SCM_SNARF_DOCSTRING_END
------------------------------------

Index: guile-snarf.awk.in
===================================================================
RCS file: /cvs/guile/guile-core/libguile/guile-snarf.awk.in,v
retrieving revision 1.14
diff -u -u -r1.14 guile-snarf.awk.in
--- guile-snarf.awk.in  2001/05/04 21:54:00     1.14
+++ guile-snarf.awk.in  2001/05/09 12:26:39
@@ -104,6 +104,11 @@
                 
                 # Trim leading whitespace and opening quote.
                 sub(/^[ \t]*\"?/,"", copy);
+
+                # The Sun Forte preprocessor puts the documentation string
+                # fragments on one line, so remove closing and opening quotes
+                # in the middle of lines. 
+                gsub(/\" \"/,"",copy);
                 
                 # Trim closing quote and trailing whitespace, or
                  # closing quote and whitespace followed by the


-- 
Matthias Köppe -- http://www.math.uni-magdeburg.de/~mkoeppe