Re: [Chicken-hackers] Request to edit manual Foreign type specifiers

[Jim Ursetto]

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