On 15:04 Sat 11 Jun , Florian Pritz wrote:
> Signed-off-by: Florian Pritz <[email protected]>
> Acked-by: matt mooney <[email protected]>
> ---
> 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
>
