This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
This whole discussion of sgml vs info is absurd. The fact of the matter is that guile *doesn't* *have* *embedded* *documentation*. Add to this the fact that anyone who writes embedded documentation is going to do very *minimal* markup. Using texinfo markup & changing it later to sgml or visa versa is going to be *very* *little* work. The work that's needed is to *write* the documentation. Everything else is *very* *minor*. If that's not enough, consider the following. I already wrote an extractor. It *already* outputs sgml *and* it outputs a plaintext function list. Making it also output texi would be *trivial*. This is because I internally generate ssgml (i.e. - scheme sgml) from the input documentation. So, I have things like: (define (proc->primitives-ssgml docitem) (let* ((data (docitem:data docitem)) (proc (procdoc:decl data)) (doc (procdoc:doc data)) (arglist (proc:args proc)) (argregexp (arglist->argregexp arglist))) `((refentry (id ,(sgml-escape-xref (proc:scheme-name proc)))) ((refnamediv) ((refname) ,(proc:scheme-name proc)) ((refpurpose) ,(if (null? arglist) (car doc) (markup-args argregexp (car doc))))) ((refsynopsisdiv) ((synopsis) ,(function-call-decl proc))) ((refsect1) ((title) "Description") ((para) ,@(if (null? arglist) doc (map (lambda (d) (markup-args argregexp d)) doc)))) ((refsect1) ((title) "Implementation Notes") ((para) "Defined in " ((ulink (url ,(docitem:file docitem))) ((filename) ,(docitem:file docitem))) ,(string-append " at line " (stringify (docitem:line docitem)) ".")))))) for generating the sgml markup for the chapter on the list of primitives. Generating sgml output is then as simple as: ;;; Convert ssgml to sgml: (define (sgml form prefix) (cond ((string? form) (display prefix) (display (sgml-markup form)) (newline)) ((null? form) '()) (else (display prefix) (sgml-render-start (car form)) (let ((d (string-append prefix " "))) (for-each (lambda (f) (sgml f d)) (cdr form))) (display prefix) (sgml-render-end (car form))))) (define (sgml-render-start tag) (displayl "<" (car tag)) (for-each (lambda (args) (displayl " " (car args) "=") (write (cadr args))) (cdr tag)) (display ">\n")) (define (sgml-render-end tag) (displayl "</" (car tag) ">\n")) I wrote this whole thing in a couple of days. It'd only take a couple of days to do the ssgml & ssgml->sgml over for texinfo. It'd probably be *extremely* easy to just write an ssgml->texinfo as above. You could probably handle 95% of the work with an sgml-tag->texinfo-tag fcn. Who the hell cares whether the extractor outputs sgml which is converted to texinfo or whether it also outputs texinfo directly? The answer is: it's easy to output both. Some people find the SGML a pain to deal with. Therefore, output both! -- Harvey J. Stein BFM Financial Research hjstein@bfr.co.il