diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 2 | ||||
| -rw-r--r-- | doc/Makefile.am | 51 | ||||
| -rw-r--r-- | doc/PKGBUILD.5.txt | 18 | ||||
| -rw-r--r-- | doc/index.txt | 194 | ||||
| -rw-r--r-- | doc/makepkg.8.txt | 2 | ||||
| -rw-r--r-- | doc/pacman.8.txt | 6 | ||||
| -rw-r--r-- | doc/repo-add.8.txt | 6 | ||||
| -rw-r--r-- | doc/submitting-patches.txt | 98 | ||||
| -rw-r--r-- | doc/translation-help.txt | 149 |
9 files changed, 501 insertions, 25 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index a3941ecd..c20afbdb 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,5 +6,7 @@ pacman.8 pacman.conf.5 repo-add.8 repo-remove.8 +*.css +*.html *.xml man3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 7992e547..a796a91e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,6 +14,24 @@ ASCIIDOC_MANS = \ DOXYGEN_MANS = $(wildcard man3/*.3) +HTML_MANPAGES = \ + pacman.8.html \ + makepkg.8.html \ + repo-add.8.html \ + PKGBUILD.5.html \ + makepkg.conf.5.html \ + pacman.conf.5.html \ + libalpm.3.html + +HTML_OTHER = \ + index.html \ + submitting-patches.html \ + translation-help.html + +HTML_DOCS = \ + $(HTML_MANPAGES) \ + $(HTML_OTHER) + EXTRA_DIST = \ asciidoc.conf \ pacman.8.txt \ @@ -25,12 +43,15 @@ EXTRA_DIST = \ pacman.conf.5.txt \ libalpm.3.txt \ footer.txt \ + index.txt \ + submitting-patches.txt \ + translation-help.txt \ Doxyfile \ $(ASCIIDOC_MANS) \ $(DOXYGEN_MANS) # Files that should be removed, but which Automake does not know. -MOSTLYCLEANFILES = *.xml $(ASCIIDOC_MANS) +MOSTLYCLEANFILES = *.xml $(ASCIIDOC_MANS) $(HTML_DOCS) # Ensure manpages are fresh when building a dist tarball dist-hook: @@ -56,6 +77,8 @@ doxygen.in: $(DOXYGEN) $(srcdir)/Doxyfile endif +html: $(HTML_DOCS) + ASCIIDOC_OPTS = \ -f asciidoc.conf \ -a pacman_version="$(REAL_PACKAGE_VERSION)" \ @@ -72,13 +95,25 @@ A2X_OPTS = \ $(ASCIIDOC_MANS): asciidoc.conf footer.txt a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt -pacman.8: pacman.8.txt -makepkg.8: makepkg.8.txt -repo-add.8: repo-add.8.txt -PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt -makepkg.conf.5: makepkg.conf.5.txt -pacman.conf.5: pacman.conf.5.txt -libalpm.3: libalpm.3.txt +%.html: %.txt + asciidoc $(ASCIIDOC_OPTS) -a linkcss $*.txt + dos2unix $@ + +# Customizations for certain HTML docs +$(HTML_MANPAGES): asciidoc.conf footer.txt +$(HTML_OTHER): asciidoc.conf +%.8.html: ASCIIDOC_OPTS += -d manpage +%.5.html: ASCIIDOC_OPTS += -d manpage +%.3.html: ASCIIDOC_OPTS += -d manpage + +# Dependency rules +pacman.8 pacman.8.html: pacman.8.txt +makepkg.8 makepkg.8.html: makepkg.8.txt +repo-add.8 repo-add.8.html: repo-add.8.txt +PKGBUILD.5 PKGBUILD.5.html: PKGBUILD.5.txt PKGBUILD-example.txt +makepkg.conf.5 makepkg.conf.5.html: makepkg.conf.5.txt +pacman.conf.5 pacman.conf.5.html: pacman.conf.5.txt +libalpm.3 libalpm.3.html: libalpm.3.txt # this one is just a symlink repo-remove.8: repo-add.8 rm -f repo-remove.8 diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index f8ed7f26..e1ea632b 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -65,19 +65,19 @@ similar to `$_basekernver`. This field specifies the license(s) that apply to the package. Commonly-used licenses are 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 + field (e.g. `license=('GPL')`). If the package provides a license not found in '/usr/share/licenses/common', then you should include the license - in the package itself and set `$$license=('custom')$$` or - `$$license=('custom:LicenseName')$$`. The license should be placed in + 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: - `$$license=('GPL' 'FDL')$$`. + `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`). *source (array)*:: An array of source files required to build the package. Source files @@ -90,7 +90,7 @@ similar to `$_basekernver`. + It is also possible to specify an optional filename, which is helpful with weird URLs and for handling multiple source files with the same -name. The syntax is: `$$source=('filename::url')$$` +name. The syntax is: `source=('filename::url')`. *noextract (array)*:: An array of filenames corresponding to those from the source array. Files @@ -118,7 +118,7 @@ name. The syntax is: `$$source=('filename::url')$$` *arch (array)*:: Defines on which architectures the given package is available (e.g. - `$$arch=('i686' 'x86_64')$$`). + `arch=('i686' 'x86_64')`). *backup (array)*:: A space-delimited array of filenames, without preceding slashes, that @@ -238,8 +238,8 @@ use during the build and install process. These three variables are as follows: *startdir*:: This contains the absolute path to the directory where the PKGBUILD was located, which is usually the output of `$(pwd)` when makepkg is started. - $$startdir$$ was most often used in combination with `/src` or `/pkg` - postfixes, but use of the `srcdir` and `pkgdir` variables is preferred. + `$startdir` was most often used in combination with `/src` or `/pkg` + postfixes, but use of the `$srcdir` and `$pkgdir` variables is preferred. *srcdir*:: This points to the directory where makepkg extracts or copies all source diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 00000000..bfca3acc --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,194 @@ +Pacman Home Page +================ + +A simple library-based package manager. + +Introduction +------------ +pacman is a utility which manages software packages in Linux. It uses simple +compressed files as a package format, and maintains a text-based package +database (more of a hierarchy), just in case some hand tweaking is necessary. + +pacman does not strive to "do everything." It will add, remove and upgrade +packages in the system, and it will allow you to query the package database for +installed packages, files and owners. It also attempts to handle dependencies +automatically and can download packages from a remote server. + +History +~~~~~~~ +Version 2.0 of pacman introduced the ability to sync packages (the `--sync` +option) with a master server through the use of package databases. Prior to +this, packages would have to be installed manually using the `--add` and +`--upgrade` operations. + +Version 3.0 was the switch to a two-part pacman- a backend named libalpm +(library for Arch Linux Package Management), and the familiar pacman frontend. +Speed in many cases was improved, along with dependency and conflict resolution +being able to handle a much wider variety of cases. The switch to a +library-based program should also make it easier in the future to develop +alternative front ends. + +Documentation +------------- + +Manpages +~~~~~~~~ +There are several manpages available for the programs, utilities, and +configuration files dealing with pacman. + +* linkman:PKGBUILD[5] +* linkman:libalpm[3] +* linkman:makepkg[8] +* linkman:makepkg.conf[5] +* linkman:pacman[8] +* linkman:pacman.conf[5] +* linkman:repo-add[8] + +Changelog +~~~~~~~~~ +For a good idea of what is going on in pacman development, take a look at the +link:http://projects.archlinux.org/?p=pacman.git[Gitweb] summary +page for the project. + +See the most recent +link:http://projects.archlinux.org/?p=pacman.git;a=blob_plain;f=NEWS;hb=HEAD[NEWS] +file for a not-as-frequently-updated list of changes. However, this should +contain the biggest changes in a format more concise than the commit log. + + +Releases +-------- + +`------------`------- +Date Version +--------------------- +2009-01-05 v3.2.2 +2008-08-26 v3.2.1 +2008-07-30 v3.2.0 +2008-04-01 v3.1.4 +2008-03-06 v3.1.3 +2008-02-20 v3.1.2 +2008-01-20 v3.1.1 +2008-01-09 v3.1.0 +2007-09-16 v3.0.6 +2007-06-17 v3.0.5 +2007-05-08 v3.0.4 +2007-04-28 v3.0.3 +2007-04-23 v3.0.2 +2007-04-04 v3.0.1 +2007-03-25 v3.0.0 +2006-02-02 v2.9.8 +2005-09-16 v2.9.7 +2005-06-10 v2.9.6 +2005-01-11 v2.9.5 +2004-12-19 v2.9.4 +2004-12-18 v2.9.3 +2004-09-25 v2.9.2 +2004-09-24 v2.9.1 +2004-09-18 v2.9 +--------------------- + +Source code for all releases is available at +link:ftp://ftp.archlinux.org/other/pacman/[]. To install, download the newest +available source tarball, unpack it in a directory, and run the three magic +commands: + + $ ./configure + $ make + # make install + +You may wish to read the options presented by `./configure --help` in order to +set appropriate paths and build options that are correct for your system. + +Development +----------- + +Mailing List +~~~~~~~~~~~~ +There is a mailing list devoted to pacman development, hosted by Arch Linux. +link:http://www.archlinux.org/mailman/listinfo/pacman-dev/[Subscribe] or +link:http://www.archlinux.org/pipermail/pacman-dev/[view the archives]. + +Source Code +~~~~~~~~~~~ +Development of pacman is currently done in GIT. The central repository is +hosted by Arch Linux, although some of the developers have their own trees (ask +on the above mailing lists if you are interested in finding the locations of +these trees). + +The current development tree can be fetched with the following command: + + git clone git://projects.archlinux.org/pacman.git pacman + +which will fetch the full development history into a directory named pacman. +You can browse the source as well using +link:http://projects.archlinux.org/?p=pacman.git[Gitweb]. + +If you are interested in hacking on pacman, it is highly recommended you join +the mailing list mentioned above, as well as take a quick glance at our +link:HACKING.html[HACKING] document. +link:submitting-patches.html[submitting-patches] is also a recommended read. + +Not as familiar with code as you'd like to be, but still want to help out? If +you speak a foreign language, you can help by either creating or updating a +translation file for your native language. Instructions can be found in +link:translation-help.html[translation-help]. + +Other Utilities +~~~~~~~~~~~~~~~ +Although the package manager itself is quite simple, many scripts have been +developed that help automate building and installing packages. These are used +extensively in link:http://archlinux.org[Arch Linux]. Most of these utilities +are available in the Arch Linux projects +link:http://projects.archlinux.org/[Gitweb browser]. + +Utilities available: + +* link:http://projects.archlinux.org/?p=abs.git[abs] - ABS (Arch Build System), scripts to download & use the Arch Linux PKGBUILD tree +* link:http://projects.archlinux.org/?p=devtools.git[devtools] - tools to assist in packaging and dependency checking +* link:http://projects.archlinux.org/?p=namcap.git[namcap] - a package analysis utility written in python +* link:http://projects.archlinux.org/?p=pacbuild.git[pacbuild] - a package building system utilizing a daemon +* link:http://projects.archlinux.org/?p=srcpac.git[srcpac] - a bash build-from-source pacman wrapper + +Bugs +---- +If you find bugs (which is quite likely), please email them to the pacman-dev +mailing last at mailto:pacman-dev@archlinux.org[] with specific information +such as your commandline, the nature of the bug, and even the package database +if it helps. + +You can also post a bug to the Archlinux bug tracker +link:http://bugs.archlinux.org/index.php?project=3[Flyspray]. Be sure to file +bugs under the Pacman project. + +Pacman/libalpm in the Wild +-------------------------- +Although Arch Linux is the primary user of pacman and libalpm, other +distributions and projects also use pacman as a package management tool. In +addition, there have been several projects started to provide a frontend GUI to +pacman and/or libalpm. + +Arch derivatives: + +* link:http://archie.dotsrc.org/[Archie] - Arch Live on steroids +* link:http://www.faunos.com/[FaunOS] - A portable, fully integrated operating system based on Arch Linux +* link:http://larch.berlios.de/[larch] - A live CD/DVD/USB-stick construction kit for Arch Linux + +Other distributions: + +* link:http://www.delilinux.org/[DeLi Linux] - "Desktop Light" Linux, a Linux distribution for old computers +* link:http://www.frugalware.org/[Frugalware Linux] - A general purpose Linux distribution for intermediate users (pacman is forked and maintained separately) + +Pacman/libalpm frontends: + +* link:http://shaman.iskrembilen.com/[Shaman] - A GUI frontend using Qt and libalpm + +Copyright +--------- +pacman is Copyright (C) 2006-2009 Dan McGee <dan@archlinux.org> and +Copyright (C) 2002-2006 Judd Vinet <jvinet@zeroflux.org> and is +licensed through the GNU General Public License, version 2 or later. + +///// +vim: set ts=2 sw=2 syntax=asciidoc et: +///// diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt index 4bb37808..fb2e8054 100644 --- a/doc/makepkg.8.txt +++ b/doc/makepkg.8.txt @@ -43,7 +43,7 @@ Options *-A, \--ignorearch*:: Ignore a missing or incomplete arch field in the build script. This is for rebuilding packages from source when the PKGBUILD may be slightly - outdated and not updated with an `$$arch=('yourarch')$$` field. + outdated and not updated with an `arch=('yourarch')` field. *-c, \--clean*:: Clean up leftover work files and directories after a successful build. diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt index c5748724..95880a25 100644 --- a/doc/pacman.8.txt +++ b/doc/pacman.8.txt @@ -124,9 +124,13 @@ Options command line or in linkman:pacman.conf[5], their default location will be inside this root path. -*-v, --verbose*:: +*-v, \--verbose*:: Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc. +*\--debug*:: + Display debug messages. When reporting bugs, this option is recommended + to be used. + *\--cachedir* <'dir'>:: Specify an alternative package cache location (a typical default is ``/var/cache/pacman/pkg''). Multiple cache directories can be specified, diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt index b9956e9b..81bf8377 100644 --- a/doc/repo-add.8.txt +++ b/doc/repo-add.8.txt @@ -6,14 +6,8 @@ repo-add(8) Name ---- -//// -* If we use this below line, the manpage name comes out all weird. We also -* can't use two separate lines, which is quite annoying. * -repo-add, repo-remove - package database maintenance utilities -//// repo-add - package database maintenance utility - Synopsis -------- repo-add [-q] <path-to-db> <package1> [<package2> ...] diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt new file mode 100644 index 00000000..e6853c5f --- /dev/null +++ b/doc/submitting-patches.txt @@ -0,0 +1,98 @@ +Pacman - Submitting Patches +=========================== + +This document is here mainly to make the job of those who review patches +easier and is more of a guideline and not a strict set of rules. However, +please try to follow as much as you can. + +NOTE: Some of this is paraphrased from the kernel documentation's +"SubmittingPatches" file. + +Getting the most recent source +------------------------------ + +Patches need to be submitted in GIT format and are best if they are against the +latest version of the code. There are several helpful tutorials for getting +started with GIT if you have not worked with it before. + +* http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html +* http://wiki.archlinux.org/index.php/Super_Quick_Git_Guide + +The pacman code can be fetched using the following command: + + git clone git://projects.archlinux.org/pacman.git + + +Creating your patch +------------------- + +-- +* use `git commit -s` for creating a commit of your changes. + +The -s allows you to credit yourself by adding a "Signed Off By" line to +indicate who has "signed" the patch - who has approved it. + + Signed-off-by: Aaron Griffin <aaron@archlinux.org> + +Please use your real name and email address. Feel free to "scramble" the +address if you're afraid of spam. + +* Describe your patch. + +It helps if you describe the overview and goals of the patch in the git commit +log. This allows others to see what you intended so as to compare it to what +was actually done, and allows better feedback. + +* Use `git format-patch` to create patches. + +Your commit message will be shown above the patch by default when you will use +`git-format-patch`, including the signoff line. +-- + +Submitting your patch +--------------------- + +-- +* Send the patch to the pacman-dev mailing list + +The mailing list is the primary queue for review and acceptance. Here you +will get feedback, and let me know the details of your patch. + +* No MIME, no links, no compression, no attachments. Just plain text. + +Patches should be contained in the actual body of the email. There are many +reasons for this. First, it makes them easier to read with any mail reader, +it allows easier review "at a glance", and most importantly, it allows people +to comment on exact lines of the patch in reply emails. + +`git send-email` allows you to send git formatted patches in plain text easily +and is the preferred method for submission to the mailing list. + +-- + +After you submit +---------------- + +-- +* Don't get discouraged + +Any feedback you get, positive or negative, has nothing to do with you. If a +patch is rejected, try taking the suggestions into account and re-submitting. +We welcome most submissions here, and some may take a bit longer to get +looked over than others. If you think your patch got lost in the shuffle, +send another email to the list in reply to the original asking if anyone has +looked at it yet. + +* Respond to feedback + +When you do get feedback, it usually merits a response, whether this be a +resubmit of the patch with corrections or a follow-up email asking for +clarifications. When neither of these occurs, don't expect your patch to see +further review. The all-volunteer staff don't have time to fix up patches that +aren't their own. + +-- + +///// +vim: set ts=2 sw=2 syntax=asciidoc et: +///// diff --git a/doc/translation-help.txt b/doc/translation-help.txt new file mode 100644 index 00000000..dd3b4129 --- /dev/null +++ b/doc/translation-help.txt @@ -0,0 +1,149 @@ +Pacman - Translating +==================== + +This document is here to guide you in helping translate pacman messages, +libalpm messages, and the manpages for the entire pacman package. + +A quick note- the gettext website is a very useful guide to read before +embarking on translation work, as it describes many of the commands in more +detail than I will here: +http://www.gnu.org/software/gettext/manual/html_node/gettext.html[] + +In addition, this site presents a small tutorial that I found useful: +http://oriya.sarovar.org/docs/gettext/[] + + +Translating Messages +-------------------- + +Overview +~~~~~~~~ + +There are two separate message catalogs in pacman- one for the backend +(libalpm) and one for the frontend (pacman and scripts). These correspond to +the `lib/libalpm/po` and `po` directories in the pacman source, respectively. + +Translation message files are a specially formatted text file containing the +original message and the corresponding translation. These po files can then +either be hand edited, or modified with a tool such as poedit, gtranslator or +kbabel. Using a translation tool tends to make the job easier. + +See the <<Notes,Notes>> section for additional hints on translating. + +Pre-release Updates +~~~~~~~~~~~~~~~~~~~ + +A week or two before each release, the codebase will go into a string freeze +and an email will be sent by the 'translation lieutenant' to the +mailto:pacman-dev@archlinux.org[pacman-dev] mailing list asking for +translations. This email will have a prefix of *[translation]* for anyone +looking to set up an email filter. + +At this time, the `.po` language files will be made available at a URL +specified in the email. Each language will have two files available (backend +and frontend). Translators interested in helping are encouraged to send a +follow-up message to the mailing list stating exactly what they intend to +translate so efforts are not duplicated on the same language. + +Once a translator has completed the translation (*OR* realizes they do not have +time to finish), please email the `.po` files back to the list with a subject +such as '[translation] Updated German translation'. At this point, the +'translation lieutenant' will gather the translations together for inclusion in +the upcoming release. + +NOTE: Please email your translations back to the list as soon as possible- this +will give other speakers of your language time to review your translations and +update them as necessary. + +For those familiar with GIT, you may wish to follow the procedure outlined +below as another alternative. + +Incremental Updates +~~~~~~~~~~~~~~~~~~~ + +If you have more advanced needs you will have to get a copy of the pacman +repository. + + git clone git://projects.archlinux.org/pacman.git pacman + +Next, you will need to run `./autogen.sh` and `./configure` in the base +directory to generate the correct Makefiles. At this point, all necessary +make targets will be generated and we can begin updating the translation +files. + +We need to first update the main message catalog file. Navigate into either the +`lib/libalpm/po` or `po` directory depending on which translation you wish to +work on first, and execute the following command. If you are working in the +`po/` tree, replace 'libalpm.pot' with 'pacman.pot': + + make libalpm.pot-update + +Next, update your specific language's translation file: + + make <po file>-update + +At this point, you can do the translation. To submit your changes, either email +the new `.po` file to the mailing-list with *[translation]* in the subject, or +submit a GIT-formatted patch (please do not include any `.pot` file changes). + +As a shortcut, all translation files (including `.pot` files) can be updated +with the following command: + + make update-po + +Adding a New Language +~~~~~~~~~~~~~~~~~~~~~ + +Making a new language is not too hard, but be sure to follow all the steps. +You will have to do the following steps in both the `lib/libalpm/po/` and `po/` +directories, substituting where appropriate. First, edit the `LINGUAS` file and +add your new language code at the bottom. Next, run the following command, +substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which +directory you are currently working in: + + msginit -l <lang code> -o <lang code>.po -i <potfile> + +You can then also add your language code to the end of the `LINGUAS` file +located in each po directory. + +Look at the current message files for more guidance if necessary. Once you +create the new language file, you may need to slightly modify the headers; +try to make them look similar to the other .po file headers. In addition, for +all new translations we would strongly recommend using UTF-8 encoding. + +Notes[[Notes]] +~~~~~~~~~~~~~~ + +msgid and msgstr 'variables' can be on as many lines as necessary. Line breaks +are ignored- if you need a literal line break, use an `\n` in your string. The +following two translations are equivalent: + + msgstr "This is a test translation" + + msgstr "" + "This is a test translation" + +If you want to test the translation (for example, the frontend one): + + rm *.gmo stamp-po + make + cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo + + +Translating Manpages +-------------------- + +There are currently no efforts underway to include translated manpages in the +pacman codebase. However, this is not to say translations are unwelcome. If +someone has experience with i18n manpages and how to best include them with our +source, please contact the pacman-dev mailing list at +mailto:pacman-dev@archlinux.org[]. + +Some community efforts have been made to translate manpages, and these can be +found in the link:http://aur.archlinux.org[AUR] (Arch User Repository). Please +check there first before undergoing a translation effort to ensure you are not +duplicating efforts. + +///// +vim: set ts=2 sw=2 syntax=asciidoc et: +///// |