Changeset 2614 for trunk/doc


Ignore:
Timestamp:
May 14, 2003, 4:05:52 PM (17 years ago)
Author:
michaelm
Message:

lots of updates, removed entities that aren't valid xml, removed references to contents, added info on destroot, added submission guidlines chapter

Location:
trunk/doc/guide/xml
Files:
1 added
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/guide/xml/commands.xml

    r1670 r2614  
    77  <sect1>
    88    <title>Commands</title>
    9 
     9   
     10    <sect2>
     11      <title>Fetch Options</title>
     12
     13      <para>
     14      </para>
     15    </sect2>
     16   
     17    <sect2>
     18      <title>Extract Options</title>
     19
     20      <variablelist>
     21        <varlistentry>
     22          <term>extract.only</term>
     23
     24          <listitem>
     25            <synopsis>Type: Optional Default: ${distfiles}</synopsis>
     26
     27            <para>List of files to extract into ${workpath}.</para>
     28
     29            <para>
     30              <userinput>extract.only worksrc-1.4.4.tar.gz</userinput>
     31            </para>
     32          </listitem>
     33        </varlistentry>
     34
     35        <varlistentry>
     36          <term>extract.cmd</term>
     37
     38          <listitem>
     39            <synopsis>Type: optional Default: gzip</synopsis>
     40
     41            <para>Command to perform extract.</para>
     42
     43            <para>
     44              <userinput>extract.cmd bzip2</userinput>
     45            </para>
     46          </listitem>
     47        </varlistentry>
     48
     49        <varlistentry>
     50          <term>extract.pre_args</term>
     51
     52          <listitem>
     53            <synopsis>Type: optional Default: -dc</synopsis>
     54
     55            <para>Arguments added to ${extract.cmd} before a file name.</para>
     56
     57            <para>
     58              <userinput>extract.pre_args -cd</userinput>
     59            </para>
     60          </listitem>
     61        </varlistentry>
     62
     63        <varlistentry>
     64          <term>extract.args</term>
     65
     66          <listitem>
     67            <synopsis>Type: read-only Default: ${distpath}/${distfile}</synopsis>
     68
     69            <para>Arguments to ${extract.cmd}.</para>
     70          </listitem>
     71        </varlistentry>
     72
     73        <varlistentry>
     74          <term>extract.post_args</term>
     75
     76          <listitem>
     77            <synopsis>Type: optional Default: | tar -xf -</synopsis>
     78
     79            <para>Arguments added to extract command after a file name.</para>
     80
     81            <para>
     82              <userinput>extract.post_args | tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -</userinput>
     83            </para>
     84          </listitem>
     85        </varlistentry>
     86
     87        <varlistentry>
     88          <term>extract.sufx</term>
     89
     90          <listitem>
     91            <synopsis>Type: optional Default: .tar.gz</synopsis>
     92
     93            <para>Suffix to append to ${distname}</para>
     94
     95            <para>
     96              <userinput>extract.sufx .tgz</userinput>
     97            </para>
     98          </listitem>
     99        </varlistentry>
     100
     101        <varlistentry>
     102          <term>use_zip</term>
     103
     104          <listitem>
     105            <synopsis>Type: optional</synopsis>
     106
     107            <para>Sets extract.sufx to: .zip Sets extract.cmd to: unzip Sets extract.pre_args to: -q Sets extract.post_args to: "-d $portpath/$workdir"</para>
     108
     109            <para>
     110              <userinput>use_zip yes</userinput>
     111            </para>
     112          </listitem>
     113        </varlistentry>
     114      </variablelist>
     115    </sect2>
     116   
     117    <sect2>
     118      <title>File Verification Options</title>
     119                <variablelist>
     120                  <varlistentry>
     121                          <term>checksums</term>
     122       
     123                          <listitem>
     124                                <synopsis>Type: optional</synopsis>
     125                               
     126                                <para>List of checksums in the format: &lt;file name&gt; &lt;checksum type&gt; &lt;checksum&gt; Currently, the only supported checksum type is md5. If only one file is downloaded, the filename may be ommitted.
     127                                </para>
     128                                <para>
     129                                <userinput>checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c</userinput>
     130                                </para>
     131                          </listitem>
     132                        </varlistentry>
     133      </variablelist>
     134    </sect2>
     135
     136    <sect2>
     137      <title>CVS Options</title>
     138
     139      <para>
     140      </para>
     141    </sect2>
     142
     143    <sect2>
     144      <title>Patch Options</title>
     145
     146      <para>
     147      </para>
     148    </sect2>
     149        <sect2>
     150      <title>Configure Options</title>
     151
     152      <variablelist>
     153        <varlistentry>
     154          <term>configure.pre_args</term>
     155
     156          <listitem>
     157            <synopsis>Type: optional</synopsis>
     158
     159            <para>Arguments added to configure command before ${configure.args}.</para>
     160
     161            <para>
     162              <userinput>configure.pre_args --prefix=${prefix}/etc</userinput>
     163            </para>
     164          </listitem>
     165        </varlistentry>
     166
     167        <varlistentry>
     168          <term>configure.args</term>
     169
     170          <listitem>
     171            <synopsis>Type: optional</synopsis>
     172
     173            <para>Arguments to pass to ${configure.cmd}.</para>
     174
     175            <para>
     176              <userinput>configure.args --etcdir=${prefix}/etc</userinput>
     177            </para>
     178          </listitem>
     179        </varlistentry>
     180
     181        <varlistentry>
     182          <term>configure.dir</term>
     183
     184          <listitem>
     185            <synopsis>Type: optional</synopsis>
     186
     187            <para>Directory in which to run ${configure-cmd}.</para>
     188
     189            <para>
     190              <userinput>configure.dir src</userinput>
     191            </para>
     192          </listitem>
     193        </varlistentry>
     194      </variablelist>
     195    </sect2>
     196
     197    <sect2>
     198      <title>Automake Options</title>
     199
     200      <variablelist>
     201        <varlistentry>
     202          <term>use_automake</term>
     203
     204          <listitem>
     205            <synopsis>Type: optional Default: ${workpath}/${worksrcdir}</synopsis>
     206
     207            <para>If set to yes, use ${automake.cmd}.</para>
     208
     209            <para>
     210              <userinput>use_automake yes</userinput>
     211            </para>
     212          </listitem>
     213        </varlistentry>
     214
     215        <varlistentry>
     216          <term>automake.env</term>
     217
     218          <listitem>
     219            <synopsis>Type: optional</synopsis>
     220
     221            <para>Environmental variables to pass to ${automake.cmd}.</para>
     222
     223            <para>
     224              <userinput>automake.env CFLAGS=-I${prefix}/include/gtk12</userinput>
     225            </para>
     226          </listitem>
     227        </varlistentry>
     228
     229        <varlistentry>
     230          <term>automake.args</term>
     231
     232          <listitem>
     233            <synopsis>Type: optional</synopsis>
     234
     235            <para>Arguments to pass to ${automake.cmd}.</para>
     236
     237            <para>
     238              <userinput>automake.args --foreign</userinput>
     239            </para>
     240          </listitem>
     241        </varlistentry>
     242
     243        <varlistentry>
     244          <term>automake.dir</term>
     245
     246          <listitem>
     247            <synopsis>Type: optional Default: ${workpath}/${worksrcdir}</synopsis>
     248
     249            <para>Directory in which to run ${automake.cmd}.</para>
     250
     251            <para>
     252              <userinput>automake.dir src</userinput>
     253            </para>
     254          </listitem>
     255        </varlistentry>
     256      </variablelist>
     257    </sect2>
     258
     259    <sect2>
     260      <title>Autoconf Options</title>
     261
     262      <variablelist>
     263        <varlistentry>
     264          <term>use_autoconf</term>
     265
     266          <listitem>
     267            <synopsis>Type: Optional</synopsis>
     268
     269            <para>If set to yes, run ${autoconf.cmd}.</para>
     270
     271            <para>
     272              <userinput>use_autoconf yes</userinput>
     273            </para>
     274          </listitem>
     275        </varlistentry>
     276
     277        <varlistentry>
     278          <term>autoconf.env</term>
     279
     280          <listitem>
     281            <synopsis>Type: optional</synopsis>
     282
     283            <para>Environment variables to pass to ${autoconf.cmd}.</para>
     284
     285            <para>
     286              <userinput>autoconf.env CFLAGS=-I${prefix}/include/gtk12</userinput>
     287            </para>
     288          </listitem>
     289        </varlistentry>
     290
     291        <varlistentry>
     292          <term>autoconf.args</term>
     293
     294          <listitem>
     295            <synopsis>Type: optional</synopsis>
     296
     297            <para>Arguments to pass to ${autoconf.cmd}.</para>
     298
     299            <para>
     300              <userinput>autoconf.args -l src/aclocaldir</userinput>
     301            </para>
     302          </listitem>
     303        </varlistentry>
     304
     305        <varlistentry>
     306          <term>autoconf.dir</term>
     307
     308          <listitem>
     309            <synopsis>Type: optional Default: ${autoconf.dir}</synopsis>
     310
     311            <para>Directory in which to run ${autoconf.cmd}.</para>
     312
     313            <para>
     314              <userinput>autoconf.dir src</userinput>
     315            </para>
     316          </listitem>
     317        </varlistentry>
     318      </variablelist>
     319    </sect2>
     320   
    10321    <sect2>
    11322      <title>Build Options</title>
     
    88399
    89400          <listitem>
    90             <synopsis>cmdType: optional, Default: &dollar;&lcub;build.cmd&rcub;</synopsis>
     401            <synopsis>cmdType: optional, Default: ${build.cmd}</synopsis>
    91402
    92403            <para>Install command to run relative to ${worksrcdir}.</para>
     
    102413
    103414          <listitem>
    104             <synopsis>Type: optional Default: &dollar;&lcub;build.type&rcub;</synopsis>
     415            <synopsis>Type: optional Default: ${build.type}</synopsis>
    105416
    106417            <para>Defines which 'make' is required, either 'gnu' or 'bsd' Sets build.cmd to either 'gnumake' or 'bsdmake' accordingly</para>
     
    150461        </varlistentry>
    151462
    152       </variablelist>
    153     </sect2>
    154 
    155     <sect2>
    156       <title>Configure Options</title>
    157 
    158       <variablelist>
    159         <varlistentry>
    160           <term>configure.pre_args</term>
    161 
    162           <listitem>
    163             <synopsis>Type: optional</synopsis>
    164 
    165             <para>Arguments added to configure command before ${configure.args}.</para>
    166 
    167             <para>
    168               <userinput>configure.pre_args --prefix=${prefix}/etc</userinput>
    169             </para>
    170           </listitem>
    171         </varlistentry>
    172 
    173         <varlistentry>
    174           <term>configure.args</term>
    175 
    176           <listitem>
    177             <synopsis>Type: optional</synopsis>
    178 
    179             <para>Arguments to pass to ${configure.cmd}.</para>
    180 
    181             <para>
    182               <userinput>configure.args --etcdir=${prefix}/etc</userinput>
    183             </para>
    184           </listitem>
    185         </varlistentry>
    186 
    187         <varlistentry>
    188           <term>configure.dir</term>
    189 
    190           <listitem>
    191             <synopsis>Type: optional</synopsis>
    192 
    193             <para>Directory in which to run ${configure-cmd}.</para>
    194 
    195             <para>
    196               <userinput>configure.dir src</userinput>
    197             </para>
    198           </listitem>
    199         </varlistentry>
    200       </variablelist>
    201     </sect2>
    202 
    203     <sect2>
    204       <title>Automake Options</title>
    205 
    206       <variablelist>
    207         <varlistentry>
    208           <term>use_automake</term>
    209 
    210           <listitem>
    211             <synopsis>Type: optional Default: ${workpath}/${worksrcdir}</synopsis>
    212 
    213             <para>If set to yes, use ${automake.cmd}.</para>
    214 
    215             <para>
    216               <userinput>use_automake yes</userinput>
    217             </para>
    218           </listitem>
    219         </varlistentry>
    220 
    221         <varlistentry>
    222           <term>automake.env</term>
    223 
    224           <listitem>
    225             <synopsis>Type: optional</synopsis>
    226 
    227             <para>Environmental variables to pass to ${automake.cmd}.</para>
    228 
    229             <para>
    230               <userinput>automake.env CFLAGS=-I${prefix}/include/gtk12</userinput>
    231             </para>
    232           </listitem>
    233         </varlistentry>
    234 
    235         <varlistentry>
    236           <term>automake.args</term>
    237 
    238           <listitem>
    239             <synopsis>Type: optional</synopsis>
    240 
    241             <para>Arguments to pass to ${automake.cmd}.</para>
    242 
    243             <para>
    244               <userinput>automake.args --foreign</userinput>
    245             </para>
    246           </listitem>
    247         </varlistentry>
    248 
    249         <varlistentry>
    250           <term>automake.dir</term>
    251 
    252           <listitem>
    253             <synopsis>Type: optional Default: ${workpath}/${worksrcdir}</synopsis>
    254 
    255             <para>Directory in which to run ${automake.cmd}.</para>
    256 
    257             <para>
    258               <userinput>automake.dir src</userinput>
    259             </para>
    260           </listitem>
    261         </varlistentry>
    262       </variablelist>
    263     </sect2>
    264 
    265     <sect2>
    266       <title>Autoconf Options</title>
    267 
    268       <variablelist>
    269         <varlistentry>
    270           <term>use_autoconf</term>
    271 
    272           <listitem>
    273             <synopsis>Type: Optional</synopsis>
    274 
    275             <para>If set to yes, run ${autoconf.cmd}.</para>
    276 
    277             <para>
    278               <userinput>use_autoconf yes</userinput>
    279             </para>
    280           </listitem>
    281         </varlistentry>
    282 
    283         <varlistentry>
    284           <term>autoconf.env</term>
    285 
    286           <listitem>
    287             <synopsis>Type: optional</synopsis>
    288 
    289             <para>Environment variables to pass to ${autoconf.cmd}.</para>
    290 
    291             <para>
    292               <userinput>autoconf.env CFLAGS=-I${prefix}/include/gtk12</userinput>
    293             </para>
    294           </listitem>
    295         </varlistentry>
    296 
    297         <varlistentry>
    298           <term>autoconf.args</term>
    299 
    300           <listitem>
    301             <synopsis>Type: optional</synopsis>
    302 
    303             <para>Arguments to pass to ${autoconf.cmd}.</para>
    304 
    305             <para>
    306               <userinput>autoconf.args -l src/aclocaldir</userinput>
    307             </para>
    308           </listitem>
    309         </varlistentry>
    310 
    311         <varlistentry>
    312           <term>autoconf.dir</term>
    313 
    314           <listitem>
    315             <synopsis>Type: optional Default: ${autoconf.dir}</synopsis>
    316 
    317             <para>Directory in which to run ${autoconf.cmd}.</para>
    318 
    319             <para>
    320               <userinput>autoconf.dir src</userinput>
     463                <varlistentry>
     464          <term>install.destroot</term>
     465
     466          <listitem>
     467            <synopsis>Type: optional Default: DESTDIR='${destroot}'</synopsis>
     468
     469            <para>Arguement passed to ${install.cmd} to cause port to install via the temporary destroot.</para>
     470
     471            <para>
     472              <userinput>install.destroot prefix='${destroot}'</userinput>
    321473            </para>
    322474          </listitem>
     
    358510      </variablelist>
    359511    </sect2>
    360 
    361     <sect2>
    362       <title>Extract Options</title>
    363 
    364       <variablelist>
    365         <varlistentry>
    366           <term>extract.only</term>
    367 
    368           <listitem>
    369             <synopsis>Type: Optional Default: ${distfiles}</synopsis>
    370 
    371             <para>List of files to extract into ${workpath}.</para>
    372 
    373             <para>
    374               <userinput>extract.only worksrc-1.4.4.tar.gz</userinput>
    375             </para>
    376           </listitem>
    377         </varlistentry>
    378 
    379         <varlistentry>
    380           <term>extract.cmd</term>
    381 
    382           <listitem>
    383             <synopsis>Type: optional Default: gzip</synopsis>
    384 
    385             <para>Command to perform extract.</para>
    386 
    387             <para>
    388               <userinput>extract.cmd bzip2</userinput>
    389             </para>
    390           </listitem>
    391         </varlistentry>
    392 
    393         <varlistentry>
    394           <term>extract.pre_args</term>
    395 
    396           <listitem>
    397             <synopsis>Type: optional Default: -dc</synopsis>
    398 
    399             <para>Arguments added to ${extract.cmd} before a file name.</para>
    400 
    401             <para>
    402               <userinput>extract.pre_args -cd</userinput>
    403             </para>
    404           </listitem>
    405         </varlistentry>
    406 
    407         <varlistentry>
    408           <term>extract.args</term>
    409 
    410           <listitem>
    411             <synopsis>Type: read-only Default: ${distpath}/${distfile}</synopsis>
    412 
    413             <para>Arguments to ${extract.cmd}.</para>
    414           </listitem>
    415         </varlistentry>
    416 
    417         <varlistentry>
    418           <term>extract.post_args</term>
    419 
    420           <listitem>
    421             <synopsis>Type: optional Default: | tar -xf -</synopsis>
    422 
    423             <para>Arguments added to extract command after a file name.</para>
    424 
    425             <para>
    426               <userinput>extract.post_args | tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -</userinput>
    427             </para>
    428           </listitem>
    429         </varlistentry>
    430 
    431         <varlistentry>
    432           <term>extract.sufx</term>
    433 
    434           <listitem>
    435             <synopsis>Type: optional Default: .tar.gz</synopsis>
    436 
    437             <para>Suffix to append to ${distname}</para>
    438 
    439             <para>
    440               <userinput>extract.sufx .tgz</userinput>
    441             </para>
    442           </listitem>
    443         </varlistentry>
    444 
    445         <varlistentry>
    446           <term>use_zip</term>
    447 
    448           <listitem>
    449             <synopsis>Type: optional</synopsis>
    450 
    451             <para>Sets extract.sufx to: .zip Sets extract.cmd to: unzip Sets extract.pre_args to: -q Sets extract.post_args to: "-d $portpath/$workdir"</para>
    452 
    453             <para>
    454               <userinput>use_zip yes</userinput>
    455             </para>
    456           </listitem>
    457         </varlistentry>
    458       </variablelist>
    459     </sect2>
    460 
    461     <sect2>
    462       <title>CVS Options</title>
    463 
    464       <para>
    465       </para>
    466     </sect2>
    467 
    468     <sect2>
    469       <title>Fetch Options</title>
    470 
    471       <para>
    472       </para>
    473     </sect2>
    474 
    475     <sect2>
    476       <title>Patch Options</title>
    477 
    478       <para>
    479       </para>
    480     </sect2>
    481512  </sect1>
    482513</chapter>
  • trunk/doc/guide/xml/details.xml

    r2360 r2614  
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    44
    5 <chapter>
     5<chapter id='details'>
    66    <title>Portfile Details</title>
    77    <para> This Chapter describes in detail how each part of a portfile is works and is used. </para>
    88    <sect1>
    99        <title>General Syntax</title>
    10         <para>A Portfile is a TCL script, so the syntax used must be valid TCL or the Portfile will not work. The basic syntax of the Portfile has been designed so most tasks are performed using key value&lpar;s&rpar; combinations. Many people don't realise it is TCL until they want to do something more advanced and realise all that power is there.</para>
    11                 <para>All key value pairs in a Portfile are single lines so line breaks must be escaped with a back solidus &lsquo;&bsol;&rsquo;. </para>
    12                 <para>Variables syntax is &dollar;&lcub;foo&rcub; for the foo variant.</para>
     10        <para>A Portfile is a TCL script, so the syntax used must be valid TCL or the Portfile will not work. The basic syntax of the Portfile has been designed so most tasks are performed using key value(s) combinations. Many people don't realise it is TCL until they want to do something more advanced and realise all that power is there.</para>
     11                <para>All key value pairs in a Portfile are single lines so line breaks must be escaped with a back solidus '\'. </para>
     12                <para>Variables syntax is ${foo} for the foo variant.</para>
    1313        <sect2>
    1414                        <title>Special characters</title>
    15                         <para>As the Portfile is a TCL script certain charachters are &ldquo;special&rdquo;. These have a special meaning in TCL and if you dont want that special meaning, they must be escaped. In general a charachter is escaped using the back solidus &lsquo;&bsol;&rsquo;. The main characters you need to be careful with are <simplelist type="inline">
    16                                         <member>&dollar;</member>
    17                                         <member>&lcub;</member>
    18                                         <member>&rcub;</member>
    19                                         <member>&lsqb;</member>
    20                                         <member>&rsqb;</member>
     15                        <para>As the Portfile is a TCL script certain charachters are "special". These have a special meaning in TCL and if you dont want that special meaning, they must be escaped. In general a charachter is escaped using the back solidus '\'. The main characters you need to be careful with are <simplelist type="inline">
     16                                        <member>$</member>
     17                                        <member>}</member>
     18                                        <member>}</member>
     19                                        <member>[</member>
     20                                        <member>]</member>
    2121                                        </simplelist></para>
    2222                </sect2>
     
    3535                                        <member>master_sites</member>
    3636                                        <member>checksums</member>
    37                                         <member>contents</member>
     37                                        <member>homepage</member>
     38                                        <member>long_description</member>
     39                                       
    3840                                </simplelist>
    3941                        Each of these keys is described in the following pages of the guide.
     
    5052                                <listitem>
    5153                                        <para>Installation prefix, set in the systemwide configuration file /etc/ports/ports.conf. Can be overridden on a per port basis. For example XFree86 needs to install in the /usr tree, or aqua applications are installed in /Applications/Ports</para>
    52                                         <para><userinput>prefix /Applications/Ports</userinput></para>
    5354                                </listitem>
    5455                        </varlistentry>
     
    7172                                <term>filedir</term>
    7273                                <listitem>
    73                                         <para>Path to port files relative to &dollar;&lcub;portpath&rcub;. Read Only.</para>
     74                                        <para>Path to port files relative to ${portpath}. Read Only.</para>
    7475                                </listitem>
    7576                        </varlistentry>
     
    7879                                <term>workdir</term>
    7980                                <listitem>
    80                                         <para>Path to work directory relative to &dollar;&lcub;portpath&rcub;. Read Only</para>
     81                                        <para>Path to work directory relative to ${portpath}. Read Only</para>
    8182                                </listitem>
    8283                        </varlistentry>
     
    110111                                </listitem>
    111112                        </varlistentry>
     113                       
    112114                </variablelist>
    113115        </sect1>
     
    165167                                <listitem>
    166168                                        <para>Description of what the port is/does. Long lines can be broken with escaped newlines. </para>
    167                                         <para><programlisting><userinput>long_description foo performs the transformation of bar into xml &bsol;
     169                                        <para><programlisting><userinput>long_description foo performs the transformation of bar into xml \
    168170This allows users to rapidly transform documentation into multiple formats. </userinput></programlisting></para>
    169171                                </listitem>
     
    187189                                <term>extract.sufx</term>
    188190                                <listitem>
    189                                         <para>By default the value of &dollar;&lcub;extract.sufx&rcub; is .tar.gz. Specifying extract.sufx is optional, only use it if the suffix is not &lsquo;tar.gz.&rsquo;. </para>
     191                                        <para>By default the value of ${extract.sufx} is .tar.gz. Specifying extract.sufx is optional, only use it if the suffix is not 'tar.gz.'. </para>
    190192                                        <para><userinput>extract.sufx .tgz</userinput></para>
    191193                                </listitem>
     
    194196                                <term>distname</term>
    195197                                <listitem>
    196                                         <para>By default distname is &dollar;&lcub;name&rcub;-&dollar;&lcub;version&rcub;. Specifying distname is optional, only use it if the file that contains the port is not &dollar;&lcub;name&rcub;-&dollar;&lcub;version&rcub; (without the extract.sufx).</para>
    197                                         <para><userinput>distname &dollar;&lcub;name&rcub;_&dollar;&lcub;version&rcub;</userinput></para>
     198                                        <para>By default distname is ${name}-${version}. Specifying distname is optional, only use it if the file that contains the port is not ${name}-${version} (without the extract.sufx).</para>
     199                                        <para><userinput>distname ${name}_${version}</userinput></para>
    198200                                </listitem>
    199201                        </varlistentry>
     
    202204                                <term>distfiles</term>
    203205                                <listitem>
    204                                         <para>Defaults to &dollar;&lcub;distname&rcub;.&dollar;&lcub;extract.sufx&rcub;. Specifying distfiles is optional, only use it if the file that contains the port is not &dollar;&lcub;distname&rcub;.&dollar;&lcub;extract.sufx&rcub; or more than one file needs to be retirieved. </para>
    205                                         <para><userinput>distfiles stable.&dollar;&lcub;extract.sufx&rcub; installer.sh</userinput></para>
     206                                        <para>Defaults to ${distname}.${extract.sufx}. Specifying distfiles is optional, only use it if the file that contains the port is not ${distname}.${extract.sufx} or more than one file needs to be retirieved. </para>
     207                                        <para><userinput>distfiles stable.${extract.sufx} installer.sh</userinput></para>
    206208                                        <para>Some ports require multiple items to be fetched from different sites, this can be achieved using tags. The tags are then used to identify which of the master_sites to fetch the file from.see master_sites below for more information. As with long_description, long lines should be broken up with escaped newlines. </para>
    207                                         <para><userinput>distfiles stable.&dollar;&lcub;extract.sufx&rcub;:source installer.sh:install</userinput></para>
     209                                        <para><userinput>distfiles stable.${extract.sufx}:source installer.sh:install</userinput></para>
    208210                                </listitem>
    209211                        </varlistentry>
     
    212214                                <term>use_zip</term>
    213215                                <listitem>
    214                                         <para>Specifying use_zip is optional, only use it if the file downloades is zipped rather than tarred and gziped. use_zip set &dollar;&lcub;extract.sufx&rcub; to .zip and extract.cmd to unzip, extract.pre_args to -q and extract.post_args to &rdquo;-d &dollar;portpath/&dollar;workdir&ldquo;.</para>
     216                                        <para>Specifying use_zip is optional, only use it if the file downloades is zipped rather than tarred and gziped. use_zip set ${extract.sufx} to .zip and extract.cmd to unzip, extract.pre_args to -q and extract.post_args to "-d $portpath/$workdir".</para>
    215217                                        <para><userinput>use_zip yes</userinput></para>
    216218                                </listitem>
     
    219221                                <term>use_bzip2</term>
    220222                                <listitem>
    221                                         <para>Specifying use_bzip2 is optional, only use it if the file downloades is bzipped rather than tarred and gziped. use_bzip2 set &dollar;&lcub;extract.sufx&rcub; to .bzip2 and extract.cmd to bzip2.</para>
     223                                        <para>Specifying use_bzip2 is optional, only use it if the file downloades is bzipped rather than tarred and gziped. use_bzip2 set ${extract.sufx} to .bzip2 and extract.cmd to bzip2.</para>
    222224                                        <para><userinput>use_bzip2 yes</userinput></para>
    223225                                </listitem>
     
    236238                                        <para><userinput></userinput></para>
    237239                                        <para>If you have multiple sites you should break up long lines with escapend newlines. </para>
    238                                         <para><programlisting><userinput>master_sites http://www.somesite.org/files/ &bsol;
     240                                        <para><programlisting><userinput>master_sites http://www.somesite.org/files/ \
    239241http://www.somemirror.org/somesite_org/files/</userinput></programlisting></para>
    240242                                        <tip><para>Always put the trailing forward solidus at the end of a url, and remember to not include the filename itself.</para></tip>
    241243                                        <para>If you need to retrieve files from different sites you can label the urls with tags.</para>
    242                                         <para><programlisting><userinput>master_sites http://www.somesite.org/files/:source &bsol;
     244                                        <para><programlisting><userinput>master_sites http://www.somesite.org/files/:source \
    243245http://www.someothersite.org/somesite_extras/:extras/</userinput></programlisting></para>
    244246
     
    267269                                                <para>
    268270                                                        <programlisting><userinput>
    269 &dollar;&lcub;distname&rcub;-&dollar;&lcub;extract.sufx&rcub; md5 65b89365a65dcad71d4402b48 &bsol;
     271${distname}-${extract.sufx} md5 65b89365a65dcad71d4402b48 \
    270272foo.tar.gz md5 65b89365a65dcad71d4402b44</userinput>
    271273                                                        </programlisting>
     
    284286                                        <term>extract.only</term>
    285287                                        <listitem>
    286                                                 <para>List of files to extract into &dollar;&lcub;workpath&rcub;, defaults to &dollar;&lcub;distfiles&rcub;. Useful when some files are not compressed. Only use extract.only if the default does not do the right thing.</para>
     288                                                <para>List of files to extract into ${workpath}, defaults to ${distfiles}. Useful when some files are not compressed. Only use extract.only if the default does not do the right thing.</para>
    287289                                                <para><userinput>extract.only foo.tar.gz bar.tar.gz</userinput>
    288290                                                </para>
     
    311313                                        <term>extract.args</term>
    312314                                        <listitem>
    313                                                 <para>Arguments to extract.cmd, Read Only. The value is &dollar;&lcub;distpath&rcub;/&dollar;&lcub;distfile&rcub;
     315                                                <para>Arguments to extract.cmd, Read Only. The value is ${distpath}/${distfile}
    314316                                                </para>
    315317                                        </listitem>
     
    319321                                        <term>extract.post_args></term>
    320322                                        <listitem>
    321                                                 <para>Arguments added to extract command after a file name. Defaults to &ldquo;| tar -xf&rdquo;. </para>
     323                                                <para>Arguments added to extract command after a file name. Defaults to "| tar -xf". </para>
    322324                                                <para><userinput>extract.post_args   | tar -xf</userinput>
    323325                                                </para>
     
    334336                                        <term>patchfiles</term>
    335337                                        <listitem>
    336                                                 <para>List of patch files to apply to source. Patch files can be supplied in a port in a directory named files within the port directory or fetched from &dollar;&lcub;patchsites&rcub;. Each patchfile supplied by the Portfile author should patch a single file. diffs should be created with <userinput>diff -u file1 file2 >../../files/patch-file</userinput>. Patches downloaded from patchsites must have checksumes.</para>
     338                                                <para>List of patch files to apply to source. Patch files can be supplied in a port in a directory named files (based on the value of ${filepath}) within the port directory or fetched from ${patchsites}. Each patchfile supplied by the Portfile author should patch a single file. The standard convention is to name the patch file 'patch-&lt;filename&gt;.diff, with one diff file per file altered in the source. If the filename is ambiguous because there are multiple files with that name in the distribution, supply the path components to uniquely identify the file being patched. Diffs should be created with <userinput>diff -u file1 file2 >../../files/patch-file.diff</userinput>. Patches downloaded from patchsites must have checksumes.</para>
    337339                                                <para><userinput>patchfiles patch-Makefile.in patch-source.c</userinput>
    338340                                                </para>
     
    362364                                                        <listitem>
    363365                                                                <para>Environmental variables to pass to automake</para>
    364                                                                 <para><userinput>CFLAGS=&ldquo;-I&lsquo;&dollar;&lcub;prefix&rcub;/include&rsquo;&rdquo;</userinput>
     366                                                                <para><userinput>CFLAGS="-I'${prefix}/include'"</userinput>
    365367                                                                </para>
    366368                                                        </listitem>
     
    379381                                                        <term>automake.dir</term>
    380382                                                        <listitem>
    381                                                                 <para>Directory in which to run &dollar;&lcub;automake.cmd&rcub;. Defaults to &dollar;&lcub;worksrcpath&rcub;</para>
     383                                                                <para>Directory in which to run ${automake.cmd}. Defaults to ${worksrcpath}</para>
    382384                                                                <para><userinput>automake.dir</userinput>
    383385                                                                </para>
     
    398400                                                        <listitem>
    399401                                                                <para>Environmental variables to pass to autoconf</para>
    400                                                                 <para><userinput>autoconf.env   CFLAGS=-I&lsquo;&dollar;&lcub;prefix&rcub;/include/gtk12&rsquo;</userinput>
     402                                                                <para><userinput>autoconf.env   CFLAGS=-I'${prefix}/include/gtk12'</userinput>
    401403                                                                </para>
    402404                                                        </listitem>
     
    415417                                                        <term>autoconf.dir</term>
    416418                                                        <listitem>
    417                                                                 <para>Directory in which to run &dollar;&lcub;autoconf.cmd&rcub;. </para>
     419                                                                <para>Directory in which to run ${autoconf.cmd}. </para>
    418420                                                                <para><userinput>autoconf.dir   src</userinput>
    419421                                                                </para>
     
    430432                                                        <listitem>
    431433                                                                <para>Set environment variables for configure.</para>
    432                                                                 <para><userinput>configure.env CFLAGS=&ldquo;-I&lsquo;&dollar;&lcub;prefix&rcub;/include&rsquo;&rdquo;</userinput>
     434                                                                <para><userinput>configure.env CFLAGS="-I'${prefix}/include'"</userinput>
    433435                                                                </para>
    434436                                                        </listitem>
     
    438440                                                        <term>configure.pre_args</term>
    439441                                                        <listitem>
    440                                                                 <para>Arguments added to configure command before &dollar;&lcub;configure.args&rcub;. Defaults to --prefix=&dollar;&lcub;prefix&rcub;. </para>
    441                                                                 <para><userinput>configure.pre_args       --prefix=&ldquo;&dollar;&lcub;prefix&rcub;/apache2&rdquo;</userinput>
     442                                                                <para>Arguments added to configure command before ${configure.args}. Defaults to --prefix=${prefix}. </para>
     443                                                                <para><userinput>configure.pre_args       --prefix="${prefix}/apache2"</userinput>
    442444                                                                </para>
    443445                                                        </listitem>
     
    448450                                                        <listitem>
    449451                                                                <para>Arguments to pass to configure.</para>
    450                                                                 <para><userinput>configure.args      --etcdir=&ldquo;&dollar;&lcub;prefix&rcub;/etc&rdquo;</userinput>
     452                                                                <para><userinput>configure.args      --etcdir="${prefix}/etc"</userinput>
    451453                                                                </para>
    452454                                                        </listitem>
     
    465467                                <term>build.cmd</term>
    466468                                <listitem>
    467                                         <para>Make command to run relative to &dollar;&lcub;worksrcdir&rcub;. Defaults to make.</para>
     469                                        <para>Make command to run relative to ${worksrcdir}. Defaults to make.</para>
    468470                                        <para><userinput>build.cmd pbxbuild</userinput>
    469471                                        </para>
     
    484486                                <term>build.pre_args</term>
    485487                                <listitem>
    486                                         <para>Arguments to pass to &dollar;&lcub;build.cmd&rcub; before &dollar;&lcub;build.args&rcub;. Read only. Set to  &dollar;&lcub;build.target.current&rcub;
     488                                        <para>Arguments to pass to ${build.cmd} before ${build.args}. Read only. Set to  ${build.target.current}
    487489                                        </para>
    488490                                </listitem>
     
    492494                                <term>build.args</term>
    493495                                <listitem>
    494                                         <para>Arguments to pass to &dollar;&lcub;build.cmd&rcub;</para>
     496                                        <para>Arguments to pass to ${build.cmd}</para>
    495497                                        <para><userinput>build.args     -DNOWARN</userinput>
    496498                                        </para>
     
    499501                       
    500502                        <varlistentry id='build.target'>
    501                                 <term>build.target.all</term>
     503                                <term>build.target</term>
    502504                                <listitem>
    503505                                        <para>Target to pass to make for building everything. Defaults to all.</para>
     
    517519                                <term>install.cmd</term>
    518520                                <listitem>
    519                                         <para>Install command to run relative to &dollar;&lcub;worksrcdir&rcub;. Defaults to &dollar;&lcub;build.cmd&rcub;.</para>
     521                                        <para>Install command to run relative to ${worksrcdir}. Defaults to ${build.cmd}.</para>
    520522                                        <para><userinput>install.cmd pbxbuild</userinput>
    521523                                        </para>
     
    536538                                <term>install.pre_args</term>
    537539                                <listitem>
    538                                         <para>Arguments to pass to &dollar;&lcub;install.cmd&rcub; before &dollar;&lcub;install.args&rcub;. Read only. Set to  &dollar;&lcub;install.target&rcub;
     540                                        <para>Arguments to pass to ${install.cmd} before ${install.args}. Read only. Set to  ${install.target}
    539541                                        </para>
    540542                                </listitem>
     
    544546                                <term>install.args</term>
    545547                                <listitem>
    546                                         <para>Arguments to pass to &dollar;&lcub;install.cmd&rcub;</para>
     548                                        <para>Arguments to pass to ${install.cmd}</para>
    547549                                        <para><userinput>install.args     -DNOWARN</userinput>
    548550                                        </para>
     
    558560                                </listitem>
    559561                        </varlistentry>
     562                        <varlistentry id='install.destroot'>
     563                                <term>install.destroot</term>
     564                                <listitem>
     565                                        <para>Arguments passed to ${install.cmd} in order to install correctly into the destroot.</para>
     566                                        <para>All ports must install via the 'destroot' so that the DarwinPorts infrastructure can register each file and directory a port installs. Most autoconf based build systems will behave correctly and respect DESTDIR, however some will not. Most of those that do not respect DESTDIR will install correctly if you use 'prefix', as in the example below. If your port doesn't respect either of these, you'll have to figure out what to do yourself. Some ports use another term, others require you to patch the Makefile (or other build related script).
     567                                        </para>
     568                                        <para><userinput>install.destroot prefix=${destroot}${prefix}</userinput>
     569                                        </para>
     570                                       
     571                                </listitem>
     572                        </varlistentry>
    560573                </variablelist>
    561 <para></para>
    562         </sect1>
    563         <sect1>
    564                 <title>Register Phase</title>
    565                 <para></para>
    566                 <variablelist>
    567                         <varlistentry id='contents'>
    568                                         <term>contents</term>
    569                                         <listitem>
    570                                                 <para>List of files to be installed by the port Files are assumed to be relative to &dollar;&lcub;prefix&rcub; unless the first character is a '/'.  </para>
    571                                                 <para><userinput>contents       bin/ls man/man1/ls.1.gz</userinput>
    572                                                 </para>
    573                                                 <para>All but the shortest contents lists should be included from a separate file. The other file should begin with the contents key, and have the same format as an inline contents list.</para>
    574                                                 <para><userinput>include contents</userinput>
    575                                                 </para>
    576                                                 <tip>
    577                                                         <para>The following is very useful for partly automating the contents list creation process. The snippet assumes you are installing in the default &dollar;&lcub;prefix&rcub; /opt/local. You must only include files that your port should uninstall so leave out directories like bin or share. Also, don't include reciept or Portfile directories under &dollar;&lcub;prefix&rcub;/var/db/dports. </para>
    578                                                         <programlisting>
    579 % find -d /opt/local &gt; /tmp/existing.files
    580 % sudo port install
    581 % find -d /opt/local &gt; /tmp/more.files
    582 % diff -u /tmp/existing.files /tmp/more.files | grep ^\+\/ | \
    583 sed -e 's|^\+/opt/local/*||g' &gt; contents
    584                                                         </programlisting>
    585                                                 </tip>
    586                                                  
    587                                         </listitem>
    588                                 </varlistentry>
    589                        
    590                 </variablelist>
    591 
    592574        </sect1>
    593575       
  • trunk/doc/guide/xml/guide.xml

    r1109 r2614  
    22<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    4 
    5 <book>
     4<book xmlns:xi="http://www.w3.org/2001/XInclude">
    65<title>Darwinports User Guide</title>
    76<preface>
     
    109</preface>
    1110
    12 <xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="quick.xml" />
     11<xi:include  href="quick.xml" />
    1312<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="details.xml" />
     13<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="submission.xml" />
    1414<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="special.xml" />
    1515<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="variants.xml" />
  • trunk/doc/guide/xml/quick.xml

    r2303 r2614  
    3434                                <programlisting><![CDATA[
    3535########################### libxslt Portfile ##################################
    36 # &dollar;Id&dollar;
     36# $Id: quick.xml,v 1.9 2003/05/14 16:05:51 michaelm Exp $
    3737
    3838PortSystem      1.0
     
    6060                        </example>
    6161                        <para>
    62                                 The Portfile uses key value pairs to define how it is executed. Below is a list of some of the simple terms. Line up each of the values with tabs in a &ldquo;table&rdquo; type of format.
     62                                The Portfile uses key value pairs to define how it is executed. Below is a list of some of the simple terms. Line up each of the values with tabs in a "table" type of format.
    6363                        </para>
    6464                        <variablelist>
     
    7070                                        <listitem>
    7171                                                <para>
    72                                                         The version of darwinports that the port depends on. If a later release introduces a function that isn't in version 1.0, you can specify the version of darwinports that the Port requires. The PortSystem value is 1.0 (at the moment there is no &quot;higher&quot; version of darwinports.
     72                                                        The version of darwinports that the port depends on. If a later release introduces a function that isn't in version 1.0, you can specify the version of darwinports that the Port requires. The PortSystem value is 1.0 (at the moment there is no &quot;higher&quot; version of darwinports).
    7373                                                </para>
    7474                                        </listitem>
     
    124124                                        <listitem>
    125125                                                <para> The md5 checksum of the distfiles. If you have more than one file being fetched you should specify the checksum for each in the form: </para>
    126                                                 <simplelist type="vert">
     126                        <simplelist type="vert">
    127127                                                        <member> foo md5 ....  </member>
    128128                                                        <member> bar md5 ....  </member>
     
    165165                                        <programlisting><![CDATA[
    166166###########################neon Portfile####################################
    167 # &dollar;Id&dollar;
     167# $Id: quick.xml,v 1.9 2003/05/14 16:05:51 michaelm Exp $
    168168
    169169PortSystem 1.0
     
    205205                                                <listitem>
    206206                                                        <para> If you need to specify additional configure arguments you should place them on a single line. As with other settings, newlines may be escaped to break up long lines. Note the continuing lines are indented two spaces.  </para>
    207                                                         <para> By default the configure script is passed --prefix=&dollar;&lcub;prefix&rcub; where ${prefix} is replaced with the prefix darwinports is configured to install into.  </para>
     207                                                        <para> By default the configure script is passed --prefix=${prefix} where ${prefix} is replaced with the prefix darwinports is configured to install into.  </para>
    208208                                                        <tip>
    209                                                                 <para> In general you should quote variables like &lcub;prefix&rcub; in case the path has a space in it.  </para>
     209                                                                <para> In general you should quote variables like }prefix} in case the path has a space in it.  </para>
    210210                                                        </tip>
    211211                                                </listitem>
     
    227227                                                </listitem>
    228228                                                <listitem>
    229                                                         <para> Enable a local source repository and comment out the remote repository. Edit /etc/ports/sources.conf and set:<userinput>file:///usr/dports</userinput> (or wherever your copy of the dport tree is).  </para>
    230                                                 </listitem>
    231                                                 <listitem>
    232                                                         <para> From the local source repository root, create an index file. This will also syntax check portfiles contained.  </para>
     229                                                        <para> Enable a seccond local source (Portfile) repository for your uncommitted ports.  Edit /etc/ports/sources.conf and add:<userinput>file:///User/foo/dports-dev</userinput> (or wherever your local dport tree is).  </para>
     230                                                </listitem>
     231                                                <listitem>
     232                                                        <para> Create an index file from the local source repository root. This will also perfom a simple syntax check portfiles contained.  </para>
    233233                                                        <para> <userinput> portindex </userinput> </para>
    234234                                                </listitem>
    235235                                                <listitem>
    236                                                         <para> Sync the index </para>
    237                                                         <para> <userinput> port sync </userinput> </para>
    238                                                 </listitem>
    239                                                 <listitem>
    240                                                         <para> Install port </para>
     236                                                        <para> Install port, first run port install without root privileges, this is a good way to check that the port installs into the destroot and not directly into the main prefix directory, or elsewhere in the system.  This should succeed up to the point darwinports attempts to copy the port from the destroot into the darwinports prefix. Once you are confident the port is correctly destrooted install the port into the darwinports prefix using root privileges. </para>
    241237                                                        <para> <userinput> sudo port install foo </userinput> </para>
    242238                                                </listitem>
     
    246242                                                </listitem>
    247243                                                <listitem>
    248                                                         <para> Make sure the port builds, installs and uninstalls on a &quot;clean machine&quot;. A clean machine should have a clean install of the OS, to avoid missing dependencies.  </para>
     244                                                        <para> Make sure the port builds, installs and uninstalls on a &quot;clean machine&quot;. A clean machine should have a clean install of the OS, to avoid missing dependencies.  Using a chrooted version of the OS to install and test ports makes this much easier, see the chroot <ulink url="http://darwinports.gene-hacker.net/docs/howto/chroot-howto.html">HOWTO</ulink> for more details on how to set up the chroot. </para>
    249245                                                </listitem>
    250246                                                <listitem>
     
    258254                                </sect1>
    259255                                <sect1>
    260                                         <title>Where to submit</title>
    261                                         <para> Email your submission to <email>darwinports@opendarwin.org</email> mailing <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports">list</ulink>. In general the Portfile should be inlined in the email, rather than as an attatchment. This allows people to view and give feedback on the Portfile more easily. If there is a large contents list and/or patchfiles these may be attatched to the email as a tarred and gzipped archive.  </para>
    262                                 </sect1>
    263                                 <sect1>
    264256                                        <title>Where can I ask for Advice?</title>
    265                                         <para>Either on the <email>darwinports@opendarwin.org</email> mailing list, or on the #opendarwin channel on irc.openprojects.net. Don't be afraid to ask questions!  </para>
    266                                 </sect1>
    267                                 </chapter>
     257                                        <para>Either on the <email>darwinports@opendarwin.org</email> mailing list, or on the #opendarwin channel on irc.freenode.net. Don't be afraid to ask questions! You should also look at the later sections of the <link linkend="details">guide</link>, the Portfile <ulink url="http:http://www.opendarwin.org/projects/darwinports/en/portfileHOWTO.php">HOWTO</ulink> and the portfile(7) and portstyle(7) manpages for more information. </para>
     258                                </sect1>
     259                                <sect1>
     260                                        <title>How do I submit my Ports</title>
     261                                        <para>See the <link linkend="submission">Submission Chapter</link> for all the infromation on how to submit a port properly.
     262                                        </para>
     263                                </sect1>
     264</chapter>
  • trunk/doc/guide/xml/style.xml

    r1529 r2614  
    66        <sect1>
    77                <title>Overview</title>
    8                 <para>
    9                         A port consists of a directory and its contents, within a category subdirectory of the root of the ports tree. This document serves as a reference for the directory structure of a single port and the layout of the files within.
     8                <para>A port consists of a directory and its contents, within a category subdirectory of the root of the ports tree.  This document serves as a reference for the directory structure of a single port and the layout of the files within.
    109                </para>
    11                 <para>
    12                         The only required file in a port is Portfile. The port file should be thought of as a set of declarations rather than a piece of code. It is best to format the port file is if it were a table consisting of keys and values. In fact, the simplest of ports will only contain a small block of values. Therefore, whitespace should not be strown about haphazardly. Nicely formatted compact tables will result in more values being visible at the same time.
     10                <para>The only required file in a port is Portfile.  The port file should be thought of as a set of declarations rather than a piece of code.  It is best to format the port file is if it were a table consisting of keys and values.  In fact, the simplest of ports will only contain a small block of values.  Therefore, whitespace should not be strown about haphazardly. Nicely formatted compact tables will result in more values being visible at the same time.
    1311                </para>
    14                 <para>
    15                         Use tabs to align items into columns. The left side should consist of single words, and will be separated from the more complex right side by a number of tabs that will result in all items begining on the same column.
     12                <para>Try to adhere to these guidelines, but remember that this is only a guide.  No set of rules can adequately cover all cases, and in some cases the best solution is to break the rules.
    1613                </para>
     14                       
     15                       
     16                       
    1717        </sect1>
    1818        <sect1>
    1919                <title>Specifics</title>
    2020                <sect2>
    21                         <title></title>
    22                         <para>
     21                        <title># $Id: style.xml,v 1.5 2003/05/14 16:05:52 michaelm Exp $</title>
     22                        <para>On the first line of the Portfile you should put a cvs ID tag. This tag will be expanded by cvs when the Portfile is committed and allows people to see at a glance details like who was the last person to commit to a port and when the last commit was performed.
    2323                        </para>
    2424                </sect2>
     
    2626                        <title>Portsystem</title>
    2727                        <para>
    28                                 At the top of the port file is the requirement statement. There is a single space between the &ldquo;PortSystem&rdquo; statement and the version number.
     28                                At the top of the port file is the requirement statement. There is a single space between the "PortSystem" statement and the version number.
    2929                        </para>
    3030                </sect2>
     
    3232                        <title>Variable assignments</title>
    3333                        <para>
    34                                 Variable assignments such as &ldquo;set libver&rdquo; can be considered a single word on the left side, with a single space between &ldquo;set&rdquo; and the variable name, followed by tabs to line up with the right side.
     34                                Variable assignments such as "set libver" can be considered a single word on the left side, with a single space between "set" and the variable name, followed by tabs to line up with the right side.
    3535                        </para>
    3636                </sect2>
     
    4848                </sect2>
    4949                <sect2>
    50                         <title>Braces or Curly Brackets &ldquo;&lcub;&rcub;&rdquo;</title>
     50                        <title>Braces or Curly Brackets "{}"</title>
    5151                        <para>
    5252                                the braces may appear on the first and last lines rather than on their own lines. This is done because the right side of the port file is already indented, and to make port file read like a table. Use a single space after the brace. Indent additional lines to this same column.
     
    5656                        <title>Variants</title>
    5757                        <para>
    58                                 Variants are like any other part of the port file. Space, indent, and format them the same way other sections are formatted. The actual vari- ant statement, &ldquo;variant&rdquo; followed by the name of the variant, can be treated as a single statement and thus placed together on the left side and separated by a single space.
     58                                Variants are like any other part of the port file. Space, indent, and format them the same way other sections are formatted. The actual variant statement, "variant" followed by the name of the variant, can be treated as a single statement and thus placed together on the left side and separated by a single space.
    5959                        </para>
    60                 </sect2>
    61                 <sect2>
    62                         <title>Contents Lists</title>
    63                         <para>
    64                                 Short contents lists should appear within the port file, listing each file on a single line, using backslashes to continue the list over the line breaks. If the list is long, it is often better to place the contents in another file named something like &ldquo;contents&rdquo; and pull it into the port file with an &ldquo;include&rdquo; statement. If a variant changes the items installed the variant content file should be named &ldquo;contents-foo&rdquo;, where foo is the name of the variant.
    65                         </para>
    66                         <tip>
    67                                 <para>
    68                                         In general you do not want to list configuration files and directories that the user may modify. The user will not want you to remove their carefully handcrafted httpd.conf, for example.
    69                                 </para>
    70                         </tip>
    7160                </sect2>
    7261                <sect2>
    7362                        <title>Patch Files</title>
    7463                        <para>
    75                                 Patch files reside in the files/ directory in the port's base directory. There should be one patch file for every file that needs to be patched. It is perfectly reasonable to use provided patches that affect multiple files, but do not create new patches that do so. Their names should begin with &ldquo;patch-&rdquo;. The rest of the name should come from the name of the file that they apply to. In many cases just the base name of the file being patched is enough. For files such as &ldquo;Makefile&rdquo; this may not be the case. In this case, use enough components of the file's path to uniquely distinguish the file. Separate the components with &rsquo;-&rsquo; characters. The patch should apply with &ldquo;patch -p0&rdquo; from the working source directory of the port.
     64                                Patch files reside in the files/ directory in the port's base directory. There should be one patch file for every file that needs to be patched. It is perfectly reasonable to use provided patches that affect multiple files, but do not create new patches that do so. Their names should begin with "patch-". The rest of the name should come from the name of the file that they apply to. In many cases just the base name of the file being patched is enough. For files such as "Makefile" this may not be the case. In this case, use enough components of the file's path to uniquely distinguish the file. Separate the components with '-' characters. The patch should apply with "patch -p0" from the working source directory of the port.
    7665                        </para>
    7766                </sect2>
  • trunk/doc/guide/xml/variants.xml

    r1118 r2614  
    77                <title>What are Variants?</title>
    88                <para>
    9                         Darwinports allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports Darwinports supports &ldquo;variants&rdquo;.
     9                        Darwinports allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports Darwinports supports "variants".
    1010                </para>
    1111        </sect1>
     
    6969                                </listitem>
    7070                        </varlistentry>
    71                         <varlistentry id='variant-contents'>
    72                                 <term>
    73                                         foo-contents
    74                                 </term>
    75                                 <listitem>
    76                                         <para>
    77                                                 If a variant changes the installed files you should list the contents in a file named &lt;variant&gt;-contents.
    78                                         </para>
    79                                 </listitem>
    80                         </varlistentry>
    8171                </variablelist>
    8272        </sect1>
     
    123113                                        <para>
    124114                                                <userinput>
    125                                                         variant foo darwin &lcub;[variant code]&rcub;
     115                                                        variant foo darwin {[variant code]}
    126116                                                </userinput>
    127117                                        </para>
Note: See TracChangeset for help on using the changeset viewer.