[pacman-dev] [RFC] [PATCH v4] doc/PKGBUILD: misc changes

Sat Jun 11 13:55:04 EDT 2011

On 15:04 Sat 11 Jun     , Florian Pritz wrote:
> Signed-off-by: Florian Pritz <bluewind at xinu.at>
> Acked-by: matt mooney <mfm at muteddisk.com>
> ---
> On 10.06.2011 23:07, matt mooney wrote:
> >> > * "The name of the package or an array of names for split packages." -
> >> > seems to be looking for an "Either" at the start to pair with the "or"
> >> > already there,
> >> 
> >> added
> >> 
> >> > and then a comma can be put before the or, e.g. "Either
> >> > the name of the package, or an array of names for split packages."
> >> > Matt, correct me if I'm wrong. :)
> >> 
> >> added for now
> > 
> > There should not be a comma here; "Either..or" is a correlative conjunction. If
> > the "or" was being used as an appositive or coordinating conjuntion, then the
> > comma would be correct.
> 
> fixed
> 
> >> > * "where makepkg extracts to or copies to all source"- not sure why
> >> > this change is being made? Adding the two "to"s doesn't seem like
> >> > proper English to me.
> >> 
> >> I felt this was missing something, but you're right is sounds weird.
> >> Maybe "where makepkg extracts or copies all the source files to"?
> >> Since I'm not a native speaker I'd appreciate it if someone who is could
> >> comment on that.
> > 
> > I overlooked that one. If the words in question were nouns, "copies" would be a
> > non-restrictive appositive for "extract"; however, I don't know the name for
> > this when applied to verbs... renaming or something. Either way it is
> > non-restrictive element and should be offset with commas.
> > 
> > My suggestion for the sentence: "This contains the directory where makepkg
> > extracts, or copies, the source files."
> 
> fixed
> 
> >> > * s/of/on/ not sure this is needed?
> > 
> > Both are prepositions and used correctly, so it seems to be a question of
> > style.
> > 
> >> I haven't yet seen/heard "of your own" and assumed it was a mistake.
> >> Again, I'd appreciate a comment here.
> >> 
> >> > * (e.g., "makepkg-git", "mplayer-svn"). Elsewhere we already used have
> >> > multiple formats, we shouldn't add a third for consistency's sake:
> >> > (e.g. '2.7.1'), (e.g. `install=pkgname.install`) .
> >> 
> >> fixed
> > 
> > Yeah, I didn't look at the file as a whole for consistency, but that is
> > obviously important. In this case, maybe he should modify the other uses of
> > "e.g." while adhering to the quoting style within the file.
> 
> It's "e.g.," (or should I loose the comma?) everywhere now. `` is used for variable
> assignments and '' for everything else.

The majority of grammarians say that the comma is required, and I agree. If you
look at the meaning, I think you will too.

e.g. = for example and you would _not_ write (for example ...) because it is an
introductory phrase that reads with a distinct pause; therefore, the comma is
required although it is not visually pleasing.

The changes look good to me!

-mfm

> -- 
> Florian Pritz
> 
> 
>  doc/PKGBUILD.5.txt |   91 +++++++++++++++++++++++++--------------------------
>  1 files changed, 45 insertions(+), 46 deletions(-)
> 
> diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
> index c0fa594..753c4ea 100644
> --- a/doc/PKGBUILD.5.txt
> +++ b/doc/PKGBUILD.5.txt
> @@ -16,12 +16,12 @@ PKGBUILD
>  
>  Description
>  -----------
> -This manual page is meant to describe general rules about PKGBUILDs. Once a
> +This manual page describes general rules about PKGBUILDs. Once a
>  PKGBUILD is written, the actual package is built using makepkg and installed
>  with pacman.
>  
> -NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'.
> -Also located there are other example files such as a ChangeLog and an install
> +NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'
> +along with other example files such as a ChangeLog and an install
>  script. You can copy the provided PKGBUILD.proto file to a new package build
>  directory and make customizations to suit your needs.
>  
> @@ -30,33 +30,33 @@ Options and Directives
>  ----------------------
>  The following is a list of standard options and directives available for use
>  in a PKGBUILD. These are all understood and interpreted by makepkg, and most
> -will be directly transferred to the built package.
> +of them will be directly transferred to the built package.
>  
>  If you need to create any custom variables for use in your build process, it is
> -recommended to name your custom variables with an '_' (underscore) prefix.
> +recommended to prefix their name with an '_' (underscore).
>  This will prevent any possible name clashes with internal makepkg variables.
>  For example, to store the base kernel version in a variable, use something
>  similar to `$_basekernver`.
>  
>  *pkgname (array)*::
> -	The name of the package. This has be a unix-friendly name as it will be
> -	used in the package filename. Members of the array are not allowed to start
> -	with hyphens.
> +	Either the name of the package or an array of names for split packages.
> +	Because it will be used in the package filename, this has to be unix-friendly.
> +	Members of the array are not allowed to start with hyphens.
>  
>  *pkgver*::
> -	The version of the software as released from the author (e.g. '2.7.1').
> +	The version of the software as released from the author (e.g., '2.7.1').
>  	The variable is not allowed to contain colons or hyphens.
>  
>  *pkgrel*::
>  	This is the release number specific to the Arch Linux release. This
>  	allows package maintainers to make updates to the package's configure
> -	flags, for example. A pkgrel of '1' is typically used for each upstream
> -	software release and is incremented for intermediate PKGBUILD updates. The
> +	flags, for example. This is typically set to '1' for each new upstream
> +	software release and incremented for intermediate PKGBUILD updates. The
>  	variable is not allowed to contain hyphens.
>  
>  *pkgdesc*::
>  	This should be a brief description of the package and its functionality.
> -	Try to keep the description to one line of text.
> +	Try to keep the description to one line of text and not use the package's name.
>  
>  *epoch*::
>  	Used to force the package to be seen as newer than any previous versions
> @@ -69,50 +69,49 @@ similar to `$_basekernver`.
>  
>  *url*::
>  	This field contains a URL that is associated with the software being
> -	packaged. This is typically the project's website.
> +	packaged. Typically the project's website.
>  
>  *license (array)*::
>  	This field specifies the license(s) that apply to the package.
> -	Commonly-used licenses are found in '/usr/share/licenses/common'. If you
> +	Commonly used licenses can be found in '/usr/share/licenses/common'. If you
>  	see the package's license there, simply reference it in the license
> -	field (e.g. `license=('GPL')`). If the package provides a license not
> -	found in '/usr/share/licenses/common', then you should include the license
> +	field (e.g., `license=('GPL')`). If the package provides a license not
> +	available in '/usr/share/licenses/common', then you should include it
>  	in the package itself and set `license=('custom')` or
>  	`license=('custom:LicenseName')`. The license should be placed in
> -	'$pkgdir/usr/share/licenses/$pkgname' when building the package. If
> -	multiple licenses are applicable for a package, list all of them:
> +	'$pkgdir/usr/share/licenses/$pkgname/' when building the package. If
> +	multiple licenses are applicable, list all of them:
>  	`license=('GPL' 'FDL')`.
>  
>  *install*::
>  	Specifies a special install script that is to be included in the package.
>  	This file should reside in the same directory as the PKGBUILD, and will
>  	be copied into the package by makepkg. It does not need to be included
> -	in the source array (e.g. `install=pkgname.install`).
> +	in the source array (e.g., `install=pkgname.install`).
>  
>  *changelog*::
>  	Specifies a changelog file that is to be included in the package.
>  	This file should reside in the same directory as the PKGBUILD, and will
>  	be copied into the package by makepkg. It does not need to be included
> -	in the source array (e.g. `changelog=$pkgname.changelog`).
> +	in the source array (e.g., `changelog=$pkgname.changelog`).
>  
>  *source (array)*::
>  	An array of source files required to build the package. Source files
> -	must either reside in the same directory as the PKGBUILD file, or be a
> -	fully-qualified URL that makepkg will use to download the file. In order
> -	to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver
> -	variables if possible when specifying the download location. Any files
> -	that are compressed will automatically be extracted, unless found in
> -	the noextract array listed below.
> +	must either reside in the same directory as the PKGBUILD, or be a
> +	fully-qualified URL that makepkg can use to download the file.
> +	To make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver`
> +	variables if possible when specifying the download location. Compressed files
> +	will be extracted automatically unless found in
> +	the noextract array described below.
>  +
> -It is also possible to specify an optional filename, which is helpful
> +It is also possible to change the name of the downloaded file, which is helpful
>  with weird URLs and for handling multiple source files with the same
>  name. The syntax is: `source=('filename::url')`.
>  
>  *noextract (array)*::
>  	An array of filenames corresponding to those from the source array. Files
>  	listed here will not be extracted with the rest of the source files. This
> -	is useful for packages which use compressed data which is downloaded but
> -	not necessary to uncompress.
> +	is useful for packages that use compressed data directly.
>  
>  *md5sums (array)*::
>  	This array contains an MD5 hash for every source file specified in the
> @@ -133,18 +132,18 @@ name. The syntax is: `source=('filename::url')`.
>  	example, one could install all KDE packages by installing the 'kde' group.
>  
>  *arch (array)*::
> -	Defines on which architectures the given package is available (e.g.
> +	Defines on which architectures the given package is available (e.g.,
>  	`arch=('i686' 'x86_64')`). Packages that contain no architecture specific
> -	files may use arch=('any').
> +	files should use arch=('any').
>  
>  *backup (array)*::
> -	A space-delimited array of filenames, without preceding slashes, that
> +	An array of filenames, without preceding slashes, that
>  	should be backed up if the package is removed or upgraded. This is
>  	commonly used for packages placing configuration files in /etc. See
>  	Handling Config Files in linkman:pacman[8] for more information.
>  
>  *depends (array)*::
> -	An array of packages that this package depends on to run. Packages in
> +	An array of packages this package depends on to run. Entries in
>  	this list should be surrounded with single quotes and contain at least
>  	the package name. Entries can also include a version requirement of the
>  	form 'name<>version', where <> is one of five comparisons: >= (greater
> @@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`.
>  	than), or < (less than).
>  
>  *makedepends (array)*::
> -	An array of packages that this package depends on to build, but are not
> +	An array of packages this package depends on to build but are not
>  	needed at runtime. Packages in this list follow the same format as
>  	depends.
>  
>  *checkdepends (array)*::
> -	An array of packages that this package depends on to run its test suite,
> +	An array of packages this package depends on to run its test suite
>  	but are not needed at runtime. Packages in this list follow the same
>  	format as depends. These dependencies are only considered when the
>  	check() function is present and is to be run by makepkg.
> @@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`.
>  	same format as depends. Versioned conflicts are also supported.
>  
>  *provides (array)*::
> -	An array of ``virtual provisions'' that this package provides. This allows
> +	An array of ``virtual provisions'' this package provides. This allows
>  	a package to provide dependencies other than its own package name. For
>  	example, the dcron package can provide 'cron', which allows packages to
>  	depend on 'cron' rather than 'dcron OR fcron'.
> @@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`.
>  	provided.
>  
>  *replaces (array)*::
> -	An array of packages that this package should replace, and can be used
> +	An array of packages this package should replace. This can be used
>  	to handle renamed/combined packages. For example, if the 'j2re' package
>  	is renamed to 'jre', this directive allows future upgrades to continue
>  	as expected even though the package has moved. Sysupgrade is currently
> @@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`.
>  
>  build() Function
>  ----------------
> -In addition to the above directives, the optional build() bash function usually
> +In addition to the above directives, the optional build() function usually
>  comprises the remainder of the PKGBUILD. This is directly sourced and executed
>  by makepkg, so anything that bash or the system has available is available for
>  use here. The function is run in `bash -e` mode, meaning any command that exits
> @@ -256,19 +255,19 @@ with a non-zero status will cause the function to exit. Be sure any exotic
>  commands used are covered by `makedepends`.
>  
>  All of the above variables such as `pkgname` and `pkgver` are available for use
> -in the build function. In addition, makepkg defines three variables for your
> -use during the build and install process. These three variables are as follows:
> +in the build function. In addition, makepkg defines the following three
> +variables for use during the build and install process:
>  
>  *startdir*::
> -	This contains the absolute path to the directory where the PKGBUILD was
> +	This contains the absolute path to the directory where the PKGBUILD is
>  	located, which is usually the output of `$(pwd)` when makepkg is started.
>  
>  *srcdir*::
> -	This points to the directory where makepkg extracts or copies all source
> +	This contains the directory where makepkg extracts, or copies, all source
>  	files.
>  
>  *pkgdir*::
> -	This points to the directory where makepkg bundles the installed package
> +	This contains the directory where makepkg bundles the installed package
>  	(this directory will become the root directory of your built package).
>  
>  If you create any variables of your own in the build function, it is
> @@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name
>  `package_foo()`, where `foo` is the name of the split package.
>  
>  All options and directives for the split packages default to the global values
> -given within the PKGBUILD. However, some of these can be overridden within each
> -split package's packaging function. The following variables can be overridden:
> +given in the PKGBUILD. Nevertheless, the following ones can be overridden within
> +each split package's packaging function:
>  `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`,
>  `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`,
>  `install` and `changelog`.
> @@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to
>  manually update the pkgver in the PKGBUILD. This was formerly done using the
>  separate utility 'versionpkg'. In order to utilize this functionality, your
>  PKGBUILD must use correct variable names depending on the SCM being fetched
> -from.
> +from (e.g., 'makepkg-git', 'mplayer-svn').
>  
>  *CVS*::
>  	The generated pkgver will be the date the package is built.
> -- 
> 1.7.5.4
> 