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

[Jim Ursetto]

On May 26, 2011, at 1:11 PM, Moritz Heidkamp wrote:

> I suggest adding a dash of dashes, e.g. <foreign-type-spec>

A good idea.

> I don't really get the difference between <specifier> and <identifier>,
> can you elaborate on that?

Let me preface this wall of text with this: upon further thought, <specifier> 
is probably not useful with chicken-doc as it is currently implemented.  Anyway:

A scheme identifier being a more generic class; where a procedure, constant and 
specifier are all identifiers, but a procedure is not a specifier.  A 
specifier, I suppose, would be a fragment of syntax used solely inside certain 
(syntax) expressions.  An identifier would be a generic scheme expression where 
the indexed item is either the car (if a list) or the item (if a symbol); e.g. 
a procedure if we didn't have a tag for procedure.

It's not clear if "specifier" or even "identifier" is generally useful though.  
For example, look at http://api.call-cc.org/doc/foreigners.  
define-foreign-record-type and define-foreign-enum-type both have "specifiers", 
the "slot definitions" and the "enumspec", but neither one is really indexable 
because they don't have a fixed identifier at the head.  In this case, they 
would be better folded into their parent definition by removing their headers 
(chicken-doc of course stops the definition at the next header, even if it's a 
subheader).

As another example, look at the coops egg (http://api.call-cc.org/doc/coops).  
There are a bunch of nonstandard tags, such as "slot option" and "class option" 
in define-class, as well as "generic" and "class".  Now, we have a <class> tag 
already and that could be fixed.  "generic" could perhaps be rewritten as 
<method>.  But "slot option" or SLOTSPEC has no real equivalent.  A dedicated 
tag for that seems like overkill.  They could be considered specifiers:

<specifier>reader: NAME</specifier>

However, if another specifier called "reader:" existed elsewhere in the coops 
egg, they would collide in the index, which would be bad.  Total protonic 
reversal.  Indexing them probably doesn't make any sense in the first place.  
At this point we usually resign ourselves to simply rewriting the markup so it 
looks nice, but is not indexed.

The same argument could be used against marking up import specifiers, though.  
They're only visible in one place (inside "import") and so perhaps they should 
just be folded into that definition, not indexed globally.

There are some pie-in-the-sky ideas I've thought about to address this indexing 
problem, but nothing very appealing.

Since this will affect the manual and since Felix typically innovates new tags 
(yes, innovates), Felix's opinion on how the documentation system should behave 
would be appreciated.

I will say this: adding a dedicated tag <foreign-type-spec> -- that will be 
used only on one page ever -- seems kind of silly.  On the other hand, the more 
generic tag <specifier> seems to be incompatible with how chicken-doc is 
currently implemented and used.  So we may have to resort to a dedicated tag.

>> Also, let me know whether lighting up the import specifiers even makes
>> sense in the first place.
> 
> I think so, yes, as I found myself searching for them in chicken-doc a
> few times!

The alternative is to remove the section headings under the (chicken modules 
import) node, which would make them visible when you do 'chicken-doc import', 
though not in the index.

J