[28039] trunk/doc/guide/new/xml
source_changes at macosforge.org
source_changes at macosforge.org
Sat Aug 18 19:31:52 PDT 2007
Revision: 28039
http://trac.macosforge.org/projects/macports/changeset/28039
Author: markd at macports.org
Date: 2007-08-18 19:31:52 -0700 (Sat, 18 Aug 2007)
Log Message:
-----------
More cross reference links.
Modified Paths:
--------------
trunk/doc/guide/new/xml/installing.xml
trunk/doc/guide/new/xml/portfiledev.xml
trunk/doc/guide/new/xml/portfileref.xml
trunk/doc/guide/new/xml/using.xml
Modified: trunk/doc/guide/new/xml/installing.xml
===================================================================
--- trunk/doc/guide/new/xml/installing.xml 2007-08-18 22:54:13 UTC (rev 28038)
+++ trunk/doc/guide/new/xml/installing.xml 2007-08-19 02:31:52 UTC (rev 28039)
@@ -5,9 +5,11 @@
<title>Installing MacPorts</title>
<para>This chapter show you how to install MacPorts and its prerequistes
- step-by-step. Note that sections 2 to 4 are Mac OS X specific. If you wish
- to install MacPorts on FreeBSD, first make sure you have gcc and X11
- installed, and then begin with section 5.</para>
+ step-by-step. Note that sections 1 through 3 are Mac OS X specific. If you
+ wish to install MacPorts on FreeBSD, first make sure you have gcc and X11
+ installed, and then begin with section <link
+ linkend="installing-macports.install.macports.source">Install MacPorts -
+ Source</link>.</para>
<section id="installing-macports.install.xcode.tools">
<title>Install Xcode Tools</title>
@@ -121,9 +123,10 @@
<para>If you wish to install MacPorts to a path other than
<filename>/opt/local</filename> do not install the MacPorts binary —skip
- this section and proceed to the next to install MacPorts from the source
- code. The MacPorts binary installer will only install to
- <filename>/opt/local</filename>.</para>
+ this section and <link
+ linkend="installing-macports.install.macports.source">install MacPorts
+ from the source code</link>. The MacPorts binary installer will only
+ install to <filename>/opt/local</filename>.</para>
<orderedlist>
<listitem>
@@ -142,19 +145,22 @@
</orderedlist>
<note>
- <para>A MacPorts selfupdate operation (see below) will automatically
- update to the latest release if the binary .dmg image is behind the
- latest released tarball.</para>
+ <para>A MacPorts <link
+ linkend="installing-macports.selfupdate">selfupdate</link> operation
+ will automatically update to the latest release if the binary .dmg image
+ is behind the latest released tarball.</para>
</note>
</section>
<section id="installing-macports.install.macports.source">
<title>Install MacPorts - Source</title>
- <para>Installing from source on Mac OS X is only necessary If you wish to
- install to a path other than <filename>/opt/local</filename>, so If you
- installed MacPorts using the binary installer, skip this section. If you
- wish to install MacPorts on FreeBSD you must install from source.</para>
+ <para>If you installed MacPorts using the binary installer, skip this
+ section. Installing from source on Mac OS X is only necessary if you wish
+ to install to a path other than <filename>/opt/local</filename>, or if you
+ wish to install a non-release version of MacPorts base. You must also
+ install MacPorts from source if you wish to install MacPorts on a platform
+ other than Mac OS X.</para>
<orderedlist>
<listitem>
@@ -174,9 +180,10 @@
</orderedlist>
<note>
- <para>A MacPorts' selfupdate (see below) will automatically update to
- the latest release if the binary .dmg image is behind the latest
- released tarball.</para>
+ <para>A MacPorts <link
+ linkend="installing-macports.selfupdate">selfupdate</link> operation
+ will automatically update to the latest release if the binary .dmg image
+ is behind the latest released tarball.</para>
</note>
</section>
@@ -237,7 +244,7 @@
</note>
</section>
- <section>
+ <section id="installing-macports.selfupdate">
<title>MacPorts Selfupdate</title>
<para>You must always do a selfupdate after a new MacPorts install, and
Modified: trunk/doc/guide/new/xml/portfiledev.xml
===================================================================
--- trunk/doc/guide/new/xml/portfiledev.xml 2007-08-18 22:54:13 UTC (rev 28038)
+++ trunk/doc/guide/new/xml/portfiledev.xml 2007-08-19 02:31:52 UTC (rev 28039)
@@ -5,35 +5,33 @@
<title>Portfile Development</title>
<para>This chapter covers a brief introduction to Portfiles, how to create a
- local <filename>Portfile</filename> repository for development, and creating
- Portfiles.</para>
+ local Portfile repository for development, and creating Portfiles.</para>
<section id="portfile-development.portfile.introduction">
<title>Portfile Introduction</title>
- <para>A MacPorts <filename>Portfile</filename> is a TCL script that
- usually contains only the simple keyword/value combinations and Tcl
- extensions as described in the Portfile Reference section below, though it
- may also contain arbitrary TCL code. Every port has a corresponding
- <filename>Portfile</filename>, but Portfiles do not completely define a
- port's installation behavior since the MacPorts base has default port
+ <para>A MacPorts Portfile is a TCL script that usually contains only the
+ simple keyword/value combinations and Tcl extensions as described in the
+ <link linkend="portfile-reference">Portfile Reference</link> chapter,
+ though it may also contain arbitrary TCL code. Every port has a
+ corresponding Portfile, but Portfiles do not completely define a port's
+ installation behavior since the MacPorts base has default port
installation characteristics coded within it. Therefore Portfiles need
only specify required options and, when required, non-default
characteristics for a port.</para>
<para>A common way for Portfiles to augment or override MacPorts base
default installation phase characteristics is by using
- <filename>Portfile</filename> phase declaration(s). If you use
- <filename>Portfile</filename> phase declaration(s), you should know how to
- identify the "global" section of a <filename>Portfile</filename>. Any
- statements not contained within a phase declaration, no matter where they
- are located in a <filename>Portfile</filename>, are said to be in the
- global section of the <filename>Portfile</filename>, therefore the global
- section need not be contiguous. Likewise, to remove statements from the
- global section they must be placed within a phase declaration.</para>
+ <filename>Portfile</filename> phase declaration(s). If you use Portfile
+ phase declaration(s), you should know how to identify the "global" section
+ of a Portfile. Any statements not contained within a phase declaration, no
+ matter where they are located in a Portfile are said to be in the global
+ section of the Portfile, therefore the global section need not be
+ contiguous. Likewise, to remove statements from the global section they
+ must be placed within a phase declaration.</para>
- <para>The main phases you need to be aware of when making a
- <filename>Portfile</filename> are these:</para>
+ <para>The main phases you need to be aware of when making a Portfile are
+ these:</para>
<itemizedlist>
<listitem>
@@ -67,21 +65,21 @@
install</command> steps, which conform to phases configure, build, and
destroot respectively. For applications that do not conform to this
standard behavior, any installation phase may be augmented using pre-
- and/or post- phases, or even overridden or eliminated. See the section
- "Example Portfiles" below.</para>
+ and/or post- phases, or even overridden or eliminated. See <link
+ linkend="portfile-development.example.portfiles">Example Portfiles</link>
+ below.</para>
<note>
- <para>For a detailed description of all port phases, see the section
- "Portfile Reference" below.</para>
+ <para>For a detailed description of all port phases, see the <link
+ linkend="portfile-reference">Portfile Reference</link> chapter.</para>
</note>
</section>
<section id="portfile-development.local.portfile.repositories">
<title>Local Portfile Repositories</title>
- <para>To create and test <filename>Portfile</filename>s that are not yet
- committed to subversion, you may create a local
- <filename>Portfile</filename> repository as shown.</para>
+ <para>To create and test Portfiles that are not yet committed to
+ subversion, you may create a local Portfile repository as shown.</para>
<orderedlist>
<listitem>
@@ -102,18 +100,17 @@
<note>
<para>The file URL should always appear before the rsync URL so that
- local <filename>Portfile</filename>s can be tested that are
- duplicated in the MacPorts tree, because the <command>port</command>
- command will always operate on the first
- <filename>Portfile</filename> it encounters.</para>
+ local Portfiles can be tested that are duplicated in the MacPorts
+ tree, because the <command>port</command> command will always
+ operate on the first Portfile it encounters.</para>
</note>
</listitem>
<listitem>
- <para>Place the <filename>Portfile</filename>s you create inside a
- directory whose name matches the port, which should in turn be placed
- inside a directory that reflect the port's primary category (the first
- category entry in the <filename>Portfile</filename>).</para>
+ <para>Place the Portfiles you create inside a directory whose name
+ matches the port, which should in turn be placed inside a directory
+ that reflect the port's primary category (the first category entry in
+ the Portfile).</para>
<programlisting><prompt>%%</prompt> <userinput>cd /Users/julesverne</userinput>
<prompt>%%</prompt> <userinput>mkdir -p ports/games/bestevergame</userinput>
@@ -122,9 +119,9 @@
</listitem>
<listitem>
- <para>After a <filename>Portfile</filename> is created (see below),
- use the MacPorts <command>portindex</command> command in the local
- repository's directory to install it into the
+ <para>After a Portfile is created (see below), use the MacPorts
+ <command>portindex</command> command in the local repository's
+ directory to install it into the
<filename>Portindex</filename>.</para>
<programlisting>%% <userinput>cd /Users/julesverne/ports</userinput>
@@ -141,7 +138,7 @@
<para>Once the local port is added to the <filename>Portindex</filename>,
it becomes available for searching or installation as with any other
- <filename>Portfile</filename> in the MacPorts tree as shown.</para>
+ Portfile in the MacPorts tree as shown.</para>
<programlisting><prompt>%%</prompt> <userinput>port search bestever</userinput></programlisting>
@@ -151,19 +148,18 @@
<section id="portfile-development.creating.a.portfile">
<title>Creating a Portfile</title>
- <para>Here we list the individual <filename>Portfile</filename> components
- for an application that conforms to the the standard <command>
- configure</command>, <command>make</command>, and <command>make
- install</command> steps of most open source application installs.</para>
+ <para>Here we list the individual Portfile components for an application
+ that conforms to the the standard <command> configure</command>,
+ <command>make</command>, and <command>make install</command> steps of most
+ open source application installs.</para>
<orderedlist>
<listitem>
<para>Subversion ID tag line</para>
- <para>The first line of a new <filename>Portfile</filename> must be
- set as shown. When a port is committed to subversion, ID tags are
- expanded to include the last person to commit and the commit
- time.</para>
+ <para>The first line of a new Portfile must be set as shown. When a
+ port is committed to subversion, ID tags are expanded to include the
+ last person to commit and the commit time.</para>
<programlisting># $Id$</programlisting>
</listitem>
@@ -193,7 +189,7 @@
<para>A port may belong to more than one category, but the first
(primary) category should match the directory name in the ports tree
- where the <filename>Portfile</filename> is to reside.</para>
+ where the Portfile is to reside.</para>
<programlisting>categories net</programlisting>
</listitem>
@@ -206,7 +202,8 @@
keyword lists maintainer email addresses(s). To hide these addresses
from spambots, see the more full explanation of the maintainer keyword
in the <link linkend="portfile-reference.keywords.global">Global
- Keywords</link> section of the Portfile Reference.</para>
+ Keywords</link> section of the <link
+ linkend="portfile-reference">Portfile Reference</link> chapter.</para>
<programlisting>maintainers julesverne at somedomain.org</programlisting>
@@ -250,8 +247,8 @@
<listitem>
<para>Port checksums</para>
- <para>The checksums specified in a <filename>Portfile</filename> are
- checked with the fetched tarball for security.</para>
+ <para>The checksums specified in a Portfile are checked with the
+ fetched tarball for security.</para>
<programlisting>checksums md5 dafa161bc9c61e57636a6085c87c1fe8</programlisting>
</listitem>
@@ -365,18 +362,15 @@
<para>Variants are a way for port authors to provide options that may be
invoked at install time. They are declared in the global section of a
- <filename>Portfile</filename> using the "variant" keyword and may provide
- a description.</para>
+ Portfile using the "variant" keyword and may provide a description.</para>
<section id="portfile-development.port.variants.modify.options">
<title>Variants to Modify Options</title>
<para>The most common use for a variant is to add or remove
dependencies, configure arguments, and build arguments from the global
- <filename>Portfile</filename> section. Here is an example of a port
- providing four variants that add additional configure arguments to a
- port. See "Variants" in the Portfile Reference section for full
- information.</para>
+ Portfile section. Here is an example of a port providing four variants
+ that add additional configure arguments to a port.</para>
<programlisting>variant pop { configure.args-append --enable-pop }
variant imap { configure.args-append --enable-imap }
@@ -439,7 +433,7 @@
<note>
<para>The default_variant keyword may only be used in the global
- <filename>Portfile</filename> section.</para>
+ Portfile section.</para>
</note>
</section>
</section>
@@ -455,15 +449,14 @@
<section id="portfile-development.patch.files.portfile.patches">
<title>Creating Portfile Patches</title>
- <para>If you wish to contribute modifications or fixes to a
- <filename>Portfile</filename>, you should do so in the form of a
- patch.</para>
+ <para>If you wish to contribute modifications or fixes to a Portfile,
+ you should do so in the form of a patch.</para>
<orderedlist>
<listitem>
- <para>Make a copy of the <filename>Portfile</filename> you wish to
- modify; both files must be in the same directory, though it may be
- any directory.</para>
+ <para>Make a copy of the Portfile you wish to modify; both files
+ must be in the same directory, though it may be any
+ directory.</para>
<programlisting><prompt>%%</prompt> <userinput>cp Portfile Portfile.org</userinput></programlisting>
</listitem>
@@ -483,8 +476,8 @@
<listitem>
<para>A patch file that is a "unified" diff file is the easiest to
interpret by humans and this type should always be used for ports.
- The <filename>Portfile</filename> patch below will change the
- version and checksums when applied.</para>
+ The Portfile patch below will change the version and checksums when
+ applied.</para>
<programlisting>--- Portfile.org 2007-07-25 18:52:12.000000000 -0700
+++ Portfile 2007-07-25 18:53:35.000000000 -0700
@@ -592,8 +585,8 @@
<orderedlist>
<listitem>
<para>Change to the directory containing the file to be patched. In
- this example, we'll apply a <filename>Portfile</filename> patch to
- the postfix port.</para>
+ this example, we'll apply a Portfile patch to the postfix
+ port.</para>
<programlisting><prompt>%%</prompt> <userinput>cd /opt/local/var/macports/sources/rsync.macports.org/release/ports/mail/postfix</userinput></programlisting>
</listitem>
Modified: trunk/doc/guide/new/xml/portfileref.xml
===================================================================
--- trunk/doc/guide/new/xml/portfileref.xml 2007-08-18 22:54:13 UTC (rev 28038)
+++ trunk/doc/guide/new/xml/portfileref.xml 2007-08-19 02:31:52 UTC (rev 28039)
@@ -15,9 +15,12 @@
perform default steps for applications that use the standard
<command>configure</command>, <command>make</command>, and <command>make
install</command> steps, but for applications that do not conform to this
- behavior, installation phases may be declared in a Portfile to override or
- eliminate the default behavior, or augment it using pre- and/or post-
- phases as shown in the section "Portfile Development".</para>
+ behavior, installation phases may be declared in a Portfile to <link
+ linkend="portfile-development.example.portfiles.pre.post">augment</link>
+ or <link
+ linkend="portfile-development.example.portfiles.override">override</link>
+ the default behavior as described in the <link
+ linkend="portfile-development">Portfile Development</link> chapter.</para>
<section id="portfile-reference.port.phases.fetch">
<title>Fetch</title>
@@ -123,8 +126,10 @@
<title>Install</title>
<para>Overview: Copy a port's destrooted files into
- <filename>${prefix}/var/macports/software</filename>. See "Port Images"
- in section "MacPorts Internals" for details.</para>
+ <filename>${prefix}/var/macports/software</filename>. See <link
+ linkend="macports-internals.port.images">Port Images</link> in the <link
+ linkend="macports-internals">MacPorts Internals</link> chapter for
+ details.</para>
</section>
<section id="portfile-reference.port.phases.activate">
@@ -132,7 +137,8 @@
<para>Overview: Set <ulink
url="http://en.wikipedia.org/wiki/Hard_link">hardlinks</ulink> pointing
- to ${prefix}/var/macports/software to point to ${prefix}.</para>
+ to <filename>${prefix}/var/macports/software</filename> to point to
+ ${prefix}.</para>
</section>
</section>
Modified: trunk/doc/guide/new/xml/using.xml
===================================================================
--- trunk/doc/guide/new/xml/using.xml 2007-08-18 22:54:13 UTC (rev 28038)
+++ trunk/doc/guide/new/xml/using.xml 2007-08-19 02:31:52 UTC (rev 28039)
@@ -4,9 +4,9 @@
<chapter id="using-macports">
<title>Using MacPorts</title>
- <para>This chapter describes the MacPorts file hierarchy, using the
- <command>port</command> command, creating port binaries, and setting up an
- rsync replication server.</para>
+ <para>This chapter describes using the <command>port</command> command, port
+ variants, common tasks, port binaries, and setting up an rsync replication
+ server.</para>
<section id="using-macports.port.command">
<title>The port Command</title>
@@ -122,8 +122,9 @@
<para>The <option>variants</option> option allows you to check what
variations of a port are available before you install it. Variants are a
way for port authors to provide options that may be invoked at install
- time. See the Variants" section below to see how to invoke
- variants.</para>
+ time. See <link
+ linkend="using-macports.port.variants.invoking.variants">Invoking Port
+ Variants</link> below to install ports that have variants.</para>
<programlisting><prompt>%%</prompt> <userinput>port variants nmap</userinput></programlisting>
@@ -137,8 +138,9 @@
<section id="using-macports.port.command.install">
<title>install</title>
- <para>The option <option>install</option> is used to install a
- port.</para>
+ <para>The option <option>install</option> is used to install a port. See
+ <link linkend="using-macports.port.variants.invoking.variants">Invoking
+ Port Variants</link> below to install ports that have variants.</para>
<programlisting><prompt>%%</prompt> <userinput>sudo port install nmap</userinput></programlisting>
@@ -148,8 +150,6 @@
installation phase such as fetch, configure, build, or
destroot.</para>
</note>
-
- <programlisting><prompt>%%</prompt> <userinput>sudo port install nmap +no_ssl</userinput></programlisting>
</section>
<section id="using-macports.port.command.clean">
@@ -263,9 +263,15 @@
<note>
<para>The <option>upgrade</option> option by default does not
- uninstall an upgraded port —it deactivates it (see section Port
- Installation Phases below). If you wish to uninstall the old version
- use the -u option.</para>
+ uninstall an upgraded port —it deactivates it. See section <link
+ linkend="macports-internals.port.images">Port Images</link>, and also
+ <link
+ linkend="portfile-reference.port.phases.destroot">Destroot</link> and
+ <link
+ linkend="portfile-reference.port.phases.activate">Activate</link>
+ phases in <link linkend="portfile-reference.port.phases">Port
+ Phases</link>. If you wish to uninstall the old version use the -u
+ option.</para>
<programlisting><prompt>%%</prompt> <userinput>port -u upgrade vile</userinput></programlisting>
</note>
@@ -336,10 +342,11 @@
<section id="using-macports.port.variants.negating.default.variants">
<title>Negating Default Variants</title>
- <para>For an explanation of default variants, see the "Port Development"
- section. Default variants are optional, and not all ports using variants
- have them. For ports with default variants, you may install a port
- without them by negating default variants using "-" as shown.</para>
+ <para>For an explanation of default variants see <link
+ linkend="portfile-development.port.variants">Port Variants</link>.
+ Default variants are optional, and not all ports using variants have
+ them. For ports with default variants, you may install a port without
+ them by negating default variants using "-" as shown.</para>
<programlisting><prompt>%%</prompt> <userinput>port install fetchmail -ssl</userinput></programlisting>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070818/a99532ad/attachment.html
More information about the macports-changes
mailing list