* how authors of add-on modules can package documentation @ 2002-03-17 4:18 Neil W. Van Dyke 2002-03-17 16:41 ` Evan Prodromou 2002-04-03 3:52 ` Thien-Thi Nguyen 0 siblings, 2 replies; 7+ messages in thread From: Neil W. Van Dyke @ 2002-03-17 4:18 UTC (permalink / raw) If anyone is thinking about different ways that authors of reusable Guile add-on modules can document their code, we should compare notes. A year ago I kludged up a filter called "Funcelit" (as in "functionally-illiterate programming") that extracts Texinfo fragments from a Guile Scheme file, tweaks them a bit, and glues them together with some boilerplate to generate a Texinfo file. The resulting Texinfo file can be translated to Info, HTML, PS/PDF formats using the usual Texinfo tools, but the output will be formatted as an article rather than as a book. Originally I had the filter treat each module as a chapter in a book, but then I decided to focus on loosely-coupled standalone modules rather than on a monolithic collection of modules. Chapter formatting could be added back in as an option. One reason I like having full docs in the source file itself as human-readable comments is that then a module can be shared simply by passing around a single Scheme source code file. This file can be immediately viewed and modified by the person who receives it (i.e., there is no "tar" or package manager to deal with, no source files getting hidden away elsewhere deep in some filesystem tree, etc.). I think this kind of accessibility of source files is one of the reasons that so many people have gotten started writing their own Emacs Lisp extensions. Of course, a holder of a source file always has the option of running the Funcelit filter on the source file generate pretty Info/HTML/PS/PDF documentation. Funcelit is not yet released, as I've been adapting it as I use it in writing modules, and didn't want to be constantly changing the input format on people. I'll probably polish it up and release it not too long after the release of Guile 1.6. (I was reminded of Funcelit tonight because I finally kludged up some Emacs font-lock support for Funcelit comments. Screenshot at "http://www.neilvandyke.org/weblog/funcelit-fontified.png".) -- Neil W. Van Dyke http://www.neilvandyke.org/ _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-17 4:18 how authors of add-on modules can package documentation Neil W. Van Dyke @ 2002-03-17 16:41 ` Evan Prodromou 2002-03-17 23:35 ` Neil Jerram 2002-04-03 3:52 ` Thien-Thi Nguyen 1 sibling, 1 reply; 7+ messages in thread From: Evan Prodromou @ 2002-03-17 16:41 UTC (permalink / raw) >>>>> "NWVD" == Neil W Van Dyke <nwv@neilvandyke.org> writes: NWVD> If anyone is thinking about different ways that authors of NWVD> reusable Guile add-on modules can document their code, we NWVD> should compare notes. So, as a module author, I have been thinking about this quite a bit myself. I really, really think that there should be a "standard" way to write documentation for Guile, embedded into the code, as javadoc is for Java, or pod for Perl, or other stuff for other languages. There should be a tool to extract that documentation automatically to static formats, such as (as you said) texinfo, plus a *roff file for man pages. In addition, the documentation should be available in Guile interactive sessions through the (help) facility or something like it. A user shouldn't have to care whether a function was defined in guile-core or by Evan Prodromou when asking for (help). In any system, function signatures should be grabbed automatically for basic function definition formats [(define (foo x) ...), (define-public (foo x) ...), (define foo (lambda (x) ...))]. This should be axiomatic. I'd personally like to see GOOPS (define-class) and (define-method) stuff grabbed automatically, too, but that's just me. The hard part is getting description documentation -- the author's description of what a function does, what it's for, what it returns, and what to look out for, etc. This is a little harder to figure out where it is and what it's related to. I think there are several ways to have embedded documentation: 1. The traditional Lispy ; commenting style. Old-schoolers know that a four-semicolon comment (;;;;) introduces a description of the file in general, three semicolons (;;;) is a per-definition (function or variable) description, two semis (;;) for a comment on its own line and one semi (;) for an in-line comment. It would be relatively easy for a text processor to grab foursies to make them the file description, and threesies to associate them with the next variable or function. It'd be kind of hard to do for interactive sessions, however, since normally comments are, after all, thrown away. Also, there's a big problem with false positives, as not all programmers follow this practice. 2. The documentation string. This is also pretty traditional for Lispers, and it's a simple enough way to put in a description of whatever format and length. I think the problem with docstrings is that there's not really a good way to attach one to a file or to a variable, much less to a GOOPS class or method. So any embedded overview, or details for non-function interface items, are lost. 3. "Special" comments or structures. These would be new Guile-specific mechanisms, like, say: ; {doc-comment} ; {/doc-comment} Or even (define-documented (func #:desc does something #:throws bounds-exception (x #:desc first param) (y #:desc second param))) I think that this would probably be easiest to process, but would require a lot of hassle for the author. Of these three, I like the semi-colon format the best, but I dunno. Regardless of how it's done, I think a Suggested Documentation Format is something that's going to have to happen sooner rather than later, or diverging de facto stuff will happen (or, worse, no documentation at all). ~ESP P.S. As to man pages: I think a suggested module.3guile is imperative. Man pages make the world go round, after all, and I don't think texinfo puts them out. -- Evan Prodromou evan@glug.org _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-17 16:41 ` Evan Prodromou @ 2002-03-17 23:35 ` Neil Jerram 2002-03-17 23:45 ` Neil Jerram 2002-03-18 2:04 ` Evan Prodromou 0 siblings, 2 replies; 7+ messages in thread From: Neil Jerram @ 2002-03-17 23:35 UTC (permalink / raw) Cc: guile-devel >>>>> "Evan" == Evan Prodromou <evan@glug.org> writes: >>>>> "NWVD" == Neil W Van Dyke <nwv@neilvandyke.org> writes: NWVD> If anyone is thinking about different ways that authors of NWVD> reusable Guile add-on modules can document their code, we NWVD> should compare notes. Evan> So, as a module author, I have been thinking about this quite a bit Evan> myself. I really, really think that there should be a "standard" way Evan> to write documentation for Guile, embedded into the code, as javadoc Evan> is for Java, or pod for Perl, or other stuff for other languages. I haven't yet read your ideas carefully, but you might like to note that there were a couple of mailing list threads in this area back in February 2001: - subject "docstring work" beginning at http://mail.gnu.org/pipermail/guile-devel/2001-February/001001.html - subject "Documentation" beginning at http://mail.gnu.org/pipermail/guile-devel/2001-February/001154.html I believe the consensus at the end of those threads preferred docs as strings rather than as comments; i.e. (define (xxx arg) "Do something" ...) rather than ;;; Do something (define (xxx arg) ...) Oh, and don't forget i18n! Neil _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-17 23:35 ` Neil Jerram @ 2002-03-17 23:45 ` Neil Jerram 2002-03-18 2:04 ` Evan Prodromou 1 sibling, 0 replies; 7+ messages in thread From: Neil Jerram @ 2002-03-17 23:45 UTC (permalink / raw) Cc: Neil W. Van Dyke, guile-devel >>>>> "Neil" == Neil Jerram <neil@ossau.uklinux.net> writes: Neil> - subject "docstring work" beginning at Neil> http://mail.gnu.org/pipermail/guile-devel/2001-February/001001.html Neil> - subject "Documentation" beginning at Neil> http://mail.gnu.org/pipermail/guile-devel/2001-February/001154.html Oops, and also a third thread, subject "Scheme file docstring format", beginning at http://mail.gnu.org/pipermail/guile-devel/2001-February/001084.html. This last was actually the thread that started off the whole discussion: the other two above came later. Neil _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-17 23:35 ` Neil Jerram 2002-03-17 23:45 ` Neil Jerram @ 2002-03-18 2:04 ` Evan Prodromou 2002-04-03 5:29 ` Thien-Thi Nguyen 1 sibling, 1 reply; 7+ messages in thread From: Evan Prodromou @ 2002-03-18 2:04 UTC (permalink / raw) >>>>> "NJ" == Neil Jerram <neil@ossau.uklinux.net> writes: NJ> I believe the consensus at the end of those threads preferred NJ> docs as strings rather than as comments; i.e. NJ> (define (xxx arg) "Do something" ...) NJ> rather than NJ> ;;; Do something NJ> (define (xxx arg) ...) OK, but as I mentioned before, there doesn't seem to be much provision for doc'ing variables, classes, methods, etc. with docstrings. ~ESP -- Evan Prodromou evan@glug.org _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-18 2:04 ` Evan Prodromou @ 2002-04-03 5:29 ` Thien-Thi Nguyen 0 siblings, 0 replies; 7+ messages in thread From: Thien-Thi Nguyen @ 2002-04-03 5:29 UTC (permalink / raw) Cc: guile-devel From: Evan Prodromou <evan@glug.org> Date: Sun, 17 Mar 2002 18:04:40 -0800 OK, but as I mentioned before, there doesn't seem to be much provision for doc'ing variables, classes, methods, etc. with docstrings. below is (ttn defvar). is this what you mean? thi ________________________________ ;;; ID: $Id: defvar.scm,v 1.3 2000/09/11 01:13:41 ttn Rel $ ;;; ;;; Description: Provide `defvar' and some doc-access procedures. (define-module (ttn defvar)) (defmacro defvar (name value docstring) `(let ((var (make-variable ,value ',name))) (module-add! (current-module) ',name var) (set-object-property! var 'documentation ,docstring) ,value)) (define (documentation-property obj) "Return, as a string, documentation on OBJ, or #f. OBJ may be a pair of the form (MODULE . SYM), where MODULE is in list form as in `define-module', in which case MODULE is consulted instead of the current-module." (cond ((variable? obj) (object-property obj 'documentation)) ((procedure? obj) (procedure-documentation obj)) ((symbol? obj) (documentation-property (module-variable (current-module) obj))) ((pair? obj) (save-module-excursion (lambda () (set-current-module (resolve-module (car obj))) (documentation-property (cdr obj))))) (else #f))) (export defvar documentation-property) ;;; $RCSfile: defvar.scm,v $$Revision: 1.3 $ ends here _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: how authors of add-on modules can package documentation 2002-03-17 4:18 how authors of add-on modules can package documentation Neil W. Van Dyke 2002-03-17 16:41 ` Evan Prodromou @ 2002-04-03 3:52 ` Thien-Thi Nguyen 1 sibling, 0 replies; 7+ messages in thread From: Thien-Thi Nguyen @ 2002-04-03 3:52 UTC (permalink / raw) Cc: guile-devel From: "Neil W. Van Dyke" <nwv@neilvandyke.org> Date: Sat, 16 Mar 2002 23:18:52 -0500 Funcelit is not yet released, as I've been adapting it as I use it in writing modules, and didn't want to be constantly changing the input format on people. I'll probably polish it up and release it not too long after the release of Guile 1.6. if you decouple Funcelit release from guile release, people can use it sooner. plus, that would give everyone (especially guile maintainers) more options when figuring out how to design "official" doc snarfing. thi _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2002-04-03 5:29 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2002-03-17 4:18 how authors of add-on modules can package documentation Neil W. Van Dyke 2002-03-17 16:41 ` Evan Prodromou 2002-03-17 23:35 ` Neil Jerram 2002-03-17 23:45 ` Neil Jerram 2002-03-18 2:04 ` Evan Prodromou 2002-04-03 5:29 ` Thien-Thi Nguyen 2002-04-03 3:52 ` Thien-Thi Nguyen
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).