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 <dan@archlinux.org>

4 files changed, 254 insertions, 2 deletions

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 <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:
+/////