From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: dave Newsgroups: gmane.lisp.guile.user Subject: Re: docstrings and snarfing Date: Sun, 16 Jul 2006 22:48:57 +0100 Message-ID: <1153086537.8280.10.camel@localhost.localdomain> References: <23454634.1152998392102.JavaMail.root@web22> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1153085083 25943 80.91.229.2 (16 Jul 2006 21:24:43 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 16 Jul 2006 21:24:43 +0000 (UTC) Cc: guile-user@gnu.org, Kevin Ryde Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Sun Jul 16 23:24:40 2006 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1G2E6M-0003hC-Ud for guile-user@m.gmane.org; Sun, 16 Jul 2006 23:24:35 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G2E6M-00046N-EU for guile-user@m.gmane.org; Sun, 16 Jul 2006 17:24:34 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1G2E6H-00046G-Pg for guile-user@gnu.org; Sun, 16 Jul 2006 17:24:29 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1G2E6G-00045T-07 for guile-user@gnu.org; Sun, 16 Jul 2006 17:24:29 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G2E6F-00045Q-RP for guile-user@gnu.org; Sun, 16 Jul 2006 17:24:27 -0400 Original-Received: from [208.97.132.118] (helo=randymail-a3.dreamhost.com) by monty-python.gnu.org with esmtp (Exim 4.52) id 1G2E8m-0002yJ-2N for guile-user@gnu.org; Sun, 16 Jul 2006 17:27:04 -0400 Original-Received: from 81-174-208-172.pth-as1.dial.plus.net (81-174-208-172.pth-as1.dial.plus.net [81.174.208.172]) by randymail-a3.dreamhost.com (Postfix) with ESMTP id 48CC9185563; Sun, 16 Jul 2006 14:24:22 -0700 (PDT) Original-To: dsmich@adelphia.net In-Reply-To: <23454634.1152998392102.JavaMail.root@web22> X-Mailer: Evolution 2.4.1 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.user:5404 Archived-At: On Sat, 2006-07-15 at 17:19 -0400, dsmich@adelphia.net wrote: > ---- Kevin Ryde wrote: > > "Dave Griffiths" 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. This makes it all a lot clearer, thankyou - I didn't realise the documentation was seperate from the api in this way, and was all dealt with as post processing. In the absence of a working official method, I'll probably roll my own system like this in a way that I can merge it in with guile in the future. cheers, dave _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://lists.gnu.org/mailman/listinfo/guile-user