From 6fb0c5abd7ac98694e9fb25749ed3b2e5b8c8848 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sat, 11 Apr 2009 12:38:20 -0500 Subject: doc: move files around for consistency Move some of our documentation files, even though they aren't manpages, to the doc/ directory. This allows the new 'html' make target to manage them. Signed-off-by: Dan McGee --- doc/.gitignore | 3 +- doc/Makefile.am | 6 +- doc/submitting-patches.txt | 98 +++++++++++++++++++++++++++++ doc/translation-help.txt | 149 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 254 insertions(+), 2 deletions(-) create mode 100644 doc/submitting-patches.txt create mode 100644 doc/translation-help.txt (limited to 'doc') diff --git a/doc/.gitignore b/doc/.gitignore index 45a7586d..c20afbdb 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,6 +6,7 @@ pacman.8 pacman.conf.5 repo-add.8 repo-remove.8 -*.xml +*.css *.html +*.xml man3 diff --git a/doc/Makefile.am b/doc/Makefile.am index cd0d83ba..a796a91e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -24,7 +24,9 @@ HTML_MANPAGES = \ libalpm.3.html HTML_OTHER = \ - index.html + index.html \ + submitting-patches.html \ + translation-help.html HTML_DOCS = \ $(HTML_MANPAGES) \ @@ -42,6 +44,8 @@ EXTRA_DIST = \ libalpm.3.txt \ footer.txt \ index.txt \ + submitting-patches.txt \ + translation-help.txt \ Doxyfile \ $(ASCIIDOC_MANS) \ $(DOXYGEN_MANS) 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 + +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 <> 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 -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 -o .po -i + +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 .gmo /usr/share/locale//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: +///// -- cgit v1.2.3-70-g09d2