[Chicken-users] Topics and a main index (was: egg documentation)

[Tobia Conforto]

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