Changeset 1118 for trunk/doc


Ignore:
Timestamp:
Oct 22, 2002, 2:43:57 AM (17 years ago)
Author:
michaelm
Message:

doc updates

Location:
trunk/doc/guide/xml
Files:
4 edited

Legend:

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

    r1102 r1118  
    2929                                        <member>name</member>
    3030                                        <member>version</member>
     31                                        <member>platforms</member>
    3132                                        <member>maintainers</member>
    3233                                        <member>categories</member>
     
    3637                                        <member>contents</member>
    3738                                </simplelist>
    38                         Each of these keys is described below.
     39                        Each of these keys is described in the following pages of the guide.
    3940                        </para>
    4041                               
     
    137138                                        <para>The version of the Port. By default this is used to build the url from which the Port is fetched. </para>
    138139                                        <para><userinput>version 1.23.45</userinput></para>
     140                                </listitem>
     141                        </varlistentry>
     142                        <varlistentry id='platforms'>
     143                                <term>platforms</term>
     144                                <listitem>
     145                                        <para>The platforms on which the port has been tested. </para>
     146                                        <para><userinput>platforms darwin freebsd</userinput></para>
    139147                                </listitem>
    140148                        </varlistentry>
     
    354362                                                        <listitem>
    355363                                                                <para>Environmental variables to pass to automake</para>
    356                                                                 <para><userinput>CFLAGS=&ldquo;-I&dollar;&lcub;prefix&rcub;/include&rdquo;</userinput>
     364                                                                <para><userinput>CFLAGS=&ldquo;-I&lsquo;&dollar;&lcub;prefix&rcub;/include&rsquo;&rdquo;</userinput>
    357365                                                                </para>
    358366                                                        </listitem>
     
    390398                                                        <listitem>
    391399                                                                <para>Environmental variables to pass to autoconf</para>
    392                                                                 <para><userinput>autoconf.env   CFLAGS=I&dollar;&lcub;prefix&rcub;/include/gtk12</userinput>
     400                                                                <para><userinput>autoconf.env   CFLAGS=-I&lsquo;&dollar;&lcub;prefix&rcub;/include/gtk12&rsquo;</userinput>
    393401                                                                </para>
    394402                                                        </listitem>
     
    422430                                                        <listitem>
    423431                                                                <para>Set environment variables for configure.</para>
    424                                                                 <para><userinput>configure.env CFLAGS=&ldquo;-I&dollar;&lcub;prefix&rcub;/include&rdquo;</userinput>
     432                                                                <para><userinput>configure.env CFLAGS=&ldquo;-I&lsquo;&dollar;&lcub;prefix&rcub;/include&rsquo;&rdquo;</userinput>
    425433                                                                </para>
    426434                                                        </listitem>
     
    431439                                                        <listitem>
    432440                                                                <para>Arguments added to configure command before &dollar;&lcub;configure.args&rcub;. Defaults to --prefix=&dollar;&lcub;prefix&rcub;. </para>
    433                                                                 <para><userinput>configure.pre_args       --prefix=&dollar;&lcub;prefix&rcub;/apache2</userinput>
     441                                                                <para><userinput>configure.pre_args       --prefix=&ldquo;&dollar;&lcub;prefix&rcub;/apache2&rdquo;</userinput>
    434442                                                                </para>
    435443                                                        </listitem>
     
    440448                                                        <listitem>
    441449                                                                <para>Arguments to pass to configure.</para>
    442                                                                 <para><userinput>configure.args      --etcdir=&dollar;&lcub;prefix&rcub;/etc</userinput>
     450                                                                <para><userinput>configure.args      --etcdir=&ldquo;&dollar;&lcub;prefix&rcub;/etc&rdquo;</userinput>
    443451                                                                </para>
    444452                                                        </listitem>
  • trunk/doc/guide/xml/quick.xml

    r1111 r1118  
    199199
    200200depends_lib     lib:libexpat.0.4:expat
    201 configure.env   LDFLAGS=-L$prefix/lib CPPFLAGS=-I$prefix/include
     201configure.env   LDFLAGS='-L"${prefix}/lib"' CPPFLAGS='-I"${prefix}/include"'
    202202
    203203configure.args  --with-ssl \
     
    245245                                                        </para>
    246246                                                        <para>
    247                                                                 By default the configure script is passed --prefix=${prefix} where ${prefix} is replaced with the prefix darwinports is configured to install into.
    248                                                         </para>
     247                                                                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.
     248                                                        </para>
     249                                                        <tip>
     250                                                                <para>
     251                                                                        In general you should quote variables like &lcub;prefix&rcub; in case the path has a space in it.
     252                                                                </para>
     253                                                        </tip>
    249254                                                </listitem>
    250255                                        </varlistentry>
  • trunk/doc/guide/xml/style.xml

    r1112 r1118  
    6464                                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. In these cases it may also make sense to use &ldquo;&lcub;&rcub;&rdquo; braces to group the file names instead of continuing across lines by escaping newlines, although this breaks the consistancy of symbol usage within the port file. 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.
    6565                        </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>
    6671                </sect2>
    6772                <sect2>
  • trunk/doc/guide/xml/variants.xml

    r1102 r1118  
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    4 
    54<chapter>
    6     <title>Variants</title>
    7     <sect1>
    8         <title>What are Variants?</title>
    9         <para></para>
    10                 <sect2>
    11                         <title>Syntax</title>
    12                         <para></para>
    13                         <sect3>
    14                                 <title>*-append and *-delete</title>
    15                                 <para></para>
    16                         </sect3>
    17                 </sect2>
     5        <title>Variants</title>
     6        <sect1>
     7                <title>What are Variants?</title>
     8                <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;.
     10                </para>
    1811        </sect1>
    1912        <sect1>
    20         <title>Advanced Variants</title>
    21         <para></para>
    22                 <sect2>
    23                         <title>Architechture Specific Variants</title>
    24                         <para></para>
    25                 </sect2>
    26                 <sect2>
    27                         <title>Default Variants</title>
    28                         <para></para>
    29                 </sect2>
     13                <title>Syntax</title>
     14                <para>
     15                        The variants syntax is largely identical to the syntax in the main part of the Portfile.
     16                </para>
     17                <variablelist>
     18                        <varlistentry id='variant'>
     19                                <term>
     20                                        variant
     21                                </term>
     22                                <listitem>
     23                                        <para>
     24                                                The key variant is used to begin the foo variant as shown in the example.
     25                                                <programlisting>
     26<![CDATA[
     27variant foo    {
     28                              [variant code]
     29                              [more variant code]
     30                 }
     31]]>
     32                                                </programlisting>
     33                                        </para>
     34                                        <para>
     35                                                Within the variant block essentially all of the keys available in the main section are available. Using a key used in the main section will overwrite it.
     36                                        </para>
     37                                </listitem>
     38                        </varlistentry>
     39                        <varlistentry id='append'>
     40                                <term>
     41                                        append
     42                                </term>
     43                                <listitem>
     44                                        <para>
     45                                                For most of the keys you can append additional terms.
     46                                                <programlisting>
     47<![CDATA[
     48variant foo    { configure.args-append --with-x}
     49
     50]]>
     51                                                </programlisting>
     52                                        </para>
     53                                </listitem>
     54                        </varlistentry>
     55                        <varlistentry id='delete'>
     56                                <term>
     57                                        delete
     58                                </term>
     59                                <listitem>
     60                                        <para>
     61                                                For most of the keys you can delete terms. The item being deleted should match a string in the option being deleted exactly.
     62                                                <programlisting>
     63<![CDATA[
     64variant gnome    { configure.args-delete --without-gnome}
     65
     66]]>
     67                                                </programlisting>
     68                                        </para>
     69                                </listitem>
     70                        </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>
     81                </variablelist>
     82        </sect1>
     83        <sect1>
     84                <title>Advanced Variants</title>
     85                <para>
     86                        For the most part, variants are quite straightforward to use. Several more advanced features of variants are also available.
     87                </para>
     88                <variablelist>
     89                        <varlistentry id='default_variants'>
     90                                <term>
     91                                        default_variants
     92                                </term>
     93                                <listitem>
     94                                        <para>
     95                                                In some cases you may want a variant or variants to be executed by default. For example w3m is distributed with a patch to add international text support. This is a vendor provided patch, but not a core part of the program. In this case it makes sense to make the internationalised version the default, but keep the vanilla w3m as the main port. The default_variants key is used in the main section of a Portfile, not in a variant.
     96                                        </para>
     97                                        <para>
     98                                                <userinput>
     99                                                        default_variants +foo +bar
     100                                                </userinput>
     101                                        </para>
     102                                </listitem>
     103                        </varlistentry>
     104                        <varlistentry id='platform_variants'>
     105                                <term>
     106                                        platform_variants
     107                                </term>
     108                                <listitem>
     109                                        <para>
     110                                                Platform specific variants are automatically executed on that platform, without needing any intervention from the user. Currently available platforms are:
     111                                                <simplelist>
     112                                                        <member>
     113                                                                darwin
     114                                                        </member>
     115                                                        <member>
     116                                                                freebsd
     117                                                        </member>
     118                                                        <member>
     119                                                                linux
     120                                                        </member>
     121                                                </simplelist>
     122                                        </para>
     123                                        <para>
     124                                                <userinput>
     125                                                        variant foo darwin &lcub;[variant code]&rcub;
     126                                                </userinput>
     127                                        </para>
     128                                </listitem>
     129                        </varlistentry>
     130                </variablelist>
    30131        </sect1>
    31132</chapter>
    32 
Note: See TracChangeset for help on using the changeset viewer.