Asciidoc a few more of our informative files

Signed-off-by: Dan McGee <dan@archlinux.org>

3 files changed, 97 insertions, 67 deletions

diff --git a/HACKING b/HACKING
index 5ee6d064..230cbb09 100644
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,10 @@
-Contributing to pacman
-======================
+Pacman - Contributing
+=====================
 
-In addition to this file, please read `submitting-patches` and
-`translation-help` in the same directory for additional info on contributing.
+This file is meant to give you a brief overview of coding style and other
+concerns when hacking on pacman. If you are interested in contributing, please
+read link:submitting-patches.html[submitting-patches] and
+link:translation-help.html[translation-help] as well.
 
 Coding style
 ------------
diff --git a/submitting-patches b/submitting-patches
index 725b1ea1..02cde30f 100644
--- a/submitting-patches
+++ b/submitting-patches
@@ -1,5 +1,5 @@
-HOWTO: Submit a patch
----------------------
+Pacman - Submitting Patches
+===========================
 
 This document is here mainly to make my job easier, and is more of a guideline,
 and not a strict set of rules.  Please try to follow as much as you can.
@@ -7,74 +7,88 @@ and not a strict set of rules.  Please try to follow as much as you can.
 NOTE: Much of this is paraphrased from the kernel documentation's
 "SubmittingPatches" file.
 
-Creating your patch:
+Creating your patch
+-------------------
 
 Most of this was more relevant before we switched to GIT for version control.
 However, much of it is still applicable and should be followed. Some notes
 have been added to make this a bit more up-to-date with the GIT workflow.
 
+--
 * Use "diff -up" or "diff -uprN" to create patches.
 
-  These options make the diff easier to read for those of us who try to review
-  submitted patches. If you are working on your own git branch, then GIT
-  formatted patches are perfectly acceptable.
+These options make the diff easier to read for those of us who try to review
+submitted patches. If you are working on your own git branch, then GIT
+formatted patches are perfectly acceptable.
 
 * Please try to make patches "p1 applicable"
 
-  This means that if you are patching file "lib/libalpm/alpm.h", I should be
-  able to apply your patch while passing the -p1 argument to 'patch'.  The diff
-  header should look like so:
+This means that if you are patching file "lib/libalpm/alpm.h", I should be
+able to apply your patch while passing the -p1 argument to 'patch'.  The diff
+header should look like so:
 
   --- ORIGINAL_DIR/lib/libalpm/alpm.h
   +++ NEW_DIR/lib/libalpm/alpm.h
 
-  With '-p1' the ORIGINAL_DIR and NEW_DIR arguments are stripped. GIT produces
-  p1 formatted patches by default.
+With '-p1' the ORIGINAL_DIR and NEW_DIR arguments are stripped. GIT produces
+p1 formatted patches by default.
+--
 
-Submitting your patch:
+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.  It also helps
-  if you add "[patch]" to the beginning of your Subject line.
+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.  It also helps
+if you add "[patch]" to the beginning of your Subject line.
 
 * 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.  Firstly, 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.
+Patches should be contained in the actual body of the email.  There are many
+reasons for this.  Firstly, 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.
 
-  It is important to know that the diff format ignores plain text before (and
-  after) the main diff itself.  If you directly insert your patch into an email,
-  you can safely add lines above it describing your patch.
+It is important to know that the diff format ignores plain text before (and
+after) the main diff itself.  If you directly insert your patch into an email,
+you can safely add lines above it describing your patch.
 
 * Describe your patch.
 
-  Before the actual diff begins, it helps if you describe the changes in the
-  patch.  This allows others to see what you intended so as to compare it to
-  what was actually done, and allows better feedback. If you use
-  'git-format-patch' to create your patch, then your commit message will
-  be shown above the patch by default.
+Before the actual diff begins, it helps if you describe the changes in the
+patch.  This allows others to see what you intended so as to compare it to
+what was actually done, and allows better feedback. If you use
+`git-format-patch` to create your patch, then your commit message will
+be shown above the patch by default.
 
 * Credit yourself
 
-  Just like with the kernel, it helps if you add a "Signed Off By" line to
-  indicate who has "signed" the patch - who has approved it.
+Just like with the kernel, it helps if you add 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. 'git commit -s' makes this easy.
 
-After you submit:
+Please use your real name and email address.  Feel free to "scramble" the
+address if you're afraid of spam. `git commit -s` makes this easy.
+--
+
+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.
+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.
+--
+
+/////
+vim: set ts=2 sw=2 syntax=asciidoc et:
+/////
diff --git a/translation-help b/translation-help
index dabf282c..8887b37a 100644
--- a/translation-help
+++ b/translation-help
@@ -1,5 +1,5 @@
-HOWTO: Help with translations
------------------------------
+Pacman - Translating
+====================
 
 This document is here to guide you in helping translate pacman messages,
 libalpm messages, and the manpages for the entire pacman package.
@@ -7,10 +7,10 @@ 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>
+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/>
+http://oriya.sarovar.org/docs/gettext/[]
 
 Translating Messages
 --------------------
@@ -22,10 +22,16 @@ Each language has a .po file associated with it; the .pot file is the template
 file for creating new .po files and updating the messages in them when the code
 changes.
 
-First things first. You will need to run ./autogen.sh and ./configure in the
-base directory to generate the correct Makefiles. To update all the translation
-files, run this command:
-	make update-po
+First things first. If you haven't already, you will need 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. To update all the translation
+files, run this command in one of the two message file directories:
+
+    make update-po
 
 At this point, the .pot file is regenerated from the source code with an
 updated string list, and the existing po files are merged if necessary to add
@@ -33,20 +39,22 @@ new messages or remove old ones. These po files can then either be hand edited,
 or modified with a tool such as poedit, gtranslator or kbabel.
 
 These steps make it easier to just update your language and not every po file.
-If you are working in the root tree, replace libalpm.pot with pacman.pot:
-	make libalpm.pot-update 
-	make <po file>-update
+If you are working in the `po/` tree, replace 'libalpm.pot' with 'pacman.pot':
+
+    make libalpm.pot-update
+    make <po file>-update
 
 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
+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' depending on which directory you are
-currently working in:
+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.
+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;
@@ -54,22 +62,25 @@ 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.
 
 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
+
+    rm *.gmo stamp-po
+    make
+    cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo
 
 Finally, submitting your translations in patch form is not essential for new
 languages, but highly recommended for future updates to the translations.
 
-Some other 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
+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"
 
-msgstr ""
-"This is a test translation"
+    msgstr ""
+    "This is a test translation"
 
 
 Translating Manpages
@@ -77,3 +88,6 @@ Translating Manpages
 
 (To Be Announced)
 
+/////
+vim: set ts=2 sw=2 syntax=asciidoc et:
+/////