On May 26, 2011, at 3:39 AM, Felix wrote: > does chicken-doc > know anything about foreign type specifiers? If not, should it, and what > should be the markup? Would using the "[...]" convention make an existing > or possible future extension of chicken-doc problematic?
That's an excellent point. I'm of the mind that foreign type specifiers should be indexable. Probably, module import specifiers should as well. If so, the identifiers would need to be repeated for chicken-doc, e.g. ---- <typespec>int</typespec> <typespec>unsigned-int</typespec> <typespec>int32</typespec> <typespec>unsigned-int32</typespec> A small integer number in fixnum range (at least 30 bit). ---- If we went ahead with this, the page would have to be updated quite a bit (which I would be happy to do) regardless of the "[...]" convention. Adding "[...]" would not hurt things, but it would later have to be undone. Reading the page again, it looks like the contents need a bit of an overhaul anyway. == Markup The only reason chicken-doc does NOT index foreign types and module specifiers is that there was no obvious class of things they belonged to, and some conservatism left over from svnwiki compatibility. Some time ago, I thought about adding a generic tagging type which we could use instead of adding a built-in tag. For example, <def type="typespec"> instead of <typespec>. I am reluctant to do that though, because cases for new definition types seem pretty rare, and allowing arbitrary ones is ripe for typos. Also, some tags may even involve special case parsing, so would need code added anyway. Instead we would need specific tag(s) of some kind. Of the below I am inclined towards #2. 1) A dedicated tag: <typespec>, <foreigntypespec>; <importspec> <foreigntypespec>bool</foreigntypespec> <importspec>(prefix IMPORT SYMBOL)</importspec> Ugly, but we don't have to add new tags very often. May be preferable because foreign types reside in their own namespace. 2) A generic specifier tag: <specifier> <specifier>bool</specifier> <specifier>(prefix IMPORT SYMBOL)</specifier> Tidy, and perhaps applicable to future types or user eggs? 3) A generic catchall tag: <identifier> Parses any scheme expression like existing tags, classifying it as the generic "identifier". <identifier>bool</identifier> <identifier>(prefix IMPORT SYMBOL)</identifier> Probably overbroad. Thoughts, anyone? Also, let me know whether lighting up the import specifiers even makes sense in the first place. Jim _______________________________________________ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
