Document file specification

In the path towards a new documentation system, we need to settle on a specification of the document page format first. There's no such thing now, although there are some tests that check certain aspects of the documentation (and the rest of the files in the repository). Let's see what a documentation page really is.

1. Content in Pod6 format.
2. Document metadata
3. Content metadata, including, but not limited to, indexes.

Let's see first what kinds of metadata we are using.

Metadata for Perl 6 documentation files

There are several pieces of metadata.

1. A broad *topic", which is contained in the directory it occupies in the repository. There are Language, Type and Program documents.
2. A narrow topic, which is implicit in the file name. For instance, some Language files that deal with transition from perl5 to 6 get special treatment when processed.
3. A section, which is conceptually the same as above, only it's processed by a different file and contained in the 00-POD-CONTROL file. This is essentially used to generate the language.html page.
4. A tag at the beginning of the file, =begin pod :tag<perl6>. It's apparently unused, although it's a well-intentioned way of establishing a topic as in the first item above.
5. Title and subtitle.
6. Class or role definition, if it's a class.

1 to 3 above are external to the file. 4 to 6 are internal. 2 and 3 are roughly the same, but they are dealt with in different ways. 2 and 4 are also roughly the same, but 4 is apparently unused and there's no specification of what values it should take and how to deal with them.

So, here's the spec proposal

1. All metadata should be included as pod config in the =begin pod line.
2. The documents should have a topic with three possible values: Reference, Tutorial or Runtime (equivalent to the actual Type, Language and Runtime). All of these might have subtopics.
   1. Reference would have the possible values: unit (class, role), routine (functions that are defined outside classes), or statement (whatever is not any of those, such as use or unit).
   2. Language will have as many subtopics as sections now.
3. Title and subtitle will be compulsory.
4. Reference documents will include a definition which will be compulsory and, if possible, checked against actual definition in Rakudo.
5. Documentation will include no code that could produce side effects in the pre-compilation phase.

Internal metadata is good, and Pod6 does have a nice way of simply using it.