The preceding sections have outlined the notions of classes , attributes , and comment embedding . What we want to do is to borrow the syntax used by BibTEX¸bibtex for bibliography data base files, and encode the file header as comment body text in whatever syntax the programming language allows, but to do so in such a way that it can be readily recognized by both humans and computer programs.
Thus, in a Fortran file, for which comments run from a C in column 1 to end of line, our file header might look something like this:
C @Class{
C attribute1 = "value1",
C attribute2 = {value2},
C attribute3 = {value3 with {extra braces}},
C attribute4 = {value4 with "quotation marks"},
C attribute5 = "value5 with ""quotation marks""",
C ...
C }
The key to programmatic recognition of the header is the syntax name followed by an opening brace, zero or more attribute assignments, and a closing brace . The attribute value fields can be enclosed in quotation marks, or balanced braces, as shown above.
In the event that braces otherwise have special significance (such as in one of Pascal's comment forms), other distinct paired delimiters could be used; in the ASCII character set, this means parentheses, square brackets, or angle brackets.
The order of attributes is significant only in the event of duplications; in such a case, the last value assignment is the one to be used. Conventions for the order of attributes will make file headers easier to read, however.
Readers familiar with BibTEX¸citation tag will note the absence of a tag following the opening brace. In the bibliography data base application, the tag serves as a unique citation key that can be placed in other documents to uniquely identify the bibliographic reference. In the current application for file headers, we have no need of such a tag.
For languages in which comments continue from a start symbol to end of line, it will be useful, though not essential, to make the comment section containing the file header more visible. This can be done in a variety of ways, such as by doubling or tripling the comment start symbol, or putting a distinctive character sequence, like several asterisks or an arrow, ==>, after it. The essential point is that if each line begins with a comment start symbol, that same prefix must be used on every line of the header . Not only does this enhance visibility, it makes it possible for a relatively simple computer program to identify the first line of the header and recognize the comment syntax automatically, and then collect the remainder of the header by discarding identical comment prefixes¸commentprefix stripping from succeeding lines until a complete header has been collected.
Outline of file headers, Attribute descriptions, Putting it all together, Top