Credits

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the credit element to record who has contributed to a page or section. You can optionally use the type attribute to specify what types of contribution the person has made. The credit element also specifies copyright holders when used with the years element.

Notes

The credit element contains a name element, any number of email elements, and an optional years element. The credit element can also contain elements from external namespaces. The order of the child elements does not matter.
The credit element can occur in any info element.

The optional type attribute can be used to specify what type of contribution the person has made. The type attribute contains a space-separated list of credit types. The following values are recommended:

"author"	somebody responsible for writing content
"editor"	somebody who has provided reviews or editorial corrections
"copyright"	a person or entity which holds copyright on the work
"maintainer"	the person or entity currently responsible for the work
"collaborator"	somebody who has provided extensive rough information
"translator"	somebody who has translated the work into another language
"publisher"	a person or entity who distributes formatted copies

The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The credit element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use credit to mark up the name and email address of the author:

<credit type="author">
  <name>Shaun McCance</name>
  <email>shaunm@gnome.org</email>
</credit>

Include copyright information using credit:

<credit type="author copyright">
  <name>Shaun McCance</name>
  <email>shaunm@gnome.org</email>
  <years>2010</years>
</credit>

Using core Mallard elements alone, you can only record the name, email address, and copyright years. Mallard allows you to use elements from external namespaces to provide richer information. Use the FOAF page property to record a URL for a publisher:

<credit type="publisher">
  <name>Floss Manuals</name>
  <page xmlns="http://xmlns.com/foaf/0.1/">http://flossmanuals.net/</page>
</credit>

Processing Expectations

There are no specific processing expectations for the credit element. As an informational element, it is not necessarily displayed. Some tools, however, may choose to display credits at the bottom of a page, on a separate information page, or in a dialog.

When processing the children of a credit element, tools should select the child elements they understand and ignore all other child content.

Comparison to Other Formats

The credit element serves the purpose of the author, collab, editor, othercredit, and publisher elements in DocBook. DocBook does not have specific elements for maintainers and translators.

In DocBook, certain credit elements have highly structured content, whereas others allow simple inline text. In Mallard, all credits use simple structured content. Although Mallard does not provide child elements for everything that can be recorded in DocBook, elements from external namespaces may be used for any additional information that is needed.

The credit element also records copyright information. In this capacity, it is similar to the copyright element in DocBook.

The credit element serves the purpose of the author, authorinformation, publisher, and publisherinformation elements in DITA. DITA does not have specific elements for editors, maintainers, and translators.

In DITA, the author and publisher elements take inline text, and only record the name of a person or organization. The authorinformation element has structured content, and can record extensive information about a person. In this respect, the Mallard credit element is similar to the DITA authorinformation element. Although Mallard does not provide child elements for everything that can be recorded in DITA, elements from external namespaces may be used for any additional information that is needed.

The credit element also records copyright information. In this capacity, it is similar to the copyright element in DITA.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the credit element. The namespace declarations for this definition are on the page Pages.

mal_info_credit = element credit {
  mal_info_credit_attr,
  mal_info_credit_content
}
mal_info_credit_attr = (
  attribute type { xsd:NMTOKENS } ?,
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_info_credit_content = (
  mal_info_name &
  mal_info_email * &
  mal_info_years ? &
  mal_external *
)