Updating GRASS Documentation: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
No edit summary
 
Line 9: Line 9:


<p>
<p>
<li>To begin, you must obtain the latest Grass source code from the CVS repositories. Detailed instructions on how to do so can be found [http://grass.itc.it/faq/cvs_howto.html here]
<li>To begin, you must obtain the latest Grass source code from the CVS repositories. Detailed instructions on how to do so can be found [http://grass.itc.it/faq/cvs_howto.html here.]</li>
 
<li>Once you have downloaded the CVS source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:</li>
 
<li>Once you have downloaded the CVS source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:
<pre>/your_cvs_directory/grass6/vector/v.in.ascii</pre>
<pre>/your_cvs_directory/grass6/vector/v.in.ascii</pre>
<li>Open a text editor and make your edits to description.html. Save your edits by overwriting the original description.html.
<li>Open a text editor and make your edits to description.html. Save your edits by overwriting the original description.html.</li>
<li>Within a terminal, create a 'unified diff' (a standard way to show changes between two versions of a file) of the Grass CVS repository version of description.html and your newly edited description.html:
<li>Within a terminal, create a 'unified diff' (a standard way to show changes between two versions of a file) of the Grass CVS repository version of description.html and your newly edited description.html:</li>
<pre>
<pre>
cvs diff -u description.html > v.in.ascii.description.patch
cvs diff -u description.html > v.in.ascii.description.patch
</pre>
</pre>
<p>
<p>
This "diff -u" command will create a report in v.in.ascii.description.patch which shows any differences between the version of description.html still on the CVS server and your edited version; a '+' at the beginning of each line denotes edits and additions you have made, and a '-' at the beginning of each line denotes lines removed from the original description.html. The exact name of your patch file is arbitrary, but should be as descriptive as
This "diff -u" command will create a report in v.in.ascii.description.patch which shows any differences between the version of description.html still on the CVS server and your edited version; a '+' at the beginning of each line denotes edits and additions you have made, and a '-' at the beginning of each line denotes lines removed from the original description.html. The exact name of your patch file is arbitrary, but should be as descriptive as
possible as in the above example.</p>
possible as in the above example.
</p>
 
<p>The output of the diff -u should look <i>something</i> like this (the exact contents will of course depend on whatever changes you made to the file):</p>
<p>The output of the diff -u should look <i>something</i> like this (the exact contents will of course depend on whatever changes you made to the file):</p>
<pre>
<pre>
Line 52: Line 53:
</pre>
</pre>
<p>(The above line is the end of the example diff file)</p>
<p>(The above line is the end of the example diff file)</p>
<li>Email a Grass <a href:"http://grass.itc.it/community/team.php">developer</a> your description.html.patch for review <b><i>as an attachment</i></b>, along with a brief explanation why it is required. Please post a general
<li>Email a Grass [http://grass.itc.it/community/team.php developer] your description.html.patch for review <b><i>as an attachment</i></b>, along with a brief explanation why it is required. Please post a general message about your documentation update to the [http://grass.itc.it/devel/index.php#list Grass Deveoper's List] before sending your patch to anyone in particular.
message about your documentation update to the <a href:"http://grass.itc.it/devel/index.php#list>Grass Developer's Mailing List</a> before sending your patch to anyone in particular.

Revision as of 15:39, 25 October 2006

How-to for Updating Grass Manual Pages

This page will provide general step-by-step instructions for updating and improving Grass manual pages. Feel free to update and improve this page as well!

As an example, the vector program v.in.ascii will be used to illustrate the steps required to update its manual page. These steps can then be generalized for your case.

  • To begin, you must obtain the latest Grass source code from the CVS repositories. Detailed instructions on how to do so can be found here.
  • Once you have downloaded the CVS source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:
  • /your_cvs_directory/grass6/vector/v.in.ascii
  • Open a text editor and make your edits to description.html. Save your edits by overwriting the original description.html.
  • Within a terminal, create a 'unified diff' (a standard way to show changes between two versions of a file) of the Grass CVS repository version of description.html and your newly edited description.html:
  • cvs diff -u description.html > v.in.ascii.description.patch
    

    This "diff -u" command will create a report in v.in.ascii.description.patch which shows any differences between the version of description.html still on the CVS server and your edited version; a '+' at the beginning of each line denotes edits and additions you have made, and a '-' at the beginning of each line denotes lines removed from the original description.html. The exact name of your patch file is arbitrary, but should be as descriptive as possible as in the above example.

    The output of the diff -u should look something like this (the exact contents will of course depend on whatever changes you made to the file):

    Index: description.html
    ===================================================================
    RCS file: /home/grass/grassrepository/grass6/vector/v.in.ascii/description.html,v
    retrieving revision 1.35
    diff -u -r1.35 description.html
    --- description.html    31 May 2006 13:03:57 -0000      1.35
    +++ description.html    26 Sep 2006 14:35:21 -0000
    @@ -35,6 +35,10 @@
    
     Use the <b>-z</b> flag to convert ASCII data into a 3D binary vector map.
    
    +Any edits you make to description.html will show up like this after you run diff -u!
    +Three lines of the original description.html will surround each block of edits you made
    +to provide context.
    +
     A GRASS ASCII vector file (in <B>standard</B> mode) may contain a mix of
     primitives including points, lines, boundaries, centroids, areas, faces,
    @@ -51,6 +55,8 @@
     <LI>'K': kernel (3D centroid)</LI>
     <LI>'A': area (boundary) - better use 'B'; kept only for backward compatibility</LI>
     </UL>
    +
    +This line is another edit made further along in description.html....
    
    The coordinates are listed following the initial line containing the
     primitive code, the total number of vectors in the series, and the number
    

    (The above line is the end of the example diff file)

  • Email a Grass developer your description.html.patch for review as an attachment, along with a brief explanation why it is required. Please post a general message about your documentation update to the Grass Deveoper's List before sending your patch to anyone in particular.