[123889] trunk/base/doc

[Ryan Schmidt]

On Aug 15, 2014, at 3:06 PM, cal at macports.org wrote:
> 
> Revision
> 123889
> Author
> cal at macports.org
> Date
> 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)

> +DESCRIPTION
> +-----------
> +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
> +created.

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)

> +DESCRIPTION
> +-----------
> +*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[1])
> +expands to.
> +
> +EXAMPLES
> +--------
> +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
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(1)
> +==============
> +$Id$
> +
> +NAME
> +----
> +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.

As above.