7. Metadata and Markup Review
The LDP uses a series of scripts to transform documents into their published format. In order for these scripts to work, documents must use valid markup and include specific metadata. Metadata is information about the document and includes author information, copyright, license and a revision history of the document.
At this time Metadata and Markup Reviews will be conducted by one of the Review Coordinators and will be the final of the three reviews for new documents. Upon successful completion of a Metadata and Markup Review, the Review Coordinator will update the document's version number to 1.0 and submit the document for publication in the collection.
7.1. Required Markup
Documents submitted to TLDP document repository must validate as one of the following:
DocBook XML version 4.2 (preferred), 4.1.2
DocBook SGML version 4.2, 4.1 or 3.x
LinuxDoc SGML
 | Authors are not required to submit documents in DocBook |
|---|---|
Authors are not required to submit their initial document in one of the required markup languages. A volunteer will be assigned to convert any document which is not submitted in valid markup. Authors must maintain their documents in one of the required formats. Help, of course, is available to authors. The main goal of The Linux Documentation Project is to provide quality documents, not to force authors to learn markup languages. |
7.2. Required Metadata
The following elements are all required:
articleinfo or bookinfo. If you are writing a shorter HOWTO (this will be most documents) you will need to use an articleinfo, if you are writing a longer guide you will need to use bookinfo.
title. Every document must contain a short, descriptive title. It should be reasonably unique; check other documents in the collection to make sure your document's title is distinctive from all other documents. Although it is not required, most "HOWTO" documents contain the word "HOWTO" in the title.
abstract. A short description of your document must be included in the abstract. This description is typically one or two sentences in length.
author. Every document must have an author. If there are multiple authors, you may use authorgroup. If the document was prepared by an organization with no individual author, please use authorcorp instead.
editor. Every new document must go through the review process and have a technical, language and metadata/markup review editor listed. In some cases two of the reviews may have been conducted by the same person. The name of the editor and the version their review was conducted on should be included. For more information about this markup, please read the notes in the Author Guide's Markup for Metadata.
pubdate. The date of publication for the document. The date should be in the ISO standard of YYYY-MM-DD.
copyright. Authors will always retain the copyright to any documents they submit to the LDP. Although it is not required, a copyright notice may be included. A license, however, is always required.
Revision history (revhistory). A summary of revisions should be included in the document. For more information about their markup, please read the notes in the Author Guide's Markup for Metadata.
The initial release of a document should be marked up as Version 1.0. Subsequent updates should increment the version number appropriately. The preferred format is Major.Minor.Bugfix, where each section is an integer. Some authors use Alan Cox style versions (for example 1.4pre-3) and some include additional information (for example 1.3beta). This is acceptable but not encouraged. The most important thing is that we have a version number so we know which version we are dealing with! Once a document goes through review it should advance in minor or bugfix version number, depending on the amount of change introduced.
License and Legal Notice. A license is required. The LDP currently accepts documents which are licensed under the GFDL, Creative Commons License and the LDP License. If you are using a license that is not listed it will need to be reviewed by our volunteers before the document is accepted. The full text of the license is required. A link is not sufficient. You may wish to include a disclaimer as part of the legal notice. A standard disclaimer is available from the Author Guide.
email. The LDP must be able to reach any author of any document via email. Email addresses should be included in the author tag, but may be included in the DocBook source as a comment. Documents without email address will not be accepted into the collection. If the LDP is unable to reach an author, the document may be removed from the collection.
Acknowledgements and Other Credits. Very few, if any, documents are written only by one person. It is good form to thank those who helped you with either the writing, research, testing or reviewing of your document. If someone added markup, or translated your document to another language they should also be given credit.