915 lines
47 KiB
Plaintext
915 lines
47 KiB
Plaintext
Linux Documentation Project Reviewer HOWTO
|
||
|
||
Emma Jane Hogbin
|
||
|
||
[http://www.xtrinsic.com] xtrinsic
|
||
|
||
<emmajane@xtrinsic.com>
|
||
|
||
David Merrill
|
||
|
||
david -AT- lupercalia.net
|
||
|
||
Joy Yokley
|
||
|
||
<jyokley@us.ibm.com>
|
||
|
||
2004-04-19
|
||
Revision History
|
||
Revision 1.4.2 2004-05-24 Revised by: EJH
|
||
Corrected spelling mistakes.
|
||
Revision 1.4.1 2004-04-19 Revised by: EJH
|
||
Minor updates to the language and markup, emphasizing the reporting
|
||
procedures for reviews. Also changed the order of the reviews to reflect
|
||
actual procedure (technical, language and finally metadata).
|
||
Revision 1.4 2004-04-18 Revised by: EJH
|
||
Updated the language review: clarified use of capitals, and added a new
|
||
requirement that Latin abbreviations always use their English counterpart
|
||
instead.
|
||
Revision 1.3 2004-01-31 Revised by: EJH
|
||
Added the metadata and markup review information.
|
||
Revision 1.2 2003-11-09 Revised by: TMM
|
||
Updated content, URLs, mailing lists, converted to XML.
|
||
Revision 1.1 2001-05-12 Revised by: DCM
|
||
Minor bugfixes.
|
||
Revision 1.0 2001-05-01 Revised by: jy
|
||
Initial release.
|
||
|
||
|
||
This document will help you review LDP documentation. It includes procedures
|
||
and techniques for the review process of all new, and existing, LDP
|
||
documents.
|
||
|
||
-----------------------------------------------------------------------------
|
||
Table of Contents
|
||
1. Introduction
|
||
1.1. Copyright and License
|
||
1.2. Acknowledgements
|
||
|
||
|
||
2. Reviewing Newly Submitted Documentation
|
||
3. Reviewing Existing Documentation
|
||
3.1. Choosing a Document
|
||
3.2. License Issues
|
||
3.3. Working With the Latest Version
|
||
3.4. Picking a Review to Conduct
|
||
|
||
|
||
4. Peer Review
|
||
5. Technical Accuracy Review
|
||
6. Language Review
|
||
7. Metadata and Markup Review
|
||
7.1. Required Markup
|
||
7.2. Required Metadata
|
||
|
||
|
||
8. Reporting Your Results
|
||
A. GNU Free Documentation License
|
||
A.1. 0. PREAMBLE
|
||
A.2. 1. APPLICABILITY AND DEFINITIONS
|
||
A.3. 2. VERBATIM COPYING
|
||
A.4. 3. COPYING IN QUANTITY
|
||
A.5. 4. MODIFICATIONS
|
||
A.6. 5. COMBINING DOCUMENTS
|
||
A.7. 6. COLLECTIONS OF DOCUMENTS
|
||
A.8. 7. AGGREGATION WITH INDEPENDENT WORKS
|
||
A.9. 8. TRANSLATION
|
||
A.10. 9. TERMINATION
|
||
A.11. 10. FUTURE REVISIONS OF THIS LICENSE
|
||
A.12. Addendum
|
||
|
||
|
||
|
||
1. Introduction
|
||
|
||
The LDP Review Project is a "working group" of the Linux Documentation
|
||
Project, whose goal is to improve the quality of the LDP's documentation. We
|
||
are approaching that goal from two different angles: a review of newly
|
||
submitted documentation, and a review of existing documentation. We are open
|
||
to your suggestions for improvement.
|
||
|
||
We have a mailing list established for editors; instructions to subscribe are
|
||
at http://www.tldp.org/mailinfo.html#maillists.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.1. Copyright and License
|
||
|
||
This document is copyright 2001 by David C. Merrill, Ph.D., and copyright
|
||
2004 by Emma Jane Hogbin.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document under
|
||
the terms of the GNU Free Documentation License, Version 1.1 or any later
|
||
version published by the Free Software Foundation; with no invariant
|
||
sections, no front-cover texts and no back-cover texts. A copy of the license
|
||
is included in the section entitled "GNU Free Documentation License".
|
||
|
||
Send feedback to <discuss@en.tldp.org>. Please reference the title of this
|
||
document in your email.
|
||
-----------------------------------------------------------------------------
|
||
|
||
1.2. Acknowledgements
|
||
|
||
The original version of this document was written in 2001 by Joy Yokley and
|
||
David C. Merrill, Ph.D.. Tabatha Marshall updated the content and converted
|
||
the document to DocBook XML in November 2003. Emma Jane Hogbin added the
|
||
section on Metadata and Markup Reviews in January 2004 and is the current
|
||
maintainer of the document.
|
||
-----------------------------------------------------------------------------
|
||
|
||
2. Reviewing Newly Submitted Documentation
|
||
|
||
This review project will continue throughout the life of the LDP. The process
|
||
will act as a front-end quality assurance review for new documentation which
|
||
is submitted to the LDP. Ideally documents will be reviewed within one week
|
||
of their submission to the LDP.
|
||
|
||
Coordinators of this effort will announce to the list or notify individual
|
||
review members of new document submissions. The coordinators will try to
|
||
funnel documents to reviewers who have knowledge in the same technical area
|
||
as the documentation. If the reviewer is not a technical expert in that
|
||
particular area and needs technical questions answered, there will be a
|
||
technical expert designated who will be able to address any technical issues
|
||
or questions.
|
||
|
||
Once reviewers have agreed to work on a document, they will have one week
|
||
to complete the review. If they are not able to complete the review within
|
||
that time frame, they will need to let the coordinator know of their
|
||
difficulties so that the author can be notified of the problem. Because these
|
||
reviews need to be conducted quickly, there will be times when reviewers will
|
||
be more able to accept review work.
|
||
|
||
When reviewing newly submitted documents, refer to the Section 5 and Section
|
||
6 portions of this guide for the types of information to verify and correct.
|
||
As a reviewer, you will need to check the documents out of the CVS [1] and
|
||
make any necessary changes. If changes are extensive or if the document has
|
||
glaringly and fundamentally fatal errors, contact a coordinator and let them
|
||
know what the problems are. Once changes are made, the reviewer will update
|
||
the minor version number, add a new entry to the revision history, and
|
||
include their name as an "editor" of the document. These changes will then be
|
||
submitted to the CVS, and an original copy will be sent to the author of the
|
||
document if the author does not have CVS access.
|
||
-----------------------------------------------------------------------------
|
||
|
||
3. Reviewing Existing Documentation
|
||
|
||
This project will focus on reviewing documentation that already exists at the
|
||
LDP. Our goal is to implement a quality management program that makes sure we
|
||
are supplying up-to-date, accurate, easily read documentation. This process
|
||
will be ongoing throughout the life of the LDP. Initially, we will try to
|
||
review all documents currently on the LDP. Once we have made our way through
|
||
existing documents, we will schedule dates for follow-up reviews. By
|
||
continually reviewing the documents throughout their life at the LDP, we help
|
||
make sure readers have the best possible experience with Linux documentation.
|
||
|
||
In addition to the primary goal of improving the quality of the documentation
|
||
itself, we will also be gathering data about the collection for storage in
|
||
some sort of database to facilitate the ongoing management of the collection.
|
||
However, this stage of the review is still being defined; details about the
|
||
specifics and how this data will be measured will be added in the future.
|
||
|
||
Below are some general guidelines that you should follow before you begin
|
||
reviewing existing documentation for the LDP. Please try to have document
|
||
reviews completed within two weeks of the time you sign up to review a
|
||
document.
|
||
-----------------------------------------------------------------------------
|
||
|
||
3.1. Choosing a Document
|
||
|
||
There are many documents that need review. The most important thing is that
|
||
you coordinate your work with the other reviewers. To coordinate the effort,
|
||
we have set up a mailing list for reviewers.
|
||
|
||
Notify the editor list (instructions for subscribing are at http://
|
||
www.tldp.org/mailinfo.html#maillists) before you begin to review a document.
|
||
We want to make sure your work is directed where it is most needed and where
|
||
it will be most useful. Of course, you may have a particular area of
|
||
expertise and that will dictate your choice to some extent. You can ask on
|
||
the list for an assignment, or you can select one for yourself and just let
|
||
the mailing list know what you're doing.
|
||
-----------------------------------------------------------------------------
|
||
|
||
3.2. License Issues
|
||
|
||
Make sure you have the legal right to work on the document. If it is licensed
|
||
under a free license that specifically grants such rights, you are fine. If
|
||
not, you need to contact the author and get permission.
|
||
|
||
If you do not plan to actually change any of the content, but simply report
|
||
on the document's status, then you don't need permission, regardless of
|
||
license. Of course, it is still polite, and advisable, to write the author
|
||
anyway.
|
||
|
||
If a document is missing a copyright and/or license, it's recommended you
|
||
advise the author to choose and apply one. More information on licensing is
|
||
available in Section 7
|
||
-----------------------------------------------------------------------------
|
||
|
||
3.3. Working With the Latest Version
|
||
|
||
Make sure the copy you are reviewing is the most current.
|
||
|
||
If your document includes a URL to an official homepage, visit that page and
|
||
see if it displays the same version number. If you find the same version
|
||
number, you are fine. If you find a newer version number, write to the author
|
||
and ask him or her to please submit the newer version to you.
|
||
-----------------------------------------------------------------------------
|
||
|
||
3.4. Picking a Review to Conduct
|
||
|
||
There are many different ways a document can be reviewed, and you may have
|
||
the skills to do only one or two types of reviews. It is sometimes useful
|
||
(and easier) to do each review as a separate pass through the document; Your
|
||
Mileage May Vary.
|
||
|
||
The following sections explain the various types of reviews we are
|
||
conducting. Use these sections as a guide to help you choose the type of
|
||
review to conduct and to help you conduct the review itself. Again, when you
|
||
post your review choice to the review list, please specify the type of review
|
||
you would like to be responsible for.
|
||
-----------------------------------------------------------------------------
|
||
|
||
4. Peer Review
|
||
|
||
When an author submits a new document to the LDP, someone monitoring the
|
||
submission email list will advise the author to post his draft to the
|
||
discussion list for an initial peer review, prior to publication. Besides
|
||
determining whether the document thoroughly covers the subject matter, peers
|
||
may also point out similar work already in the document collection, in which
|
||
case the new author might want to contact the maintainer of the existing
|
||
work.
|
||
|
||
As a member of the review team, you will recognize a peer review document as
|
||
one the author has submitted to the discussion list, specifically requesting
|
||
feedback for inclusion of their HOWTO in the collection. This review can be
|
||
performed by anyone subscribed to the discussion list ([www.tldp.org/
|
||
mailinfo.html#maillists] www.tldp.org/mailinfo.html#maillists).
|
||
-----------------------------------------------------------------------------
|
||
|
||
5. Technical Accuracy Review
|
||
|
||
Make sure the facts as stated in the document are correct, helpful, and on
|
||
topic.
|
||
|
||
To do a technical accuracy review, you really need to know your subject
|
||
matter, probably as well or better than the original author. Use whatever
|
||
other documentation is available for your subject, including man pages,
|
||
program documentation, other printed books, etc. You might also use mailing
|
||
lists on the topic, asking for third parties to verify certain facts of which
|
||
you are in doubt.
|
||
|
||
When doing this type of review, consider if the information is only valid for
|
||
certain types of hardware or software. If this is the case, make sure to note
|
||
the limitations of the document within the document, either within the
|
||
abstract or as a note at the beginning of the document. For example, if the
|
||
solutions in the document only are relevant for one type or brand of
|
||
hardware, make sure that that limitation is defined. This will keep readers
|
||
from trying to apply a certain type of technology to an application or
|
||
situation where it will not work.
|
||
|
||
The same should apply for the prerequisite knowledge of the reader. If prior
|
||
knowledge of a subject is assumed or required, the author should say so
|
||
somewhere at the beginning of the document, and it's helpful to ask that
|
||
authors provide a Resource section for further reading, to bring readers that
|
||
much closer to the required information.
|
||
-----------------------------------------------------------------------------
|
||
|
||
6. Language Review
|
||
|
||
Because writers come from all types of backgrounds, there may be problems
|
||
within the documentation that need to be fixed. Writers may be very
|
||
knowledgeable in their subject areas but not great writers, or they may be
|
||
excellent writers but not completely fluent in the language of the document.
|
||
The language review addresses these types of problems by focusing on language
|
||
issues that make the document easier for the user to read and understand.
|
||
Some of the problems that may occur within the document are poor sentence
|
||
structure, grammar, organization, clarity, and spelling.
|
||
|
||
If you are doing a language review, you should be fluent in the language and
|
||
the structure of the language. You want to consider both the logic and
|
||
grammar of the document. Your primary goal in a language review is to
|
||
identify and correct areas that could lead to confusion for the reader/user
|
||
of the document. To this end, you can most certainly use language and grammar
|
||
references such as dictionaries and handbooks when in doubt.
|
||
|
||
Although this review does address the structure and delivery of the language,
|
||
you should not attempt to purge the document of individuality and personality
|
||
in an attempt to make it "sound better" or more technical. Stilted, humorless
|
||
language and structures are not the goals here. Again, your goal should be to
|
||
make the document clear, unambiguous, and correct in spelling and grammar.
|
||
|
||
Items to evaluate:
|
||
|
||
* Spelling. Spelling should conform to a standardized English spelling of
|
||
terms. For words that are new to the language and not yet standardized
|
||
(for example technical Linux terminology that is generally accepted in
|
||
the community), follow the most common spelling for the term.
|
||
|
||
Note Note
|
||
Because there are two generally accepted forms of English, this
|
||
review should not privilege American English spellings over British
|
||
English spellings, or vice-versa. For example, if the author is
|
||
writes British English and uses the word "realise" you should not
|
||
change the spelling of the word to "realize" just because you speak/
|
||
write American English.
|
||
|
||
* Grammar. For the purposes of this review, grammar should address issues
|
||
such as standards of subject/verb agreement, pronoun/antecedent
|
||
agreement, etc. One of the common and confusing mistakes made in HOWTOs
|
||
is unclear pronoun antecedents.
|
||
|
||
For example, to say, "You will need to set several parameters in the
|
||
config file to make it compile correctly. The ones you choose to set make
|
||
a big difference." In this example it sounds like the config file is what
|
||
is compiling and it takes a re-reading of the phrase for it to be clear
|
||
that "The ones" refers to the parameters.
|
||
|
||
Along these same lines, many authors writing for the LDP use smiley faces
|
||
and exclamation points where they would never be accepted in formal
|
||
documentation or grammar handbooks. The general rule to follow at this
|
||
time is to leave the smiley faces and gratuitous punctuation marks in
|
||
place unless they interfere with the reader's understanding of the
|
||
concepts being explained. The rationale behind this is to protect the
|
||
more conversational tone of the LDP documentation.
|
||
|
||
* Use of capital letters. The word "HOWTO" should always be in full caps
|
||
with no hyphen. The document's title and section headings may follow one
|
||
of two conventions, but must be consistent throughout. Titles may either
|
||
capitalize only the first word, or may capitalize each word. In the
|
||
second case the only words not capitalized in a title are prepositions,
|
||
articles, and proper nouns which would not be capitalized otherwise (for
|
||
example: insmod). Other capitalization should follow rules of standard
|
||
English.
|
||
|
||
* Clarity. Judgements on clarity are sometimes difficult to make. One
|
||
successful strategy in evaluating clarity is asking the question "If I
|
||
did not already know this information, would the explanation be clear
|
||
from this document." If it is confusing to you and you already generally
|
||
understand what the author is trying to say, then there is a good chance
|
||
that the explanation is really confusing for someone reading the document
|
||
for the first time. If you run across this situation, and you don't
|
||
really know how to correct the technical explanation, or you are afraid
|
||
your changes might affect the meaning of the document, ask for help from
|
||
a technical expert. If no technical expert is available or no one
|
||
responds to your requests, note the needed changes in the review and mark
|
||
that these concerns need to be addressed in the technical review.
|
||
|
||
* Organization. In some cases the document would really benefit from a
|
||
different structure. You should address these issues when they interfere
|
||
with the understanding of the information within the document. If a
|
||
document gives background information after a procedure has been
|
||
performed, this may well be too late for the reader to fully consider the
|
||
information he or she needs before performing the task. Look for document
|
||
organization that might confuse or mislead the reader. These will be the
|
||
types of issues you want to address. Once these are identified, it may be
|
||
worthwhile to let the author know your rationale and discuss major
|
||
changes with him or her.
|
||
|
||
* Sentence Structure. To some extent, sentence structure issues are
|
||
discussed in the grammar section; however, there are some additional
|
||
issues that are not grammatically incorrect but do interfere with the
|
||
readers comprehension of the material. One of the most noticeable of
|
||
these is stacked prepositional phrases. Stacked prepositional phrases
|
||
become a problem when the document's readability suffers because it
|
||
becomes less and less clear what the subject and action of the sentence
|
||
are. In some cases more precise descriptors are needed or sentences need
|
||
to be changed from one long sentence that is hard to comprehend, to two
|
||
or three more easily read sentences.
|
||
|
||
* Readability. This area is somewhat subjective. What passes for fairly
|
||
readable material to one person might be confusing to someone else.
|
||
Because this is a value judgement you should be cautious when marking up
|
||
an author's work for readability. Realize when basing a judgement on
|
||
readability that you might be dealing with preferences of style. At this
|
||
point in time within the LDP, there is no set style or stylistic rules
|
||
that authors need to follow. In evaluating readability you must consider
|
||
whether or not the way the document is written truly interferes with the
|
||
readers understanding of the information. If the answer you come up with
|
||
is "No, but it doesn't sound like I think it should." then you should
|
||
probably not re-write the text to make it sound better to you.
|
||
|
||
* Title. The title should be in proper title case. The general principle
|
||
for this is that all words are capitalized in a title except prepositions
|
||
and articles (an article will be capitalized if it is the first word in
|
||
the title). The word HOWTO should be in all capital letters. There should
|
||
be no hyphens within the word HOWTO. The version should not be included
|
||
in the title.
|
||
|
||
* Date Formats. Dates should be in standard ISO format, which is
|
||
YYYY-MM-DD.
|
||
|
||
* Uniform Use of Terms. Because the HOWTO you are reviewing is probably
|
||
filled with new information for the reader, it is important that the
|
||
terms discussed throughout the document be uniform. For example,
|
||
referring to a part or parameter in one section of the document by one
|
||
name and then calling it by another name (or an abbreviation that has not
|
||
be explained) in another part of the document is confusing for the
|
||
reader. Making sure that terms are the same throughout the document goes
|
||
a long way in helping the reader understand the documentation.
|
||
|
||
* Definitions of Acronyms or Slang. Terminology and language within the
|
||
realm of computer technology changes rapidly. In reviewing documents you
|
||
may find that many of the terms that are being discussed are not valid
|
||
words in any dictionary or technical reference that you are familiar
|
||
with. In this case you will need to search on terms and find if they are,
|
||
in fact, terminology that is accepted in the general Linux community.
|
||
Terms that are less familiar should be defined immediately following the
|
||
first instance of the term. Slang should be replaced with more common
|
||
terminology if the slang will causes the reader to be confused by the
|
||
connotation or denotation of the term. Remember that readers using the
|
||
document may not come to English as a primary language and, therefore,
|
||
you should do your best to make sure that the document is as easy to
|
||
understand as possible.
|
||
|
||
* Latin abbreviations. Avoid using abbreviations. e.g. (for example), et
|
||
al. (and others), etc (and so on) and i.e. (that is) should always use
|
||
the English equivalent.
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
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
|
||
|
||
|
||
Warning 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 [http://tldp.org/LDP/LDP-Author-Guide/html/
|
||
metadata-markup.html] 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 [http://tldp.org/LDP/LDP-Author-Guide/html/
|
||
metadata-markup.html] 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.
|
||
|
||
|
||
-----------------------------------------------------------------------------
|
||
8. Reporting Your Results
|
||
|
||
Once you have completed your review of a document, you should send the
|
||
updated file and your results back to the Review Coordinator [2] , and advise
|
||
the working group you've completed the review. A summary of your findings
|
||
should be included in the body of the email. If the reviewer has access to
|
||
the CVS, and permission of the author to submit the changes directly, the
|
||
reviewer may email the Review Coordinator with only a summary of findings and
|
||
a note that the document was updated in the CVS.
|
||
|
||
If you have made any modifications to the document, also send your updates to
|
||
the author or maintainer, as well as the LDP submission list, which is at
|
||
submit@en.tldp.org. The subject line should be the title of the document. In
|
||
the body of your email, please include a note which says something to the
|
||
effect of, "I am a reviewer for the LDP and am submitting an updated copy of
|
||
this document on behalf of the author."
|
||
|
||
Note Updates should not be sent to the discuss list.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A. GNU Free Documentation License
|
||
|
||
A.1. 0. PREAMBLE
|
||
|
||
The purpose of this License is to make a manual, textbook, or other written
|
||
document "free" in the sense of freedom: to assure everyone the effective
|
||
freedom to copy and redistribute it, with or without modifying it, either
|
||
commercially or noncommercially. Secondarily, this License preserves for the
|
||
author and publisher a way to get credit for their work, while not being
|
||
considered responsible for modifications made by others.
|
||
|
||
This License is a kind of "copyleft", which means that derivative works of
|
||
the document must themselves be free in the same sense. It complements the
|
||
GNU General Public License, which is a copyleft license designed for free
|
||
software.
|
||
|
||
We have designed this License in order to use it for manuals for free
|
||
software, because free software needs free documentation: a free program
|
||
should come with manuals providing the same freedoms that the software does.
|
||
But this License is not limited to software manuals; it can be used for any
|
||
textual work, regardless of subject matter or whether it is published as a
|
||
printed book. We recommend this License principally for works whose purpose
|
||
is instruction or reference.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.2. 1. APPLICABILITY AND DEFINITIONS
|
||
|
||
This License applies to any manual or other work that contains a notice
|
||
placed by the copyright holder saying it can be distributed under the terms
|
||
of this License. The "Document", below, refers to any such manual or work.
|
||
Any member of the public is a licensee, and is addressed as "you".
|
||
|
||
A "Modified Version" of the Document means any work containing the Document
|
||
or a portion of it, either copied verbatim, or with modifications and/or
|
||
translated into another language.
|
||
|
||
A "Secondary Section" is a named appendix or a front-matter section of the
|
||
Document that deals exclusively with the relationship of the publishers or
|
||
authors of the Document to the Document's overall subject (or to related
|
||
matters) and contains nothing that could fall directly within that overall
|
||
subject. (For example, if the Document is in part a textbook of mathematics,
|
||
a Secondary Section may not explain any mathematics.) The relationship could
|
||
be a matter of historical connection with the subject or with related
|
||
matters, or of legal, commercial, philosophical, ethical or political
|
||
position regarding them.
|
||
|
||
The "Invariant Sections" are certain Secondary Sections whose titles are
|
||
designated, as being those of Invariant Sections, in the notice that says
|
||
that the Document is released under this License.
|
||
|
||
The "Cover Texts" are certain short passages of text that are listed, as
|
||
Front-Cover Texts or Back-Cover Texts, in the notice that says that the
|
||
Document is released under this License.
|
||
|
||
A "Transparent" copy of the Document means a machine-readable copy,
|
||
represented in a format whose specification is available to the general
|
||
public, whose contents can be viewed and edited directly and
|
||
straightforwardly with generic text editors or (for images composed of
|
||
pixels) generic paint programs or (for drawings) some widely available
|
||
drawing editor, and that is suitable for input to text formatters or for
|
||
automatic translation to a variety of formats suitable for input to text
|
||
formatters. A copy made in an otherwise Transparent file format whose markup
|
||
has been designed to thwart or discourage subsequent modification by readers
|
||
is not Transparent. A copy that is not "Transparent" is called "Opaque".
|
||
|
||
Examples of suitable formats for Transparent copies include plain ASCII
|
||
without markup, Texinfo input format, LaTeX input format, SGML or XML using a
|
||
publicly available DTD, and standard-conforming simple HTML designed for
|
||
human modification. Opaque formats include PostScript, PDF, proprietary
|
||
formats that can be read and edited only by proprietary word processors, SGML
|
||
or XML for which the DTD and/or processing tools are not generally available,
|
||
and the machine-generated HTML produced by some word processors for output
|
||
purposes only.
|
||
|
||
The "Title Page" means, for a printed book, the title page itself, plus
|
||
such following pages as are needed to hold, legibly, the material this
|
||
License requires to appear in the title page. For works in formats which do
|
||
not have any title page as such, "Title Page" means the text near the most
|
||
prominent appearance of the work's title, preceding the beginning of the body
|
||
of the text.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.3. 2. VERBATIM COPYING
|
||
|
||
You may copy and distribute the Document in any medium, either commercially
|
||
or noncommercially, provided that this License, the copyright notices, and
|
||
the license notice saying this License applies to the Document are reproduced
|
||
in all copies, and that you add no other conditions whatsoever to those of
|
||
this License. You may not use technical measures to obstruct or control the
|
||
reading or further copying of the copies you make or distribute. However, you
|
||
may accept compensation in exchange for copies. If you distribute a large
|
||
enough number of copies you must also follow the conditions in section 3.
|
||
|
||
You may also lend copies, under the same conditions stated above, and you
|
||
may publicly display copies.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.4. 3. COPYING IN QUANTITY
|
||
|
||
If you publish printed copies of the Document numbering more than 100, and
|
||
the Document's license notice requires Cover Texts, you must enclose the
|
||
copies in covers that carry, clearly and legibly, all these Cover Texts:
|
||
Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover.
|
||
Both covers must also clearly and legibly identify you as the publisher of
|
||
these copies. The front cover must present the full title with all words of
|
||
the title equally prominent and visible. You may add other material on the
|
||
covers in addition. Copying with changes limited to the covers, as long as
|
||
they preserve the title of the Document and satisfy these conditions, can be
|
||
treated as verbatim copying in other respects.
|
||
|
||
If the required texts for either cover are too voluminous to fit legibly,
|
||
you should put the first ones listed (as many as fit reasonably) on the
|
||
actual cover, and continue the rest onto adjacent pages.
|
||
|
||
If you publish or distribute Opaque copies of the Document numbering more
|
||
than 100, you must either include a machine-readable Transparent copy along
|
||
with each Opaque copy, or state in or with each Opaque copy a
|
||
publicly-accessible computer-network location containing a complete
|
||
Transparent copy of the Document, free of added material, which the general
|
||
network-using public has access to download anonymously at no charge using
|
||
public-standard network protocols. If you use the latter option, you must
|
||
take reasonably prudent steps, when you begin distribution of Opaque copies
|
||
in quantity, to ensure that this Transparent copy will remain thus accessible
|
||
at the stated location until at least one year after the last time you
|
||
distribute an Opaque copy (directly or through your agents or retailers) of
|
||
that edition to the public.
|
||
|
||
It is requested, but not required, that you contact the authors of the
|
||
Document well before redistributing any large number of copies, to give them
|
||
a chance to provide you with an updated version of the Document.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.5. 4. MODIFICATIONS
|
||
|
||
You may copy and distribute a Modified Version of the Document under the
|
||
conditions of sections 2 and 3 above, provided that you release the Modified
|
||
Version under precisely this License, with the Modified Version filling the
|
||
role of the Document, thus licensing distribution and modification of the
|
||
Modified Version to whoever possesses a copy of it. In addition, you must do
|
||
these things in the Modified Version:
|
||
|
||
* A. Use in the Title Page (and on the covers, if any) a title distinct
|
||
from that of the Document, and from those of previous versions (which
|
||
should, if there were any, be listed in the History section of the
|
||
Document). You may use the same title as a previous version if the
|
||
original publisher of that version gives permission.
|
||
|
||
* B. List on the Title Page, as authors, one or more persons or entities
|
||
responsible for authorship of the modifications in the Modified Version,
|
||
together with at least five of the principal authors of the Document (all
|
||
of its principal authors, if it has less than five).
|
||
|
||
* C. State on the Title Page the name of the publisher of the Modified
|
||
Version, as the publisher.
|
||
|
||
* D. Preserve all the copyright notices of the Document.
|
||
|
||
* E. Add an appropriate copyright notice for your modifications adjacent to
|
||
the other copyright notices.
|
||
|
||
* F. Include, immediately after the copyright notices, a license notice
|
||
giving the public permission to use the Modified Version under the terms
|
||
of this License, in the form shown in the Addendum below.
|
||
|
||
* G. Preserve in that license notice the full lists of Invariant Sections
|
||
and required Cover Texts given in the Document's license notice.
|
||
|
||
* H. Include an unaltered copy of this License.
|
||
|
||
* I. Preserve the section entitled "History", and its title, and add to it
|
||
an item stating at least the title, year, new authors, and publisher of
|
||
the Modified Version as given on the Title Page. If there is no section
|
||
entitled "History" in the Document, create one stating the title, year,
|
||
authors, and publisher of the Document as given on its Title Page, then
|
||
add an item describing the Modified Version as stated in the previous
|
||
sentence.
|
||
|
||
* J. Preserve the network location, if any, given in the Document for
|
||
public access to a Transparent copy of the Document, and likewise the
|
||
network locations given in the Document for previous versions it was
|
||
based on. These may be placed in the "History" section. You may omit a
|
||
network location for a work that was published at least four years before
|
||
the Document itself, or if the original publisher of the version it
|
||
refers to gives permission.
|
||
|
||
* K. In any section entitled "Acknowledgements" or "Dedications", preserve
|
||
the section's title, and preserve in the section all the substance and
|
||
tone of each of the contributor acknowledgements and/or dedications given
|
||
therein.
|
||
|
||
* L. Preserve all the Invariant Sections of the Document, unaltered in
|
||
their text and in their titles. Section numbers or the equivalent are not
|
||
considered part of the section titles.
|
||
|
||
* M. Delete any section entitled "Endorsements". Such a section may not be
|
||
included in the Modified Version.
|
||
|
||
* N. Do not retitle any existing section as "Endorsements" or to conflict
|
||
in title with any Invariant Section.
|
||
|
||
|
||
If the Modified Version includes new front-matter sections or appendices
|
||
that qualify as Secondary Sections and contain no material copied from the
|
||
Document, you may at your option designate some or all of these sections as
|
||
invariant. To do this, add their titles to the list of Invariant Sections in
|
||
the Modified Version's license notice. These titles must be distinct from any
|
||
other section titles.
|
||
|
||
You may add a section entitled "Endorsements", provided it contains nothing
|
||
but endorsements of your Modified Version by various parties--for example,
|
||
statements of peer review or that the text has been approved by an
|
||
organization as the authoritative definition of a standard.
|
||
|
||
You may add a passage of up to five words as a Front-Cover Text, and a
|
||
passage of up to 25 words as a Back-Cover Text, to the end of the list of
|
||
Cover Texts in the Modified Version. Only one passage of Front-Cover Text and
|
||
one of Back-Cover Text may be added by (or through arrangements made by) any
|
||
one entity. If the Document already includes a cover text for the same cover,
|
||
previously added by you or by arrangement made by the same entity you are
|
||
acting on behalf of, you may not add another; but you may replace the old
|
||
one, on explicit permission from the previous publisher that added the old
|
||
one.
|
||
|
||
The author(s) and publisher(s) of the Document do not by this License give
|
||
permission to use their names for publicity for or to assert or imply
|
||
endorsement of any Modified Version .
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.6. 5. COMBINING DOCUMENTS
|
||
|
||
You may combine the Document with other documents released under this
|
||
License, under the terms defined in section 4 above for modified versions,
|
||
provided that you include in the combination all of the Invariant Sections of
|
||
all of the original documents, unmodified, and list them all as Invariant
|
||
Sections of your combined work in its license notice.
|
||
|
||
The combined work need only contain one copy of this License, and multiple
|
||
identical Invariant Sections may be replaced with a single copy. If there are
|
||
multiple Invariant Sections with the same name but different contents, make
|
||
the title of each such section unique by adding at the end of it, in
|
||
parentheses, the name of the original author or publisher of that section if
|
||
known, or else a unique number. Make the same adjustment to the section
|
||
titles in the list of Invariant Sections in the license notice of the
|
||
combined work.
|
||
|
||
In the combination, you must combine any sections entitled "History" in the
|
||
various original documents, forming one section entitled "History"; likewise
|
||
combine any sections entitled "Acknowledgements", and any sections entitled
|
||
"Dedications". You must delete all sections entitled "Endorsements."
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.7. 6. COLLECTIONS OF DOCUMENTS
|
||
|
||
You may make a collection consisting of the Document and other documents
|
||
released under this License, and replace the individual copies of this
|
||
License in the various documents with a single copy that is included in the
|
||
collection, provided that you follow the rules of this License for verbatim
|
||
copying of each of the documents in all other respects.
|
||
|
||
You may extract a single document from such a collection, and dispbibute it
|
||
individually under this License, provided you insert a copy of this License
|
||
into the extracted document, and follow this License in all other respects
|
||
regarding verbatim copying of that document.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.8. 7. AGGREGATION WITH INDEPENDENT WORKS
|
||
|
||
A compilation of the Document or its derivatives with other separate and
|
||
independent documents or works, in or on a volume of a storage or
|
||
distribution medium, does not as a whole count as a Modified Version of the
|
||
Document, provided no compilation copyright is claimed for the compilation.
|
||
Such a compilation is called an "aggregate", and this License does not apply
|
||
to the other self-contained works thus compiled with the Document , on
|
||
account of their being thus compiled, if they are not themselves derivative
|
||
works of the Document. If the Cover Text requirement of section 3 is
|
||
applicable to these copies of the Document, then if the Document is less than
|
||
one quarter of the entire aggregate, the Document's Cover Texts may be placed
|
||
on covers that surround only the Document within the aggregate. Otherwise
|
||
they must appear on covers around the whole aggregate.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.9. 8. TRANSLATION
|
||
|
||
Translation is considered a kind of modification, so you may distribute
|
||
translations of the Document under the terms of section 4. Replacing
|
||
Invariant Sections with translations requires special permission from their
|
||
copyright holders, but you may include translations of some or all Invariant
|
||
Sections in addition to the original versions of these Invariant Sections.
|
||
You may include a translation of this License provided that you also include
|
||
the original English version of this License. In case of a disagreement
|
||
between the translation and the original English version of this License, the
|
||
original English version will prevail.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.10. 9. TERMINATION
|
||
|
||
You may not copy, modify, sublicense, or distribute the Document except as
|
||
expressly provided for under this License. Any other attempt to copy, modify,
|
||
sublicense or distribute the Document is void, and will automatically
|
||
terminate your rights under this License. However, parties who have received
|
||
copies, or rights, from you under this License will not have their licenses
|
||
terminated so long as such parties remain in full compliance.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.11. 10. FUTURE REVISIONS OF THIS LICENSE
|
||
|
||
The Free Software Foundation may publish new, revised versions of the GNU
|
||
Free Documentation License from time to time. Such new versions will be
|
||
similar in spirit to the present version, but may differ in detail to address
|
||
new problems or concerns. See [http://www.gnu.org/copyleft] http://
|
||
www.gnu.org/copyleft/.
|
||
|
||
Each version of the License is given a distinguishing version number. If
|
||
the Document specifies that a particular numbered version of this License "or
|
||
any later version" applies to it, you have the option of following the terms
|
||
and conditions either of that specified version or of any later version that
|
||
has been published (not as a draft) by the Free Software Foundation. If the
|
||
Document does not specify a version number of this License, you may choose
|
||
any version ever published (not as a draft) by the Free Software Foundation.
|
||
-----------------------------------------------------------------------------
|
||
|
||
A.12. Addendum
|
||
|
||
To use this License in a document you have written, include a copy of the
|
||
License in the document and put the following copyright and license notices
|
||
just after the title page:
|
||
|
||
|
||
Copyright © YEAR YOUR NAME.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.1 or any
|
||
later version published by the Free Software Foundation; with the
|
||
Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts
|
||
being LIST, and with the Back-Cover Texts being LIST. A copy of the
|
||
license is included in the section entitled "GNU Free Documentation
|
||
License".
|
||
|
||
If you have no Invariant Sections, write "with no Invariant Sections"
|
||
instead of saying which ones are invariant. If you have no Front-Cover Texts,
|
||
write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST";
|
||
likewise for Back-Cover Texts.
|
||
|
||
If your document contains nontrivial examples of program code, we recommend
|
||
releasing these examples in parallel under your choice of free software
|
||
license, such as the GNU General Public License, to permit their use in free
|
||
software.
|
||
|
||
Notes
|
||
|
||
[1] Alternatively, if you've obtained the file from the Review Coordinator,
|
||
or are unfamiliar with CVS, you can return the changes to the
|
||
coordinator for further handling.
|
||
[2] The LDP is currently filtering documents back through the Review
|
||
Coordinator until a document management system is implemented, allowing
|
||
for review notes to be stored with the file in a database record.
|