unofficial mirror of guile-user@gnu.org 
 help / color / mirror / Atom feed
* Re: docstrings and snarfing
@ 2006-07-15 21:19 dsmich
  2006-07-16 21:48 ` dave
  0 siblings, 1 reply; 6+ messages in thread
From: dsmich @ 2006-07-15 21:19 UTC (permalink / raw)
  Cc: guile-user

---- Kevin Ryde <user42@zip.com.au> wrote: 
> "Dave Griffiths" <dave@pawfal.org> writes:
> >
> > I tried running the example through the C preprocessor, and it seems
> > the docstring is lost anyway:
> 
> There's some magic with a "-DSCM_MAGIC_SNARF_DOCS" to get them, then
> the scripts/snarf-check-and-output-texi program picks them out from
> the code.  (Or something like that.)  Not documented in the manual
> though (alas).

Doc snarfing of C code is done in several stages.

  1. The first stage is to extract all the docstrings from the C files
     using the C preprocessor.  (The guile-snarf-docs shell script)

  2. Then a filter program (guile_filter_doc_snarfage compiled from
     c-tokenize.lex) is used to convert the extracted strings into
     easily parsed scheme data.  These are the .doc files.  Because
     these files are basically scheme data structures, they can be
     easily read and manipulated with scheme.

  3. The next stage concatenates all the .doc files together and
     generates texinfo source. (guile script scripts/snarf-check-and-output-texi)
     Two texinfo files are created: guile.texi and
     guile-procedures.texi.  They are basically the same except the
     guile.texi file has extra C function names for Scheme primitives.

  4. Finally makeinfo is used to process guile-procedures.texi into a
     text file.  (guile-procedures.txt) The text file is used for
     Guile online help documentation.

-Dale



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user


^ permalink raw reply	[flat|nested] 6+ messages in thread
* Re: docstrings and snarfing
@ 2006-07-15 18:21 dsmich
  0 siblings, 0 replies; 6+ messages in thread
From: dsmich @ 2006-07-15 18:21 UTC (permalink / raw)
  Cc: guile-user

---- Kevin Ryde <user42@zip.com.au> wrote: 
> "Dave Griffiths" <dave@pawfal.org> writes:
> >
> > I tried running the example through the C preprocessor, and it seems
> > the docstring is lost anyway:
> 
> There's some magic with a "-DSCM_MAGIC_SNARF_DOCS" to get them, then
> the scripts/snarf-check-and-output-texi program picks them out from
> the code.  (Or something like that.)  Not documented in the manual
> though (alas).

Docsnarfing is something I'd like to see made available (again) for quite some time now.  The pieces that implement this for Guile (several scripts and some compiled code) are not currently installed.  It was at one time, but removed because of the difficulty in supporting all the platfroms that Guile supports. (If I remember correctly)

I've been (very slowly!) bringing scwm up to date with Guile 1.8.  Scwm uses docstrings as heavily as emacs.  It would *really* be great to have docsnarfing working again.  My currenty plans are to lift the Guile code and inlcude it as part of scwm.

-Dale



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user


^ permalink raw reply	[flat|nested] 6+ messages in thread
* docstrings and snarfing
@ 2006-07-13 10:15 Dave Griffiths
  2006-07-15  1:57 ` Kevin Ryde
  0 siblings, 1 reply; 6+ messages in thread
From: Dave Griffiths @ 2006-07-13 10:15 UTC (permalink / raw)


Hi all,

I want to implement docstrings for my extension functions, but for various
reasons I can't use snarfing (the array it generates has problems with C++
namespaces).

So I had a look through the macros for SCM_DEFINE to find out what it does
with the DOCSTRING argument, and got lost pretty quickly, so I tried
running the example through the C preprocessor, and it seems the docstring
is lost anyway:

 static const char s_clear_image [] = "clear-image"; SCM clear_image (SCM
image_smob)


 {

 }

 void
 init_image_type ()
 {
# 1 "clear-image.x" 1

 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)()) clear_image); ;
# 14 "clear-image.c" 2
 }

after snarfing and cpping the example code:

#include <libguile.h>

SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
             (SCM image_smob),
             "Clear the image.")
 {
   /* C code to clear the image in image_smob... */
 }

 void
 init_image_type ()
 {
 #include "clear-image.x"
 }

Any pointers to what happens with the docstring, or how I can implement
them for my functions?

Many thanks,

dave



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user


^ permalink raw reply	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2006-07-18 17:14 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2006-07-15 21:19 docstrings and snarfing dsmich
2006-07-16 21:48 ` dave
2006-07-18 17:14   ` Neil Jerram
  -- strict thread matches above, loose matches on Subject: below --
2006-07-15 18:21 dsmich
2006-07-13 10:15 Dave Griffiths
2006-07-15  1:57 ` Kevin Ryde

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).