Re: [Chicken-hackers] Request to edit manual Foreign type specifiers
On May 28, 2011, at 4:26 AM, Felix wrote: I would suggest a type tag, which can be used for foreign- and (forthcoming) specialization type specifiers. It is generic enough to be re-usable for different type-related purposes and having multiple entities of type type in the same document is confusing enough for the reader to be avoided. OK, type now works in chicken-doc and qwiki. I have added type tags to the foreign types documentation, reorganized the page and expanded its contents. If you like, have a look at one of: http://api.call-cc.org/doc/foreign/types http://wiki.call-cc.org/man/4/Foreign%20type%20specifiers Jim ___ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
Re: [Chicken-hackers] Request to edit manual Foreign type specifiers
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. I would suggest a type tag, which can be used for foreign- and (forthcoming) specialization type specifiers. It is generic enough to be re-usable for different type-related purposes and having multiple entities of type type in the same document is confusing enough for the reader to be avoided. cheers, felix ___ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
Re: [Chicken-hackers] Request to edit manual Foreign type specifiers
From: Kon Lovett konlov...@gmail.com Subject: [Chicken-hackers] Request to edit manual Foreign type specifiers Date: Wed, 25 May 2011 13:33:47 -0700 Hi Folks, I would like to edit the Foreign type specifiers manual section so pointer entries follow the optional attribute convention introduced by '[nonnull-] c-string*'. I will also add a general note about the pointer passing/return #f - NULL conversion. In keeping with the spirit above specifiers like unsigned-integer will become [unsigned-] integer. Sure. It's a bit of a mess, that page, anyway, and help in improving the manual is always welcome. But one question remains: 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? cheers, felix ___ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
Re: [Chicken-hackers] Request to edit manual Foreign type specifiers
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. typespecint/typespec typespecunsigned-int/typespec typespecint32/typespec typespecunsigned-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 foreigntypespecbool/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 specifierbool/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. identifierbool/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
Re: [Chicken-hackers] Request to edit manual Foreign type specifiers
Jim Ursetto zbignie...@gmail.com writes: 1) A dedicated tag: typespec, foreigntypespec; importspec I suggest adding a dash of dashes, e.g. foreign-type-spec Thoughts, anyone? I don't really get the difference between specifier and identifier, can you elaborate on that? 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! Moritz ___ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
[Chicken-hackers] Request to edit manual Foreign type specifiers
Hi Folks, I would like to edit the Foreign type specifiers manual section so pointer entries follow the optional attribute convention introduced by '[nonnull-] c-string*'. I will also add a general note about the pointer passing/return #f - NULL conversion. In keeping with the spirit above specifiers like unsigned-integer will become [unsigned-] integer. Let me know if any issues, Thank you, Kon ___ Chicken-hackers mailing list Chicken-hackers@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-hackers
