/[MITgcm]/MITgcm/doc/devel_HOWTO.sgml
ViewVC logotype

Diff of /MITgcm/doc/devel_HOWTO.sgml

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.7 by edhill, Tue Apr 6 04:12:00 2004 UTC revision 1.13 by jmc, Sat May 15 01:44:50 2010 UTC
# Line 1  Line 1 
1  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">  <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2    <!--
3     $Header$
4     $Name$
5    -->
6    
7  <article id="MITgcm-Development-HOWTO">  <article id="MITgcm-Development-HOWTO">
8    
# Line 22  Line 26 
26            Initial version.            Initial version.
27          </revremark>          </revremark>
28        </revision>        </revision>
29          <revision>
30            <revnumber>0.02</revnumber>
31            <date>2010-01-21</date>
32            <authorinitials>jmc</authorinitials>
33            <revremark>
34              update links.
35            </revremark>
36          </revision>
37          <revision>
38            <revnumber>0.03</revnumber>
39            <date>2010-04-25</date>
40            <authorinitials>jmc</authorinitials>
41            <revremark>
42              Add subsection "Developer settings" (under CVS Repository).
43            </revremark>
44          </revision>
45      </revhistory>      </revhistory>
46    
47      <abstract>      <abstract>
# Line 37  Line 57 
57      <sect2>      <sect2>
58        <title>New Versions of This Document</title> <para>You can        <title>New Versions of This Document</title> <para>You can
59        obtain the latest version of this document <ulink        obtain the latest version of this document <ulink
60        url="http://mitgcm.org/dev_docs/devel_HOWTO/">online</ulink> in        url="http://mitgcm.org/public/docs.html">online</ulink> in
61        various formats.</para>        various formats.</para>
62      </sect2>      </sect2>
63      <sect2>      <sect2>
# Line 56  Line 76 
76        <title>User Manual</title>        <title>User Manual</title>
77    
78        <para>Before jumping into development, please familiarize yourself with        <para>Before jumping into development, please familiarize yourself with
79          the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual          the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
80          </ulink>.  This document contains volumes of useful information and is          </ulink>.  This document contains volumes of useful information and is
81          included here by reference.</para>          included here by reference.</para>
82    
# Line 94  Line 114 
114    
115    <sect1 id="cvs">    <sect1 id="cvs">
116      <title>CVS Repository</title>      <title>CVS Repository</title>
117    
118      <sect2>      <sect2>
119        <title>Layout</title>        <title>Layout</title>
120    
# Line 104  Line 125 
125        others.  The tree currently resembles:</para>        others.  The tree currently resembles:</para>
126    
127  <programlisting>gcmpack/  <programlisting>gcmpack/
128    MITgcm-contrib        contributed code    CVSROOT               -hidden-
   CS-regrid             goes into utils  
   cvspolicy.html        -save-  
   CVSROOT               -save-  
   development           experimental stuff  
   manual                -save-  
   misc                  -?-  
129    
130    MITgcm                code    MITgcm                code
131         adjoint                  fold into genmake         bin                      empty
132         bin                      stub for ecco build         doc                      basic developpment documentation
133         compare01                old from 20th century         eesupp                   execution environment support code (wrapper)
134         diags                    timeave f77 in pkgs now         exe                      empty
135         doc                      tags -- connect to real docs?         jobs                     runtime shell scripts for
136         eesupp                   cnh?                                    various platforms (not maintained)
137         exe                      ecco user build         lsopt                    line search
138      ,- jobs                     runtime shell scripts for         model                    main dynamics (core)
139      |                             various platforms         optim                    line search interface
140      |  lsopt                    line search         pkg                      alternate and optional numerics, etc.
141     m|  model                    main dynamics (core)         tools                    scripts to build (and test)
142     e|    optimization_drivers   ?         utils                    pre/post processing tools (matlab, ..)
143     r|  optim                    line search interface         verification             standard regression tests + examples
144     g|  pkg                      alternate and optional numerics, etc.                                        + documented examples (tutorials)
145     e|- tools         tutorial_examples        (only in release1 branch)
    ?|  tutorial_examples        documented tests  
     |                             only populated on release1 branch  
     |                             and not validated during "testscript"  
     '- utils  
        verification             std tests  
146    
147      MITgcm_contrib        contributed code
148    
149    mitgcmdoc -> manual   -remove-    acesgrid.org          build acesgrid web site
150      development           experimental stuff
151      gfd_lab               -?-
152      manual                source of MITgcm documentation
153    mitgcm.org            build web site    mitgcm.org            build web site
154    models                -?-    old_develop           old and early development source
155    packages              -?-         misc                 -?-
156    preprocess            -?-         models               -?-
157    tmp                   -?-         packages             -?-
158           preprocess           -?-
159      pdfs                  some pdfs
160      planetinabottle.org   unfinished web site
161      www.ecco-group.org    build ecco web site ?
162  </programlisting>  </programlisting>
163    
164     <!--
165        <para>Efforts are underway to reduce the complexity.</para>        <para>Efforts are underway to reduce the complexity.</para>
166    -->
167    
168      </sect2>      </sect2>
169    
# Line 182  Line 202 
202        <title>Branches</title>        <title>Branches</title>
203    
204        <para>As shown in the online <ulink        <para>As shown in the online <ulink
205        url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">        url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph">
206        ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two        ViewCVS-generated tree</ulink>, the MITgcm codebase is split into
207        branches or "lines" under which development proceeds.  These two lines are        branches or "lines" under which development proceeds.  The main line
208        referred to as the "MAIN" and "ecco" versions of the code.  While not        of development is referred to as the "MAIN" version of the code.
       identical, the bulk of the MAIN and ecco lines are composed of files from  
       the same codebase.  
209        </para>        </para>
210    
211        <para>Periodically, a "Release" branch is formed from the "MAIN"        <para>Periodically, a "Release" branch is formed from the "MAIN"
212        development branch.  This is done in order to create a relatively stable        development branch.  This is done in order to create a relatively stable
213        reference point for both users and developers.  The intent is that once a        reference point for both users and developers.  The intent is that once a
214        relese branch has been created, only bug-fixes will be added to it.        release branch has been created, only bug-fixes will be added to it.
215        Meanwhile, development (which might "break" or otherwise render invalid        Meanwhile, development (which might "break" or otherwise render invalid
216        the documentation, tutorials, and/or examples contained within a release        the documentation, tutorials, and/or examples contained within a release
217        branch) is allowed to continue along the MAIN and ecco lines.</para>        branch) is allowed to continue along the MAIN line.</para>
218        </sect2>
219    
220        <sect2>
221          <title> Developer settings </title>
222    
223          <para>CVS is a convenient tool to keep up-to-date a personal copy of the
224          MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html">
225          using CVS </ulink>). The same tool is used by developers to
226          incorporate any change into the repository. However, this later
227          function requires specific settings, as detailed here after:</para>
228          <orderedlist>
229            <listitem>
230              <para> You will need an account (loggin access) to the server
231               "mitgcm.org" with the proper group setting (e.g.,
232                group "gcmctrb" to add/modify code into MITgcm_contrib).
233                This kind of account is granted only upon well motivated request.
234                The access to the server mitgcm.org is through ssh-key authorization
235                which will need to be set properly on both side (on your local machine
236                and on your server account). You need to be able to
237                to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
238                in case of different user-name on both sides) to proceed further.</para>
239            </listitem>
240    
241            <listitem>
242              <para> You need to register to the
243            <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs">
244          mitgcm-cvs </ulink> mailing list.
245              This ensures that other developers will receive email notification
246               when you make changes; you will also receive as well such email
247               when others make changes to the repository.
248              </para>
249            </listitem>
250    
251            <listitem>
252              <para> It is highly recommended that you register also to the
253            <ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel">
254          mitgcm-devel </ulink> mailing list (expect a short delay for
255           this request to be processed).
256              This list is intended for developer discussions.
257              </para>
258            </listitem>
259    
260            <listitem>
261              <para> The standard anonymous mode (using "cvsanon", as mentionned
262            <ulink url="http://mitgcm.org/public/source_code.html">
263          here </ulink>) does not allow check-in ("cvs commit") permission.
264             Instead, you will need to set our CVS environment as follow:</para>
265    <screen>
266      $ export CVS_RSH=ssh
267      $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
268    </screen>
269              <para> After downloading a directory, e.g.: <filename>myCopy</filename>,
270               from the CVS repository (e.g.,
271                <filename>MITgcm_contrib/thisPart</filename>) using the command:</para>
272    <screen>
273      $ cvs co -P -d myCopy MITgcm_contrib/thisPart
274    </screen>
275              <para> the type of CVS environment which has been used
276               is stored in the file <filename>myCopy/CVS/Root</filename>
277               and makes it difficult to re-use, for cvs-commit purpose,
278               a cvs local copy (<filename>myCopy</filename>) which was obtained
279               using the CVS anonymous mode.</para>
280            </listitem>
281    
282            <listitem>
283              <para> At this stage, you should be able to send your modified source
284              file (e.g., <filename>src_file</filename>) from your local copy directory
285              (<filename>myCopy</filename>) to the CVS repository
286              (<filename>MITgcm_contrib/thisPart</filename>) using the command
287              "cvs commit":</para>
288    <screen>
289      $ cd myCopy
290      $ cvs -n update        (optional; check if new changes have been made)
291      $ cvs diff src_file    (optional; list your changes)
292      $ cvs commit src_file
293    </screen>
294              <para> It is essential that you provide a short description of the
295              changes you made to <filename>src_file</filename> as you check-in
296              this file (the "cvs commit" command automatically opens your standard
297              editor for this purpose).</para>
298            </listitem>
299    
300          </orderedlist>
301    
302      </sect2>      </sect2>
303    
304      <sect2>      <sect2>
305        <title>Tagging</title>        <title>Main code development</title>
306          <para>(formerly named "Tagging" ; this section needs an update)</para>
307    
308        <para>The intent of tagging is to create "known-good" checkpoints that        <para>The intent of tagging is to create "known-good" checkpoints that
309        developers can use as references.  Traditionally, MITgcm tagging has        developers can use as references.  Traditionally, MITgcm tagging has
# Line 216  Line 319 
319    
320          <listitem>          <listitem>
321            <para>The developer then runs the <ulink            <para>The developer then runs the <ulink
322            url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">            url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
323            testscript</ulink> shell script to see if any problems are introduced.            testreport</ulink> shell script to see if any problems are introduced.
324            While not intended to be exhaustive, the test cases within the            While not intended to be exhaustive, the test cases within the
325            verification directory do provide some indication whether gross errors            verification directory do provide some indication whether gross errors
326            have been introduced.            have been introduced.
# Line 232  Line 335 
335              <listitem>              <listitem>
336                <para>adds a "checkpointXY_pre" comment (where X is a checkpoint                <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
337                number and Y is a letter) to the <ulink                number and Y is a letter) to the <ulink
338                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">                url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
339                tag-index</ulink> file and checks it into the CVS                tag-index</ulink> file and checks it into the CVS
340                repository</para>                repository</para>
341              </listitem>              </listitem>
# Line 277  checkpoint50d_pre Line 380  checkpoint50d_pre
380    </sect1>    </sect1>
381    
382    
   <sect1 id="documentation">  
     <title>Editing the Documentation</title>  
   
     <sect2 id="documentation_getting">  
       <title>Getting the Docs and Code</title>  
   
       <para>The first step towards editing the documentation is to checkout a  
       copy of code, docs, and build scripts from the CVS server using:</para>  
   
 <screen>  
   $ export CVS_RSH=ssh  
   $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'  
   $ mkdir scratch  
   $ cvs co MITgcm manual mitgcm.org  
 </screen>  
   
       <para>These commands extract the necessary information from the CVS server  
       and create a temporary (called <filename>scratch</filename>) directory for  
       the storage of the HTML and other files that will be created.  Please note  
       that you must either create <filename>scratch</filename> as shown or edit  
       the various <filename>Makefile</filename>s and scripts used to create the  
       documentation.</para>  
     </sect2>  
   
     <sect2>  
       <title>Editing the Documentation</title>  
   
       <para>The documentation is contained in the <filename>manual</filename>  
       directory in a raw LaTeX format.  The main document is  
       <filename>manual.tex</filename> and it uses <command>\input{}</command>s  
       to include the chapters and subsections.</para>  
   
       <para>Since the same LaTeX source is used to produce PostScript, PDF, and  
       HTML output, care should be taken to follow certain conventions.  Two of  
       the most important are the usage of the <command>\filelink{}{}</command>  
       and <command>\varlink{}{}</command> commands.  Both of these commands have  
       been defined to simplify the connection between the automatically  
       generated ("code browser") HTML and the HTML version of the manual  
       produced by LaTeX2HTML.  They each take two arguments (corresponding to  
       the contents of the two sets of curly braces) which are the text that the  
       author wishes to be "wrapped" within the link, and a specially formatted  
       link thats relative to the <filename>MITgcm</filename> directory within  
       the CVS tree.</para>  
   
       <para>The result is a command that resembles either</para>  
         
       <orderedlist>  
         <listitem>  
           <para>a reference to a variable or subroutine name such as  
           <command>\varlink{tRef}{tRef}</command>, or </para>  
         </listitem>  
   
         <listitem>  
           <para>a reference to a file such as  
               <command>\varlink{tRef}{path-to-the-file_name.F}</command>  
               where the absolute path to the file is of the form  
               <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>  
               <para>(please note how the leading "/foo/MITgcm"  
               component of the path is dropped leaving the path  
               <emphasis>relative</emphasis> to the head of the code  
               directory and each directory separator "/" is turned  
               into a "-")</para>  
         </listitem>  
       </orderedlist>  
             
   
   
     </sect2>  
   
     <sect2>  
       <title>Building the Documentation</title>  
         
       <para>Given the directory structure of <xref  
       linkend="documentation_getting">, the entire documentation for the web  
       site can be built using:</para>  
   
 <screen>  
   $ cd mitgcm.org/devel/buildweb  
   $ make All  
 </screen>  
   
       <para>Which builds the PDF from the LaTeX source, creates the HTML output  
       from the LaTeX source, parses the FORTRAN code base to produce a  
       hyperlinked HTML version of the source, and then determines the  
       cross-linking between the various HTML components.</para>  
   
       <para>If there are no errors, the result of the build process (which can  
       take 30+ minutes on a P4/2.5Ghz) will be contained within a single  
       directory called <filename>scratch/dev_docs</filename>.  This is a freshly  
       built version of the entire on-line users manual.  If you have the correct  
       permissions, it can be directly copied to the web server area:</para>  
   
 <screen>  
   $ mv scratch/dev_docs /u/u0/httpd/html  
 </screen>  
   
       <para>and the update is complete.</para>  
   
     </sect2>  
   
   </sect1>  
   
383    <sect1 id="coding">    <sect1 id="coding">
384      <title>Coding for MITgcm</title>      <title>Coding for MITgcm</title>
385    
# Line 787  checkpoint50d_pre Line 788  checkpoint50d_pre
788                special command option (see "-command" below) to invoke the MPI                special command option (see "-command" below) to invoke the MPI
789                executable.  Examples of PBS scripts using MPI with testreport can be                executable.  Examples of PBS scripts using MPI with testreport can be
790                found in the <ulink                found in the <ulink
791                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">                url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
792                MITgcm-contrib area</ulink></para>                MITgcm-contrib area</ulink></para>
793              </listitem>              </listitem>
794            </varlistentry>            </varlistentry>
# Line 799  checkpoint50d_pre Line 800  checkpoint50d_pre
800                output.txt" is not sufficient.  This option allows a more general                output.txt" is not sufficient.  This option allows a more general
801                command (or shell script) to be invoked.  Examples of PBS scripts                command (or shell script) to be invoked.  Examples of PBS scripts
802                using MPI with testreport can be found in the <ulink                using MPI with testreport can be found in the <ulink
803                url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">                url="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
804                MITgcm-contrib area</ulink></para>                MITgcm-contrib area</ulink></para>
805              </listitem>              </listitem>
806            </varlistentry>            </varlistentry>
# Line 826  checkpoint50d_pre Line 827  checkpoint50d_pre
827          the generic fluid dynamical engine.</para>          the generic fluid dynamical engine.</para>
828    
829        <para>The MITgcmUV packaging structure is described below using generic        <para>The MITgcmUV packaging structure is described below using generic
830          package names ${pkg}.  A concrete examples of a package is the code for          package names ${pkg}. A concrete examples of a package is the code for
831          implementing GM/Redi mixing. This code uses the package name</para>          implementing GM/Redi mixing. This code uses the package name</para>
832    
833      </sect2>      </sect2>
# Line 886  o  Each package gets its runtime configu Line 887  o  Each package gets its runtime configu
887     Package runtime config. options are imported     Package runtime config. options are imported
888     into a common block held in a header file     into a common block held in a header file
889     called "${PKG}.h".     called "${PKG}.h".
890       Note: In some packages, the header file "${PKG}.h" is splitted
891       into "${PKG}_PARAMS.h" that contains the package parameters and
892       ${PKG}_VARS.h" for the field arrays.
893    
894  o  The core driver part of the model can check  o  The core driver part of the model can check
895     for runtime enabling or disabling of individual packages     for runtime enabling or disabling of individual packages
# Line 908  CPP Flags Line 912  CPP Flags
912      1. Within the core driver code flags of the form      1. Within the core driver code flags of the form
913         ALLOW_${PKG} are used to include or exclude         ALLOW_${PKG} are used to include or exclude
914         whole packages. The ALLOW_${PKG} flags are included         whole packages. The ALLOW_${PKG} flags are included
915         from a PKG_CPP_OPTIONS block which is currently         from a PACKAGES_CONFIG.h file that is automatically
916           generated by genmake2 (see genmake2 section).
917         held in-line in the CPP_OPTIONS.h header file.         held in-line in the CPP_OPTIONS.h header file.
918         e.g.         e.g.
919    
920         Core model code .....         Core model code .....
921    
922           #include "PACKAGES_CONFIG.h"
923         #include "CPP_OPTIONS.h"         #include "CPP_OPTIONS.h"
924           :           :
925           :           :
# Line 925  CPP Flags Line 931  CPP Flags
931    
932      2. Within an individual package a header file,      2. Within an individual package a header file,
933         "${PKG}_OPTIONS.h", is used to set CPP flags         "${PKG}_OPTIONS.h", is used to set CPP flags
934         specific to that package. It is not recommended         specific to that package. It also includes
935         to include this file in "CPP_OPTIONS.h".         "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
936    
937    
938  Package Boot Sequence  Package Boot Sequence
# Line 978  Package Output Line 984  Package Output
984    
985          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
986            if ( use${Pkg} )            if ( use${Pkg} )
987       &       CALL ${PKG}_DIAGS( )       &       CALL ${PKG}_OUTPUT( )
988          #endif          #endif
989    
990       7. S/R PACKAGES_WRITE_PICKUP()       7. S/R PACKAGES_WRITE_PICKUP()
# Line 994  Description Line 1000  Description
1000        - ${PKG}_READPARMS()        - ${PKG}_READPARMS()
1001      is responsible for reading      is responsible for reading
1002      in the package parameters file data.${pkg}, and storing      in the package parameters file data.${pkg}, and storing
1003      the package parameters in "${PKG}.h".      the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1004      -> called from INITIALISE_FIXED in PACKAGES_READPARMS      -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1005    
1006       - ${PKG}_INIT_FIXED()       - ${PKG}_INIT_FIXED()
# Line 1024  Description Line 1030  Description
1030       use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old       use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1031       form ${PKG}_INIT       form ${PKG}_INIT
1032    
1033       - ${PKG}_DIAGS()       - ${PKG}_OUTPUT( )
1034       is responsible for writing time-average diagnostics to output       is responsible for writing time-average fields to output files
1035       files (but the cumulating step is done within the package main S/R).       (but the cumulating step is done within the package main S/R).
1036       Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)       Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1037       and write snap-shot fields that are hold in common blocks. Other       and write snap-shot fields that are hold in common blocks. Other
1038       temporary fields are directly dump to file where they are available.       temporary fields are directly dump to file where they are available.
1039       NOTE: this part does not yet have a standard form and should be called       NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
1040         from a package dedicated S/R such as PACKAGE_WRITE_DIAGS                but is beeing replaced by ${PKG}_OUTPUT
1041                  to avoid confusion with pkg/diagnostics functionality.
1042               2) the output part is not yet in a standard form and might still
1043                  evolve a lot.
1044      -> called within DO_THE_MODEL_IO      -> called within DO_THE_MODEL_IO
1045    
1046       - ${PKG}_WRITE_PICKUP()       - ${PKG}_WRITE_PICKUP()
# Line 1058  Summary Line 1067  Summary
1067    -----------------------    -----------------------
1068    * ${PKG}_OPTIONS.h     has further package-specific CPP options    * ${PKG}_OPTIONS.h     has further package-specific CPP options
1069    * ${PKG}.h             package-specific common block variables, fields    * ${PKG}.h             package-specific common block variables, fields
1070       or  ${PKG}_PARAMS.h   package-specific common block parameters
1071       and ${PKG}_VARS.h     package-specific common block fields
1072    
1073  - FORTRAN source files  - FORTRAN source files
1074    -----------------------    -----------------------
# Line 1066  Summary Line 1077  Summary
1077    * ${pkg}_check.F        checks package dependencies and consistencies    * ${pkg}_check.F        checks package dependencies and consistencies
1078    * ${pkg}_init_varia.F   initialises package-related fields    * ${pkg}_init_varia.F   initialises package-related fields
1079    * ${pkg}_... .F         package source code    * ${pkg}_... .F         package source code
1080    * ${pkg}_diags.F        write diagnostics to file.    * ${pkg}_output.F       write output to file.
1081    * ${pkg}_write_pickup.F write a package pickup file to restart the model    * ${pkg}_write_pickup.F write a package pickup file to restart the model
1082    
1083      New: Subroutine in one package (pkgA) that only contains code which
1084           is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1085           will be named: pkgA_pkgB_something.F
1086    
1087  - parameter file  - parameter file
1088    -----------------------    -----------------------
1089    * data.${pkg}          parameter file    * data.${pkg}          parameter file
# Line 1077  Summary Line 1092  Summary
1092    </sect1>    </sect1>
1093    
1094    
1095      <sect1 id="documentation">
1096        <title>Editing the Documentation</title>
1097    
1098        <sect2 id="documentation_getting">
1099          <title>Getting the Docs and Code</title>
1100    
1101          <para>The first step towards editing the documentation is to checkout a
1102          copy of code, docs, and build scripts from the CVS server using:</para>
1103    
1104    <screen>
1105      $ export CVS_RSH=ssh
1106      $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
1107      $ mkdir scratch
1108      $ cvs co -P MITgcm manual mitgcm.org
1109    </screen>
1110    
1111          <para>These commands extract the necessary information from the CVS server
1112          and create a temporary (called <filename>scratch</filename>) directory for
1113          the storage of the HTML and other files that will be created.  Please note
1114          that you must either create <filename>scratch</filename> as shown or edit
1115          the various <filename>Makefile</filename>s and scripts used to create the
1116          documentation.</para>
1117        </sect2>
1118    
1119        <sect2>
1120          <title>Editing the Documentation</title>
1121    
1122          <para>The documentation is contained in the <filename>manual</filename>
1123          directory in a raw LaTeX format.  The main document is
1124          <filename>manual.tex</filename> and it uses <command>\input{}</command>s
1125          to include the chapters and subsections.</para>
1126    
1127          <para>Since the same LaTeX source is used to produce PostScript, PDF, and
1128          HTML output, care should be taken to follow certain conventions.  Two of
1129          the most important are the usage of the <command>\filelink{}{}</command>
1130          and <command>\varlink{}{}</command> commands.  Both of these commands have
1131          been defined to simplify the connection between the automatically
1132          generated ("code browser") HTML and the HTML version of the manual
1133          produced by LaTeX2HTML.  They each take two arguments (corresponding to
1134          the contents of the two sets of curly braces) which are the text that the
1135          author wishes to be "wrapped" within the link, and a specially formatted
1136          link thats relative to the <filename>MITgcm</filename> directory within
1137          the CVS tree.</para>
1138    
1139          <para>The result is a command that resembles either</para>
1140          
1141          <orderedlist>
1142            <listitem>
1143              <para>a reference to a variable or subroutine name such as
1144              <command>\varlink{tRef}{tRef}</command>, or </para>
1145            </listitem>
1146    
1147            <listitem>
1148              <para>a reference to a file such as
1149                  <command>\varlink{tRef}{path-to-the-file_name.F}</command>
1150                  where the absolute path to the file is of the form
1151                  <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
1152                  <para>(please note how the leading "/foo/MITgcm"
1153                  component of the path is dropped leaving the path
1154                  <emphasis>relative</emphasis> to the head of the code
1155                  directory and each directory separator "/" is turned
1156                  into a "-")</para>
1157            </listitem>
1158          </orderedlist>
1159              
1160    
1161    
1162        </sect2>
1163    
1164        <sect2>
1165          <title>Building the Documentation</title>
1166          
1167          <para>Given the directory structure of <xref
1168          linkend="documentation_getting">, the entire documentation for the web
1169          site can be built using:</para>
1170    
1171    <screen>
1172      $ cd mitgcm.org/devel/buildweb
1173      $ make All
1174    </screen>
1175    
1176          <para>Which builds the PDF from the LaTeX source, creates the HTML output
1177          from the LaTeX source, parses the FORTRAN code base to produce a
1178          hyperlinked HTML version of the source, and then determines the
1179          cross-linking between the various HTML components.</para>
1180    
1181          <para>If there are no errors, the result of the build process (which can
1182          take 30+ minutes on a P4/2.5Ghz) will be contained within a single
1183          directory called <filename>scratch/dev_docs</filename>.  This is a freshly
1184          built version of the entire on-line users manual.  If you have the correct
1185          permissions, it can be directly copied to the web server area:</para>
1186    
1187    <screen>
1188      $ mv scratch/dev_docs /u/u0/httpd/html
1189    </screen>
1190    
1191          <para>and the update is complete.</para>
1192    
1193        </sect2>
1194    
1195      </sect1>
1196    
1197  </article>  </article>
1198    
1199    
Legend:
Removed from v.1.7  
changed lines
  Added in v.1.13
  ViewVC Help
Powered by ViewVC 1.1.22