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