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.


Reply via email to