Jim Ursetto wrote:
<proc>(string-set! a b)</proc>
<macro>(args:make-option (OPTION-NAME ...) ARG-DATA [BODY])</macro>
<record>hostinfo</record>
<param>eggdoc:doctype</param>
<read>@[object message: value ...]</read>
<signature type="string">doctype:xhtml-1.0-strict</signature>
I like this solution! It's a good compromise between plain, un-
indexed Wiki pages and a complete documentation rewrite in a domain-
specific language (which, although technically better, I agree would
thwart user contributions.)
I hope you are planning to build a "main index" of all definitions, by
symbol and by permuted symbol? (see for example the indexes in CL
Hyperspec) IMHO this would be the best benefit of introducing this
syntax. I will gladly contribute code, once we decide to start
working on it.
In this spirit, I propose another addition: topics, meaning relevance
to something:
<proc topics="stream cons higher-order">(stream-xcons a b)</proc>
This would make it possible to build a dynamic index system of all the
definitions (procedures, macros, records...) that have something to do
with consing, and/or with streams, and/or with higher-order procedure
usage or any other topic used in at least one definition. Other
topics could be: list, vector, string, port, networking, html, eval,
threading, fold, map, cgi, timedate...
The topic index system can be written later, but I think it's
important to get the attribute ready for the hackaton, if we agree
it's a good idea. Meaning, let's define a list of basic topics and
commit to put them on every definition we touch, if and where
appropriate.
With these semantic additions, I think the wiki repo could be
considered the main source of documentation. Package builders will
just have to checkout both the egg repo and the wiki repo, and run
some scripts to generate the most recent documentation in various
formats.
Vincent Manis wrote:
By the way, on the subject of wiki markup, I'd like to put in a plug
for marking index entries.
As I see it, with Alejandro's solution we are already marking index
entries, at least for procedures, macros, records, and SRFI-39
parameters. On the other hand, the contents of <read> and <signature>
don't have a fixed syntax that can be easily extracted (they aren't a
single s-expr whose car is to be indexed) so maybe an index=""
attribute would have its uses, in case the author feels like putting a
name for the entry in the aforementioned main index. Or maybe not.
If instead you mean index links, as in "this macro is useful in
conjunction with [[index:stream-xcons]]", that's a good idea. We
could again fix the syntax and use it in the forthcoming documentation
review, delaying implementation to when we write the main index itself.
Tobia
_______________________________________________
Chicken-users mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/chicken-users
