411 lines
8.7 KiB
HTML
411 lines
8.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Metadata and Markup Review</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="Linux Documentation Project Reviewer HOWTO"
|
|
HREF="index.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Language Review"
|
|
HREF="languagereview.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Reporting Your Results"
|
|
HREF="reporting.html"></HEAD
|
|
><BODY
|
|
CLASS="sect1"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Linux Documentation Project Reviewer HOWTO</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="languagereview.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="reporting.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="metadatareview"
|
|
></A
|
|
>7. Metadata and Markup Review</H1
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>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.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="requiredmarkup"
|
|
></A
|
|
>7.1. Required Markup</H2
|
|
><P
|
|
>Documents submitted to TLDP document repository must validate as one of the following:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> DocBook XML version 4.2 (preferred), 4.1.2
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> DocBook SGML version 4.2, 4.1 or 3.x
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> LinuxDoc SGML
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="warning"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="warning"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/warning.gif"
|
|
HSPACE="5"
|
|
ALT="Warning"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
>Authors are not required to submit documents in DocBook</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>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.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="requiredmetadata"
|
|
></A
|
|
>7.2. Required Metadata</H2
|
|
><P
|
|
>The following elements are all required:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>articleinfo</TT
|
|
> or <TT
|
|
CLASS="sgmltag"
|
|
>bookinfo</TT
|
|
>. </B
|
|
>If you are writing a shorter HOWTO (this will be most documents) you will need to use an <TT
|
|
CLASS="sgmltag"
|
|
>articleinfo</TT
|
|
>, if you are writing a longer guide you will need to use <TT
|
|
CLASS="sgmltag"
|
|
>bookinfo</TT
|
|
>.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>title</TT
|
|
>. </B
|
|
>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 <SPAN
|
|
CLASS="QUOTE"
|
|
>"HOWTO"</SPAN
|
|
> documents contain the word <SPAN
|
|
CLASS="QUOTE"
|
|
>"HOWTO"</SPAN
|
|
> in the title.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>abstract</TT
|
|
>. </B
|
|
>A short description of your document must be included in the <TT
|
|
CLASS="sgmltag"
|
|
>abstract</TT
|
|
>. This description is typically one or two sentences in length.
|
|
</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>author</TT
|
|
>. </B
|
|
>Every document must have an author. If there are multiple authors, you may use <TT
|
|
CLASS="sgmltag"
|
|
>authorgroup</TT
|
|
>. If the document was prepared by an organization with no individual author, please use <TT
|
|
CLASS="sgmltag"
|
|
>authorcorp</TT
|
|
> instead.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>editor</TT
|
|
>. </B
|
|
>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 <I
|
|
CLASS="citetitle"
|
|
>Author Guide</I
|
|
>'s <A
|
|
HREF="http://tldp.org/LDP/LDP-Author-Guide/html/metadata-markup.html"
|
|
TARGET="_top"
|
|
>Markup for Metadata</A
|
|
>.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>pubdate</TT
|
|
>. </B
|
|
>The date of publication for the document. The date should be in the ISO standard of YYYY-MM-DD.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>copyright. </B
|
|
>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.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Revision history (<TT
|
|
CLASS="sgmltag"
|
|
>revhistory</TT
|
|
>). </B
|
|
>A summary of revisions should be included in the document. For more information about their markup, please read the notes in the <I
|
|
CLASS="citetitle"
|
|
>Author Guide</I
|
|
>'s <A
|
|
HREF="http://tldp.org/LDP/LDP-Author-Guide/html/metadata-markup.html"
|
|
TARGET="_top"
|
|
>Markup for Metadata</A
|
|
>.</P
|
|
></DIV
|
|
><P
|
|
>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 <EM
|
|
>have</EM
|
|
> 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.</P
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>License and Legal Notice. </B
|
|
>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 <I
|
|
CLASS="citetitle"
|
|
>Author Guide</I
|
|
>.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>email. </B
|
|
>The LDP must be able to reach any author of any document via email. Email addresses should be included in the <TT
|
|
CLASS="sgmltag"
|
|
>author</TT
|
|
> 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.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Acknowledgements and Other Credits. </B
|
|
>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.</P
|
|
></DIV
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="languagereview.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="reporting.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Language Review</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Reporting Your Results</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |