Hello, As I've worked on smart linking, I've found some gaps in the spec, often of the variety of "obvious" parts that should largely work the same as Perl 5. For example, "say" was formally spec'ed until recently, or "print" for that matter.
I have a suggestion which I believe make the docs more useful to users as well as the spec maintainers, in addition to helping the smart linking work flow. I would like a new heading at the bottom of each synposis that would be there to be a target for smart links, which clearly should be associated with this particular synopsis, but are lacking a specific target, because the spec is incomplete or missing. This is different than "unspecced" features, it more about features like "print", that are so obvious they have been left out until now. To users, it would be convey that there is already functionality they can review related to the synopsis, that might be fully spec'ed yet. To spec maintainers, it provides a kind of TODO list of things that need to be clarified. To smart linkers, it makes better use of our time than making no link, or linking to something suboptimal, with no visible result that we found something that needed attention. A name for this section might be "To Be Clarified" The boilerplate text might be: "The following tests relate to this synopsis, but need further spec clarifications so that a specific smart link can be created. #### As an example, today's discovery was that the auto-increment and decrement operators aren't spec'ed, beyond mentioning them in a precedence table. This specific example also illustrates why just pointing to "how Perl 5 works" isn't a good idea. The first sentence of the Perl 5 docs work are: '"++" and "--" work as in C ...' While I realize creating a self-contained Perl 6 spec is leaves significantly more work, It has the important benefit of clarifying exactly how large of a task it is to create something which is "official" in the sense that it complies with such a large volume of documentation, which will finally be available all in one place. Mark
