ryandesign at macports.org
Fri Aug 15 13:53:06 PDT 2014
On Aug 15, 2014, at 3:06 PM, cal at macports.org wrote:
> cal at macports.org
> 2014-08-15 13:06:28 -0700 (Fri, 15 Aug 2014)
> Log Message
> base: document port cd, distfiles, dmg, mdmg, pkg, mpkg, echo, exit, quit, gohome, info; #44530
Great work on the continuing documentation saga! Thanks.
> --- trunk/base/doc/port-dmg.1.txt (rev 0)
> +++ trunk/base/doc/port-dmg.1.txt 2014-08-15 20:06:28 UTC (rev 123889)
> +These commands create OS X-native binary archives of a given port. Depending on
> +the command, either a .dmg disk image file, or a .pkg installer package is
I would remove the comma before the "or". Also note that the mpkg target creates a .mpkg file. The mdmg target still creates a .dmg file; there is no .mdmg file extension.
> +*port dmg* creates an OS X disk image. *port pkg* wraps the same files in an OS
> +X installer package. In most cases you probably want to package a port and all
> +its library and runtime dependencies in a single package suitable for binary
> +redistribution. You can use a metapackage to do this. Create one using *port
> +mdmg* or *port mpkg*.
I think it would be clearer to say that *port pkg* creates an installer package for installing the port's files, and that *port dmg* creates a disk image containing such an installer package. And then mention similarly mpkg, and mdmg containing the mpkg. We also need a mention that on OS X 10.6 and later the pkg and mpkg are in "flat" format, such that wrapping them in a dmg is no longer needed for online distribution (which is the reason why previously dmgs were used).
> --- trunk/base/doc/port-echo.1.txt (rev 0)
> +++ trunk/base/doc/port-echo.1.txt 2014-08-15 20:06:28 UTC (rev 123889)
> +*port echo* expands its argument list according to MacPorts' rules and prints
> +a list of ports that match the expression given as argument. It can be useful to
> +see what a pseudo-portname or a pseudo-portname selector (see man:port)
> +expands to.
> +Common use cases are:
> +port echo depends:zlib
> +port echo inactive
> +port echo obsolete
> +port echo requested
> +port echo leaves
> +port echo category:^mail$
Not sure if worth mentioning, but "port echo" will print anything you give it, even if it's not a valid port name:
$ port echo nonexistentport
Just don't want a user to be confused that "Hey, 'port echo nonexistentport' said nonexistentport existed so why can't I 'sudo port install nonexistentport'?"
> --- trunk/base/doc/port-gohome.1.txt (rev 0)
> +++ trunk/base/doc/port-gohome.1.txt 2014-08-15 20:06:28 UTC (rev 123889)
> @@ -0,0 +1,27 @@
> +// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
> +port-gohome - Open the homepage(s) of the given port(s)
Should be "homepage" (not "homepage(s)"); we don't support multiple homepages per port. (Just tried it; MacPorts combines all homepages with a space and tries to launch that single URL.)
> --- trunk/base/doc/port-info.1.txt (rev 0)
> +++ trunk/base/doc/port-info.1.txt 2014-08-15 20:06:28 UTC (rev 123889)
> +The rest of the options affect which fields will be given in the output:
> +--category, or --categories::
> + List the categories of a port.
You can use a comma before the "and" or "or" (the "Oxford comma") when there are three or more items in the list, but not with just two; it looks weird. But I'd actually just remove the "or" since the list of arguments doesn't need to read like a sentence.
> +--depends, --depends_fetch, --depends_extract, --depends_build, --depends_lib, and --depends_run::
> + List the specified dependencies of a port. *--depends* is a shorthand option
> + for all other *--depends_** options.
Here I'd remove the "and".
> +--description, and --long_description::
> + Print the short, and long description of a port, respectively.
I'd remove the "and" in the list of options and remove the first comma in the description.
> +--epoch, --version, --revision::
> + List the components of a MacPorts version tuple, epoch, version and
> + revision, respectively.
This is how I would do it everywhere.
> +--maintainer, or --maintainers::
> + List the email address(es) of a port's maintainer(s).
> +--platform, or --platforms::
> + List the platforms supported by a port. This field exists for historical
> + reasons only. In modern MacPorts, this is always 'darwin', i.e., OS X.
> +--variant, or --variants::
> + List the variants defined by a port by name.
More information about the macports-dev