[134973] trunk/base/doc

cal at macports.org cal at macports.org
Sun Apr 12 12:08:55 PDT 2015


Revision: 134973
          https://trac.macports.org/changeset/134973
Author:   cal at macports.org
Date:     2015-04-12 12:08:55 -0700 (Sun, 12 Apr 2015)
Log Message:
-----------
base: doc: (re-)generate roff from asciidoc, enable new manpages

Modified Paths:
--------------
    trunk/base/doc/Makefile.in
    trunk/base/doc/port-fetch.1
    trunk/base/doc/port-select.1

Added Paths:
-----------
    trunk/base/doc/port-space.1
    trunk/base/doc/port-sync.1
    trunk/base/doc/port-test.1
    trunk/base/doc/port-upgrade.1
    trunk/base/doc/port-usage.1
    trunk/base/doc/port-variants.1
    trunk/base/doc/port-version.1
    trunk/base/doc/sources.conf.5

Modified: trunk/base/doc/Makefile.in
===================================================================
--- trunk/base/doc/Makefile.in	2015-04-12 19:07:49 UTC (rev 134972)
+++ trunk/base/doc/Makefile.in	2015-04-12 19:08:55 UTC (rev 134973)
@@ -74,14 +74,24 @@
 		port-selfupdate.1 \
 		port-setrequested.1 \
 		port-setunrequested.1 \
+		port-space.1 \
+		port-sync.1 \
+		port-test.1 \
 		port-uninstall.1 \
 		port-unload.1 \
 		port-unsetrequested.1 \
+		port-upgrade.1 \
 		port-url.1 \
+		port-usage.1 \
+		port-variants.1 \
+		port-version.1 \
 		port-work.1 \
 		port.1 \
 
-MAN5=		macports.conf.5
+MAN5=		\
+		macports.conf.5 \
+		sources.conf.5 \
+
 MAN7=		portfile.7 portstyle.7 porthier.7 portgroup.7 portundocumented.7
 MAN=		${MAN1} ${MAN5} ${MAN7}
 

Modified: trunk/base/doc/port-fetch.1
===================================================================
--- trunk/base/doc/port-fetch.1	2015-04-12 19:07:49 UTC (rev 134972)
+++ trunk/base/doc/port-fetch.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -1,5 +1,5 @@
 '\" t
-.TH "PORT\-FETCH" "1" "2014\-08\-24" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.TH "PORT\-FETCH" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -20,11 +20,11 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-port-fetch, port-checksum, port-extract, port-patch, port-configure, port-build, port-destroot \- Run a specific phase of a port
+port-fetch, port-checksum, port-extract, port-patch, port-configure, port-build, port-destroot, port-test \- Run a specific phase of a port
 .SH "SYNOPSIS"
 .sp
 .nf
-\fBport\fR [\fB\-vdoy\fR] [\fB\-D\fR \fIportdir\fR] [\fBfetch\fR | \fBchecksum\fR | \fBextract\fR | \fBpatch\fR | \fBconfigure\fR | \fBbuild\fR | \fBdestroot\fR]
+\fBport\fR [\fB\-vdoy\fR] [\fB\-D\fR \fIportdir\fR] [\fBfetch\fR | \fBchecksum\fR | \fBextract\fR | \fBpatch\fR | \fBconfigure\fR | \fBbuild\fR | \fBdestroot\fR | \fBtest\fR ]
      [[\fIportname\fR | \fIpseudo\-portname\fR | \fIport\-expressions\fR | \fIport\-url\fR]]
 .fi
 .SH "DESCRIPTION"
@@ -32,6 +32,8 @@
 These commands run a specific phase of a port\&. Depending phases will be executed automatically as needed\&.
 .sp
 If the \fIPortfile\fR has changed between multiple invocation, \fBport\fR will perform a clean before running the phase\&. The flag \fI\-o\fR can be used to ignore this and keep the current state of the \(lqwork\(rq dir\&.
+.sp
+Note that the \fBtest\fR phase is special in that it will not be run by MacPorts by default\&. When supported by the given port, the \fBtest\fR phase will run the testcases of the software\&.
 .SH "GLOBAL OPTIONS"
 .sp
 Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.

Modified: trunk/base/doc/port-select.1
===================================================================
--- trunk/base/doc/port-select.1	2015-04-12 19:07:49 UTC (rev 134972)
+++ trunk/base/doc/port-select.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -1,5 +1,5 @@
 '\" t
-.TH "PORT\-SELECT" "1" "2015\-02\-08" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.TH "PORT\-SELECT" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -24,19 +24,19 @@
 .SH "SYNOPSIS"
 .sp
 .nf
-\fBport\fR [\fB\-dvp\fR] \fBselect\fR \-\-summary
+\fBport\fR [\fB\-dv\fR] \fBselect\fR \-\-summary
 .fi
 .sp
 .nf
-\fBport\fR [\fB\-dvp\fR] \fBselect\fR \-\-show \fIgroup\fR
+\fBport\fR [\fB\-dv\fR] \fBselect\fR \-\-show \fIgroup\fR
 .fi
 .sp
 .nf
-\fBport\fR [\fB\-dvp\fR] \fBselect\fR [\-\-list] \fIgroup\fR
+\fBport\fR [\fB\-dv\fR] \fBselect\fR [\-\-list] \fIgroup\fR
 .fi
 .sp
 .nf
-\fBport\fR [\fB\-dvp\fR] \fBselect\fR [\-\-set] \fIgroup\fR \fIoption\fR
+\fBport\fR [\fB\-dv\fR] \fBselect\fR [\-\-set] \fIgroup\fR \fIoption\fR
 .fi
 .SH "DESCRIPTION"
 .sp

Added: trunk/base/doc/port-space.1
===================================================================
--- trunk/base/doc/port-space.1	                        (rev 0)
+++ trunk/base/doc/port-space.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,128 @@
+'\" t
+.TH "PORT\-SPACE" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-space \- Show the disk usage of the given ports
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-D\fR \fIportdir\fR]  \fBspace\fR [\-\-units \fIunit\fR] [\fItotal\fR]
+    [[\fIportname\fR | \fIpseudo\-portname\fR | \fIport\-expressions\fR | \fIport\-url\fR]]
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport space\fR lists the amount of disk space the port(s) given on the command line occupy on disk\&. Note that the space reported is for the files installed by a port, but not the image of the port\(cqs files MacPorts keeps internally\&. See the \fBPORT IMAGES\fR section for more information on how images work\&. Consequently, \fBport space\fR will only work on active ports\&.
+.sp
+By default, \fBport space\fR will print a line with the size in an appropriate unit followed by the name of a port for each port given on the command line (or expanded from a pseudo\-port expression given; see \fBport\fR(1) for more info on pseudo\-port expressions)\&. The last line of output will contain a total\&.
+.sp
+If you are only interested in the total of all ports (e\&.g\&. if you want to get the total amount of space used by your installed ports) use the \fB\-\-total\fR flag\&. If you want to sort the output by file size, you can pipe the results of \fBport space\fR to \fBsort \-n\fR\&. Since \fBport space\fR defauts to using a suitable unit, you should specify a unit to allow for meaningful numeric sorting, e\&.g\&. \fBport space \-\-units KiB\fR to get all output in KiB\&.
+.SH "OPTIONS"
+.PP
+\fB\-\-total\fR*
+.RS 4
+Only print the total amount of space used by all given ports\&.
+.RE
+.PP
+\fB\-\-units \fR\fB\fIunit\fR\fR
+.RS 4
+Choose the unit in which the size is given\&. You should specify this if you intend to sort the output\&. Valid values for
+\fIunit\fR
+are
+.PP
+\fBB\fR
+.RS 4
+List sizes in bytes\&.
+.RE
+.PP
+\fBK\fR, \fBKi\fR, \fBKiB\fR
+.RS 4
+List sizes in KiB, i\&.e\&., 1024 bytes\&.
+.RE
+.PP
+\fBMi\fR, \fBMiB\fR
+.RS 4
+List sizes in MiB, i\&.e\&., 1024 * 1024 bytes\&.
+.RE
+.PP
+\fBGi\fR, \fBGiB\fR
+.RS 4
+List sizes in GiB, i\&.e\&., 1024 * 1024 * 1024 bytes\&.
+.RE
+.PP
+\fBk\fR, \fBkB\fR
+.RS 4
+List sizes in kB, i\&.e\&., 1000 bytes\&.
+.RE
+.PP
+\fBM\fR, \fBMB\fR
+.RS 4
+List sizes in MB, i\&.e\&., 1000 * 1000 bytes\&.
+.RE
+.PP
+\fBG\fR, \fBGB\fR
+.RS 4
+List sizes in GB, i\&.e\&., 1000 * 1000 * 1000 bytes\&.
+.RE
+.RE
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.SH "PORT IMAGES"
+.sp
+MacPorts has the ability to install multiple versions or different variant selections of the same port\&. The files will be stored in an intermediate location as \fIarchives\fR, which allows to switch between the versions\&. Only one version can be active at a time\&. On activation, files will be copied to their intended place in \fIprefix\fR\&.
+.sp
+More information on this topic can be found in the \m[blue]\fBThe MacPorts Guide\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.sp
+To check the current status of a specific port, use \fB\fBport-installed\fR(1)\fR\&.
+.SH "EXAMPLES"
+.sp
+To find the 10 largest ports in your MacPorts installation, you can use the following command:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port space \-\-units MiB active | sort \-rn | head \-n10
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBport-archive\fR(1), \fBsort\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXTERNAL REFERENCES"
+.IP " 1." 4
+The MacPorts Guide
+.RS 4
+\%http://guide.macports.org/#internals.images
+.RE

Added: trunk/base/doc/port-sync.1
===================================================================
--- trunk/base/doc/port-sync.1	                        (rev 0)
+++ trunk/base/doc/port-sync.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,72 @@
+'\" t
+.TH "PORT\-SYNC" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-sync \- Update the port definition files
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-qvd\fR] \fBsync\fR
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport sync\fR updates the local port definitions (the so\-called ports tree) to the latest state so you have the latest versions of ports available\&. You should normally not run \fBport sync\fR directly, but use \fBport selfupdate\fR, which updates MacPorts itself and then proceeds to do the same operation as \fBsync\fR does\&. You can, however, use \fBport sync\fR if you know that \fBselfupdate\fR does not work on your system or in your network environment, for example because your network administrator blocks outbound rsync connections and you have changed your \fBsources.conf\fR(5) to use a different method of obtaining the ports tree\&.
+.sp
+Running \fBsync\fR is required to get updated software with bug fixes and new features\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBWarning\fR
+.ps -1
+.br
+.sp
+When you use \fBport sync\fR, it is your responsibility to check whether new updates are available for MacPorts itself, and update them, when necessary\&. The MacPorts project will start to use new features in port definitions one week after the release of the new version, and you may run into problems when your MacPorts version has not been updated\&.
+.sp .5v
+.RE
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.PP
+\fB\-q\fR
+.RS 4
+Supress status output, be as silent as possible\&.
+.RE
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBport-selfupdate\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}

Added: trunk/base/doc/port-test.1
===================================================================
--- trunk/base/doc/port-test.1	                        (rev 0)
+++ trunk/base/doc/port-test.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1 @@
+.so man1/port-fetch.1

Added: trunk/base/doc/port-upgrade.1
===================================================================
--- trunk/base/doc/port-upgrade.1	                        (rev 0)
+++ trunk/base/doc/port-upgrade.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,135 @@
+'\" t
+.TH "PORT\-UPGRADE" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-upgrade \- Upgrade a port to the latest version
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-vdqysbckpotf\fR] [\fB\-D\fR \fIportdir\fR] \fBupgrade\fR
+     [\-\-enforce\-variants] [\-\-force] [\-\-no\-replace] [\-\-no\-rev\-upgrade]
+     [[\fIportname\fR | \fIpseudo\-portname\fR | \fIport\-expressions\fR | \fIport\-url\fR]]
+     [+/\-variant \&...]
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport upgrade\fR will upgrade the given installed ports to the latest available version\&. To upgrade a port, MacPorts needs an updated port definition, which can be obtained using the \fBport-selfupdate\fR(1) command\&. You should regularly run \fBselfupdate\fR followed by \fBupgrade outdated\fR to make sure your system has the latest versions and bug fixes\&.
+.sp
+When specifying variants during upgrade, the order of precedence is
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+variants specified on the command line
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+variants active in the latest installed version of the port
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+variants specified in
+\fBvariants.conf\fR(5)
+.RE
+.sp
+In most cases, you should specify the \fBoutdated\fR pseudo\-port expression as argument to \fBport upgrade\fR to upgrade all ports where a newer version is available\&. See \fBport\fR(1) for more information on pseudo\-port expressions\&.
+.SH "OPTIONS"
+.PP
+\fB\-\-enforce\-variants\fR
+.RS 4
+Upgrade all given ports and their dependencies where the installed variants do not match those requested on the command line, even if those ports aren\(cqt outdated\&.
+.RE
+.PP
+\fB\-\-force\fR
+.RS 4
+Ignore circumstances that would normally cause ports to be skipped, such as not being outdated\&.
+.RE
+.PP
+\fB\-\-no\-replace\fR
+.RS 4
+Do not automatically install ports that replace a now\-obsolete port you have installed\&.
+.RE
+.PP
+\fB\-\-no\-rev\-upgrade\fR
+.RS 4
+Do not run rev\-upgrade after upgrading\&. See
+\fBport-rev-upgrade\fR(1)
+for more information\&.
+.RE
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.PP
+\fB\-f\fR
+.RS 4
+Upgrade a port, even if it is not outdated\&.
+.RE
+.PP
+\fB\-n\fR
+.RS 4
+Only upgrade the given ports and avoid upgrading their dependencies\&. This flag may be useful when combined with
+\fB\-\-enforce\-variants\fR\&.
+
+WARNING: Ports expect their dependencies to always be at the latest version, which is why MacPorts upgrades dependencies first\&. Do not specify this flag if you don\(cqt know what you are doing\&.
+.RE
+.PP
+\fB\-p\fR
+.RS 4
+Keep going and attempt to upgrade the next port when a port fails to build\&.
+
+WARNING: This option is harmful to
+\fBupgrade\fR
+and should be avoided at all cost\&. Often, MacPorts ports are only upgraded to rebuild them against updated dependencies\&. Specifying this flag will cause a spurious rebuild if a dependency of a port fails to build and leave your system in a broken state once the dependent port is fixed\&.
+.RE
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBport-uninstall\fR(1), \fBport-info\fR(1), \fBport-variants\fR(1), \fBport-rev-upgrade\fR(1), \fBport-setrequested\fR(1), \fBvariants.conf\fR(5)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}

Added: trunk/base/doc/port-usage.1
===================================================================
--- trunk/base/doc/port-usage.1	                        (rev 0)
+++ trunk/base/doc/port-usage.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,46 @@
+'\" t
+.TH "PORT\-USAGE" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-usage \- Show a short command synopsis summary for the port command
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR \fBusage\fR
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport usage\fR displays a very brief summary of all possible options of \fBport\fR(1) and the canonical order in which port expects them\&. It prints the \fBSYNOPSIS\fR port of the \fBport\fR(1) manpage\&.
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}

Added: trunk/base/doc/port-variants.1
===================================================================
--- trunk/base/doc/port-variants.1	                        (rev 0)
+++ trunk/base/doc/port-variants.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,88 @@
+'\" t
+.TH "PORT\-VARIANTS" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-variants \- Print a list of variants with descriptions provided by a port
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-qvd\fR] [\fB\-D\fR \fIportdir\fR] \fBvariants\fR [\-\-index]
+     [[\fIportname\fR | \fIpseudo\-portname\fR | \fIport\-expressions\fR | \fIport\-url\fR]]
+     [+/\-variant \&...]
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport variants\fR prints a list of variants provided by the port(s) given on the command line\&. Variants allow users to select certain features when installing a certain port\&. For example, the gtk3 port provides two conflicting variants \fI+quartz\fR and \fI+x11\fR that select whether Gtk uses the X11 backend (which requires an X server) or the OS X\-native Quartz backend (which attempts to provide a more native OS X look and feel)\&. In addition, many ports feature an \fI+universal\fR variant that enables building of universal (i\&.e\&. multi\-arch) binaries\&.
+.sp
+\fBport variants\fR lists all variants by name and (if available) description\&. If variants depend on or conflict with other variants, this information is printed as a bulleted list for each variant\&.
+.sp
+The output of \fBport variants\fR contains \fI[+]\fR before a variant name, if the port declares this variant as default\&. \fI(+)\fR or \fI(\-)\fR in the same spot mark variants enabled or disabled by your \fBvariants.conf\fR(5)\&. Last, a single \fI+\fR or \fI\-\fR marks variants explicitly enabled or disabled on the command line by appending \fI+variantname\fR or \fI\-variantname\fR\&.
+.SH "OPTIONS"
+.PP
+\fB\-\-index\fR
+.RS 4
+Do not read the
+\fIPortfile\fR, but rely solely on the port index information\&. Note that this will limit the output to the variant names only\&. No descriptions, dependencies or conflicts between variants will be reported\&.
+.RE
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.PP
+\fB\-q\fR
+.RS 4
+Do not print the header line\&.
+.RE
+.SH "EXAMPLES"
+.sp
+The output of \fBport variants\fR provides all available information on a port\(cqs variants\&. The gtk3 port can serve as a good example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port variants gtk3 \-universal
+gtk3 has the variants:
+(+)quartz: Support for native Mac OS X graphics
+     * conflicts with x11
+  \-universal: Build for multiple architectures
+[+]x11: Enable X11 support
+     * conflicts with quartz
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+In this case, \fI(+)\fR means that we have chosen \fI+quartz\fR as a default variant in our \fBvariants.conf\fR(5)\&. Additionally, we have explicitly disabled the universal variant on the command line, as indicated by its leading \fI\-\fR symbol\&. Finally, the port maintainer has chosen \fI+x11\fR as the default, indicated by \fI[+]\fR\&. Furthermore, the \fIquartz\fR and \fIx11\fR variants conflict with each other\&.
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}

Added: trunk/base/doc/port-version.1
===================================================================
--- trunk/base/doc/port-version.1	                        (rev 0)
+++ trunk/base/doc/port-version.1	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,54 @@
+'\" t
+.TH "PORT\-VERSION" "1" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-version \- Print the MacPorts version
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-q\fR] \fBversion\fR
+.fi
+.SH "DESCRIPTION"
+.sp
+This command prints the version of your MacPorts installation\&. You can use \fBport-selfupdate\fR(1) to update your MacPorts installation to the latest release\&.
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.PP
+\fB\-q\fR
+.RS 4
+Do not print the \(lqVersion:\(rq prefix\&.
+.RE
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBport-selfupdate\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}

Added: trunk/base/doc/sources.conf.5
===================================================================
--- trunk/base/doc/sources.conf.5	                        (rev 0)
+++ trunk/base/doc/sources.conf.5	2015-04-12 19:08:55 UTC (rev 134973)
@@ -0,0 +1,130 @@
+'\" t
+.TH "SOURCES\&.CONF" "5" "2015\-04\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+sources.conf \- port definition configuration file of the MacPorts system
+.SH "DESCRIPTION"
+.sp
+\fBsources\&.conf\fR is the configuration file used by the MacPorts system to locate its port definitions\&. The file is read by the \fBport\fR command to find available ports and how to install them\&. Entries in this file are URIs optionally followed by flags in square brackets\&. Each source specification is given on a separate line\&. A grammar in EBNF is given below:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+<line>  ::= <URI> [ \*(Aq[\*(Aq <flags> \*(Aq]\*(Aq ]
+<flags> ::= <flag> [ \*(Aq,\*(Aq [ \*(Aq \*(Aq | \*(Aq\et\*(Aq ] <flags> ]
+<flag>  ::= \*(Aqdefault\*(Aq | \*(Aqnosync\*(Aq
+.fi
+.if n \{\
+.RE
+.\}
+.SH "URI FORMATS"
+.sp
+MacPorts supports a number of different protocols as source descriptions\&.
+.PP
+\fIrsync://\fR
+.RS 4
+Followed by a server name and a path on this server, this URI instructs MacPorts to fetch the contents of the file or directory referenced by this URI into a path of its own choosing\&. This is the default method of port tree synchronization and is generally recommended\&. MacPorts will derive a machine\- and architecture\-specific URI (in the subdirectory PortIndex_${platform}_${os_major}_${os_arch}/) and attempt to download a pre\-generated PortIndex (including the PortIndex\&.quick file) from there\&.
+.PP
+\fBExample\fR
+.RS 4
+rsync://rsync\&.macports\&.org/release/tarballs/ports\&.tar
+.RE
+.PP
+\fBDefault\fR
+.RS 4
+rsync://rsync\&.macports\&.org/release/tarballs/ports\&.tar [default]
+.RE
+.RE
+.PP
+\fIfile://\fR
+.RS 4
+Followed by an absolute path (which will result in
+\fBthree\fR
+slashes at the beginning of the URI) to a local directory that should be used as port tree\&. A port index will automatically be generated for this source\&. Note that MacPorts will try to determine whether the given path is under source control and attempt to update from the default remote server if it is\&. Currently, Subversion and Git (including git\-svn) are supported options\&. You can add the
+\fInosync\fR
+tag to avoid this behavior\&.
+
+NOTE: The MacPorts user (usually called
+\fImacports\fR) needs to be able to read and write to this location\&. This usually means your home directory is not a suitable place for a port tree, unless you adjust permissions accordingly\&.
+.PP
+\fBExample\fR
+.RS 4
+\m[blue]\fBfile:///opt/dports\fR\m[]
+[nosync,default]
+.RE
+.PP
+\fBDefault\fR
+.RS 4
+none
+.RE
+.RE
+.PP
+\fIhttp://\fR, \fIhttps://\fR and \fIftp://\fR
+.RS 4
+Followed by a server name and a path on this server, this URI instructs MacPorts to download a tarball snapshot of a ports tree from the URI and extract it to a path of its choice\&. This possibility is provided as a fallback to users that can use neither rsync nor subversion to sync the MacPorts port tree\&.
+
+If the tarball contains a pre\-built PortIndex and PortIndex\&.quick file at PortIndex_${platform}_${os_major}_${os_arch}/, those will be used as default\&. If it does not, MacPorts will build a suitable port index for the local system automatically\&.
+.RE
+.SH "SOURCE FORMATS"
+.sp
+Port definition trees can be either directories (e\&.g\&. for the \fIfile://\fR and rsync methods) or tarballs (for HTTP, HTTPS, FTP and rsync)\&. For the directory format, no additional verification is performed\&. Because transfers using rsync are not encrypted or authenticated, the use of this setup over rsync is discouraged\&.
+.sp
+If the URI ends with \fI\&.tar\fR, MacPorts assumes the source is a tarball and attempts to download an additional \fI\&.tar\&.rmd160\fR signature file\&. It then uses the public keys configured in \fBpubkeys.conf\fR(5) to verify this signature to ensure the source has not been tampered with\&. You are strongly encouraged to use this setup, and it has been the default for MacPorts since it has been introduced\&.
+.SH "FLAGS"
+.sp
+Source specifications support a number of flags that modify the behavior of a source:
+.PP
+\fInosync\fR
+.RS 4
+Skip this source when
+\fBport sync\fR
+or
+\fBport selfupdate\fR
+are used\&. You can use this flag to avoid updating your local ports tree managed by a source control system such as Git or Subversion\&. You are responsible for generating a current port index using the
+\fBportindex\fR(1)
+command for sources marked with this flag\&.
+.RE
+.PP
+\fIdefault\fR
+.RS 4
+Mark this source as the default\&. The default source is used as a fallback to load additional files (such as PortGroups and mirror definitions) from the
+\fI_resources/port1\&.0\fR
+directory\&.
+.RE
+.SH "FILES"
+.sp
+The path of the \fIsources\&.conf\fR file is specified in the \fBsources_conf\fR option of \fBmacports.conf\fR(5)\&. It defaults to \fI${prefix}/etc/macports/sources\&.conf\fR\&. There is no user\-specific \fIsources\&.conf\fR file, but support for this can be emulated by setting \fIsources\&.conf\fR in the user\-specific \fBmacports.conf\fR(5) file\&.
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBport-selfupdate\fR(1), \fBport-sync\fR(1), \fBportindex\fR(1), \fBmacports.conf\fR(5)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2015 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/macports-changes/attachments/20150412/f2e295a6/attachment-0001.html>


More information about the macports-changes mailing list