- Fix grammar and form in chapter "2.Writing documentation"

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@237 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2dman.texi

@@ -93,6 +93,7 @@ Free Documentation License''.
 
 @node       History, Directory overview, Top, Top
 @unnumbered History
+@cindex history of changes
 
 @table @strong
 
@@ -136,6 +137,7 @@ First draft of this document
 @node    Directory overview, Writing documentation, History, Top
 @chapter Directory overview
 @cindex  directory layout
+@cindex  source code organization
 
 If you need to work on SGPEM sources, you'll probably
 be interested in understanding how this package directory
@@ -201,25 +203,28 @@ The source files of SGPEM.
 
 @node    Formal documents and draft proposals, Documenting code, Writing documentation, Writing documentation
 @section Formal documents and draft proposals
+@cindex formal documents
+@cindex draft proposals
 
 @subsection Introduction
 
 For writing and editing technical documents we use a subsection 
-of the free office suite @emph{OpenOffice.org 2.0.0}, namely @emph{OpenOffice.org Writer}.
+of the free (as in speech) office suite @emph{OpenOffice.org 2.0.0}, 
+namely @emph{OpenOffice.org Writer}.
 
-In some cases also use some other subsections of @emph{OpenOffice.org}
+We sporadically also use other parts of the suite, such as 
-will be used, like @emph{OpenOffice.org Calc} for calculations and 
+@emph{OpenOffice.org Calc} for calculations and 
 charts, and @emph{OpenOffice.org Impress} for presentations.
 
 @subsection Technical document format
-All technical documents must respect the styles and formats 
+All technical documents must respect the style and formats 
 explained hereafter.
 
 @itemize
 @item
-@emph{All the document start with the Cover Page} : 
+@emph{All the documents start with a Cover Page} : 
 The @b{cover page} contains in the right corner the logo, name and address 
-of company. In the middle of the page there's the @b{title} of the specific 
+of the company. In the middle of the page there's the @b{title} of the specific 
 technical document. Under the title goes the @b{acronym} of the project 
 (@acronym{SGPEMv2}), followed by the @b{version} of the document. 
 
@@ -235,53 +240,55 @@ be reported the @b{status} of the document, either @emph{Formal} or
 @emph{Informal}, followed by one of the tags @emph{External} or 
 @emph{Internal}.
 
-The @b{footer} of the cover page must contain the name of the @b{Author} of 
+The @b{footer} of the cover page should contain the name of the @b{Author} of 
 that technical document. 
 
 @item
 The page after the cover page has to contain:
 
     @enumerate
-@item
-@strong{Distribution List}: to whom the document goes, it includes 
-the Surname and Name of the person to who delivers the document along with
-the role of that person.
 
     @item
-@strong{History of changes} : where to trace the changes made to the specific 
+    @strong{Distribution List}: to whom the document goes. It includes 
-document, including the date of the change, the person who made the 
+    the Surname and Name of the person to be reached by the document, 
+    along with the role of that person.
+
+    @item
+    @strong{History of changes}: where to trace the changes made to the 
+    document, including the date of the edit, the person who made the 
     change, and the reason(s) of it.
 
     @item
-@strong{List of Approved Versions} : here all the approved versions of 
+    @strong{List of Approved Versions}: here are traced all the approved 
-that document are traced, reporting the date and the name of the 
+    versions of the document, reporting the date and the name of the 
-person who approved that version.
+    person who approved that particular revision.
 
     @end enumerate
 
 @item
-An @b{Abstract} must follow the List of Approved Versions: a short 
+An @b{Abstract} has to follow the List of Approved Versions: it's 
-one-liner of what the document is about.
+a short one-liner of what the document is about.
 
 @item
 On a new page, there's a @b{Table of Contents} that shows all 
 the @b{Headings} in the file.
 
-If the document has a lot of Illustrations, then after the @b{Table of
+If the document includes a lot of figures, then after the @b{Table of
-Contents} it should follow a @b{Illustration Index} of all figures 
+Contents} there should be an @b{Illustration Index}.
-included in the file.
 
 @item
 After that, every document has to start with the @b{Introduction} section, 
-where it will be described the purpose of the document, the purpose 
+where it will be described the purpose of the document and the purpose 
-of the product and it will be included a list of used @b{References}.
+of the product, along with a list of used @b{References} to other 
+documents or resources.
 
 @item
-The other parts of the document are specific to the technical document 
+Other parts of the document are specific to the technical document 
-itself, and therefore should be managed by the author of the document. 
+itself, and therefore should be managed by the editor. 
 Mostly, the general structure for the more common documents can be found at
 @uref{http://www.math.unipd.it/~tullio/IS-1/2005/Progetto/Documenti.html} 
 (in Italian).
+
 In the @samp{docs/misc/} directory of the Subversion repository,
 there's an OpenOffice.org @b{template} with some already defined 
 styles you should inherit from. Its name is @file{templatedocument.ott}.
@@ -289,16 +296,16 @@ styles you should inherit from. Its name is @file{templatedocument.ott}.
 @item
 At the end of every document there should be a @b{Glossary}. The Glossary 
 is a file on its own (usually, @file{docs/externals/Glossary.odt} 
-off the repository), so new entries must be inserted into it.
+off the repository), so new entries must be inserted into this latter.
 
 Every technical document should ``include'' the afore mentioned file. 
 Please refer to the @emph{OpenOffice.org} manual about @emph{Sections} to know
-how to do so. The Glossary will then be linked to the current document 
+how to do so. The Glossary will so be linked to the current document 
 dinamically, and every change done on the Glossary will reflect 
-in an automatical update in every linker.
+in an automatic update in every referer.
 
-In this way all the technical documents will automatically contain the 
+In this way all the technical documents are always able to have the 
-latest up-to-date version of the Glossary.
+latest up-to-date and synchronized revision of the Glossary.
 
 @item
 The @b{Header} of all pages, except the one on the cover page, 
@@ -309,11 +316,11 @@ contains:
 in the left corner, the name of the company;
 
 @item
-in the right corner, the Chapter number and name.
+in the right corner, the chapter number and name.
 @end itemize
 
 @item
-The @b{Footer} of every page, except the cover page, contains:
+The @b{Footer} of every page, except on the cover page, contains:
 
 @itemize
 @item
@@ -327,10 +334,9 @@ number of  pages.
 
 @end itemize
 
-To make easier to abid to these rules, inherit from the template document that 
+To make it easier to abid to these rules, please remember to inherit 
-includes all Fonts and Styles established. It also has a foundation for all 
+from the template document. It lays down a foundation for all 
-the pages mentioned above.
+the style guidelines mentioned above.
-
 
 @c % ---- new section 
 
@@ -340,46 +346,52 @@ the pages mentioned above.
 In order to generate documentation straight from the source code:
 
 @subsection C++ code
+@cindex documenting C++ code
 
-Please refer to Doxygen manual 
+Please refer to @emph{Doxygen} manual 
 (@uref{http://www.stack.nl/~dimitri/doxygen/manual.html}) 
 in order to learn how to use this automatic tool for extracting 
 documentation from code.
 
 Every function, class, class member, class method, 
-and enumeration in code should be documented, less of static
+and enumeration in code should be documented, less of trivial 
-global functions visible only to the current compilation unit.
+static global functions visible only to the 
+current compilation unit.
 
 In particular, for functions and methods, you should use
 @code{\param} and @code{\return} to describe respectively
-parameters and return value of it.
+parameters and return value.
 
 @subsection Python code
+@cindex documenting Python code
 
-It is usually possible to document Python classes so that
+It is usually possible to annotate Python classes so that
 calling the @code{__doc__} method of an object returns
 its documentation string. 
 Please refer to the Python manual at @uref{http://www.python.org/}
 to learn more of it.
 
 However, if we want to generate good documentation straight
-from code with Doxygen, we should use the @samp{#} documenting
+from code, with the help of Doxygen, we should use the @samp{#} 
-style. Please look at the end of 
+documenting style. Please look at the end of 
-@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for an example.
+@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for 
+an example.
 
 @c % ----- new subsection
 
 @node    Reporting anomalies, (none), Documenting code, Writing documentation
 @section Reporting anomalies
+@cindex  anomaly
+@cindex  bug
 
 @emph{Note}: sometimes we will refer to an anomaly with the less-formal
 term ``@emph{bug}''.
 
 Anomaly documentation is divided in two parts. The first part concerns the 
-@b{Anomaly Investigation} record and the second one the @b{Anomaly Resolution} record. 
+@b{Anomaly Investigation} and the second one the @b{Anomaly Resolution}. 
-All informations about Anomalies are held in the Appendix section of 
+All informations about anomalies are held in the document named 
-the document named @file{AnomalyRecords.odt}. If you find an anomaly you should start 
+@file{AnomalyRecords.odt}. If you find an anomaly you should start 
-a new page and create a header as follows:
+a new page via a page-break, and create a header as follows:
 
 @table @strong
 
@@ -387,7 +399,7 @@ a new page and create a header as follows:
 Identification number of the anomaly, a unique integer
 
 @item Summary
-A one-liner with a summary of the contents of the anomaly
+A one-liner with a summary of the anomaly
 
 @item Severity
 This field describes the impact of a bug.
@@ -408,10 +420,10 @@ This field describes the impact of a bug.
      @end table
 
 @item Reporter
-Name and email of the person who discovered the Anomaly
+Name and email of the person who discovered the anomaly
 
 @item Date of Identification
-GMT time at witch the anomaly was identified
+Timestamp at which the anomaly was identified
 
 @item Product type and version
 Product (with version number) affected by the anomaly (e.g., architecture, 
@@ -420,7 +432,7 @@ design, code, documentation, @dots{}).
 @item Status
 Please choose one and only one of the following states.
 
-These are used @strong{before} a resolution:
+These are used @strong{before} reaching a resolution:
 
       @table @samp
 
@@ -449,7 +461,7 @@ These are used @strong{before} a resolution:
 
       @end table
 
-Instead, @strong{after} a resolution, the state should change to:
+Instead, @strong{after} a resolution, the state should change to one of:
       
       @table @samp
       
@@ -474,8 +486,8 @@ Who's working to resolve this anomaly, name and email. Usually, it's initially l
 
 @item Description and comments
 Latin creativity at work -- text describing the reasons for assuming 
-the presence of an anomaly. Please be as clear as possible. Unfortunately, giving guidelines in this
+the presence of an anomaly. Please be as clear as possible. Unfortunately, 
-sense is quite difficult @enddots{}
+giving guidelines in this sense is quite difficult @enddots{}
 
 As for follow-ups, always start with the name of the editor, email and the timestamp
 of the comment, assigning a numerical ID to it.
@@ -483,17 +495,17 @@ An example of a comment would be:
 @smallexample
 @group
 -- Comment #1, Slartibartfast <slarti@@go.eu>, 2006 Jan 27th - 16:13 --
-Okay, I'll go and fix the time-space continuum yesterday. 
+Okay, I'll go and fix the time-space continuum on last Friday 17th. 
 Just give me the time to put the gas in my spaceship, will you?
 @end group
 @end smallexample
 
-@strong{Important}: please report clearly in a comment if you change any 
+@strong{Important}: please report it clearly in a new comment if you 
-field of the anomaly header.
+change any field of the anomaly header.
 
 @end table
 
-When the anomaly is resolved, a footer to it is added, with:
+When the anomaly is resolved, a footer is added to it, with:
 
 @table @strong
 @item Date