Things are beginning to look great :) > However at the same time I debate what is the usefulness of the > "partial" signatures you can automatically extract from the HTML, vs > the cost of adding the markup. > As hinted in the previous paragraph: what would be the actual > usefulness of such partial signatures? How would you use them? I would have these immediate uses for them: 1) To show a quick overview of a particular definition (e.g. in Emacs, put the cursor on a procedure name and it shows the expected arguments at the bottom of the screen). 2) To show a cheat sheet or an index of procedures with arguments. I generated an example: <http://lassi.io/temp/srfi-symbol-index.html>. It could be formatted more nicely and have links, but shows what I mean. Personally, Scheme is not my primary language and I tend to switch languages constantly (as people are often forced to do nowadays) so I forget details all the time. This kind of detailed reference card is a huge help when learning a language or refreshing memory. 3) Search for procedures by argument name. This would not be perfect by any means, but it's one more tool to help find procedures and could be implemented with almost no extra work from the index. For these purposes, the main thing would be to have the names of the arguments, and to see which ones are optional and which are required. Types would be a nice bonus, but not strictly necessary. A link to the the SRFI (especially if it's a direct link to the right definition) would be plenty to get started with. > I don't know if the signatures should or shouldn't be part of the > actual SRFI repository. > > I think a better place would be in a completely different "common" > repository. After listening to all your points of view, I'm fine with either decision. >> If we are going to developing the static type signatures in the >> same S-expression file where the straightforward transcribed stuff >> lives, > > I see nothing wrong with multiple files. The "automatically > extracted" signatures could live in separate file than the "manually > formalized" signatures. Moreover there could be a simple tool that > would cross-check any discrepancies between the two. The more I think about this, the more I'm beginning to agree. Especially if the type signatures are stored in different repos. The cross-checking tool would really be the main thing for me. As long as we have a simple command that we can run to ask "is everything synced?" then things will probably be fine. We might even be able set up a Continuous Integration server to check automatically. The rest of tooling and format design is just a question of having more vs less manual work, and those details can be worked out one way or another. If we use S-expressions for all the metadata files, the cross-checker will also be easy to write in Scheme, eliminating one more discussion about which language to use for tooling ;) > Please note that the above signature doesn't include argument > "names" because I haven't actually added them in the signature, > however the underlying format does support them. OK, then an automatic converter could probably be made to generate traditional Lispy signatures. >> We would have to find some notation that combines these quite >> opposing traditions. We could also write them separately, but any >> duplication is a chance for discrepancy. > > The format I proposed supports both. (The variant of `make-vector` > above is just a "specialization" of the more "traditional" format.) > Also in case of `list-copy` I clearly want to markup that a circular > list would raise an error: That sounds quite advanced :) Is there a circular list detector?
