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 _______________________________________________ Chicken-hackers mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/chicken-hackers
