On 19:39 Fri 10 Jun , Florian Pritz wrote: > Signed-off-by: Florian Pritz <[email protected]> > --- > On 10.06.2011 19:12, Dan McGee wrote: > > On Fri, Jun 10, 2011 at 4:31 AM, matt mooney <[email protected]> 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 <[email protected]> > > > > 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 >
