Next: , Previous: Naming Record Types, Up: Record Descriptors


2.4.3 Documenting Records

As well as a name, it is a good idea to provide a description of the record set. This is sometimes called the record set's documentation and is specified using the %doc field.

Whereas the name is usually short and can contain only alphanumeric characters and underscores, no such restriction applies to the documentation. The documentation is typically more verbose than the name provided by the %rec field and may contain arbitrary characters such as punctuation and parentheses. It is somewhat similar to a comment (see Comments), but it can be managed more easily in a programmatic way. Unlike a comment, the %doc field is recognized by tools such as recinf (see Invoking recinf) which processes record descriptors. For example, you might have two record sets with %rec and %doc fields as follows:

     %rec: Contact
     %doc: Family, friends and acquaintances (other than business).
     
     Name: Granny
     Phone: +12 23456677
     
     Name: Edwina
     Phone: +55 0923 8765
     
     
     %rec: Associate
     %doc: Colleagues and other business contacts
     
     Name: Karl Schmidt
     Phone: +49 88234566
     
     Name: Genevieve Curie
     Phone: +33 34 87 65