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

[matt mooney]

On 19:39 Fri 10 Jun     , Florian Pritz wrote:
> Signed-off-by: Florian Pritz <bluewind at xinu.at>
> ---
> On 10.06.2011 19:12, Dan McGee wrote:
> > On Fri, Jun 10, 2011 at 4:31 AM, matt mooney <mfm at muteddisk.com> wrote:
> >> On 09:00 Fri 10 Jun     , Florian Pritz wrote:
> >>> On 10.06.2011 01:58, matt mooney wrote:
> >>> > Apart from those minor issues, great work! I am a big fan of grammar cleanups ;)
> >>>
> >>> Thanks for taking a look at it. I don't want to clutter this ML too much
> >>> so the fixed patch is available at [1]. Once it's been read by a few
> >>> more people I'll send the final one for merging.
> >>
> >> Next time you should just resend it inline as [PATCH v2] to allow people to
> >> comment on the corrected version.
> >>
> >> Acked-by: matt mooney <mfm at muteddisk.com>
> > 
> > Definitely just send it again next time; don't ever worry about
> > cluttering the ML. Whether a message includes a patch or not, it is
> > still a message.
> > 
> > Comments (made harder by not inline):
> 
> Ok I didn't think about that sorry.
> 
> > * "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.

I do like the change though.

> 
> > * "(re)set" -> "set", I don't think the former adds any clarity.
> 
> removed
> 
> > * source: we seem to have a precedent elsewhere in the docs to put
> > variables in `` (backticks). 
> 
> fixed
> 
> > Since this got a total rewrite anyway,
> > feel free to rewrap the whole thing for consistency at the normal
> > textwidth of 80.

I definitely agree here!

> 2 lines are exactly 80 chars, the rest is below. That script might come
> in handy: http://git.server-speed.net/bin/plain/long-lines.pl
> 
> > * "It is also possible to overwrite the filename". This seems a bit
> > misleading- "It is possible to change the name of the downloaded
> > file..." or something?
> 
> done
> 
> > * "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."

> > Also, for these three, we should be consistent
> > with either "This contains" or "This points to" (I think the former).
> 
> 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.

-matt

> 
>  doc/PKGBUILD.5.txt |   83 +++++++++++++++++++++++++--------------------------
>  1 files changed, 41 insertions(+), 42 deletions(-)
> 
> diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
> index c0fa594..63c8640 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,18 +30,18 @@ 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').
> @@ -50,13 +50,13 @@ similar to `$_basekernver`.
>  *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,18 +69,18 @@ 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
> +	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*::
> @@ -97,22 +97,21 @@ similar to `$_basekernver`.
>  
>  *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
> @@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`.
>  *arch (array)*::
>  	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,22 +255,22 @@ 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 to or copies to 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
> +If you create any variables on your own in the build function, it is
>  recommended to use the bash `local` keyword to scope the variable to inside
>  the build function.
>  
> @@ -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
>