ubuntu-packaging-guide-team team mailing list archive

[Dmitry Shachnev <mitya57@xxxxxxxxx>]

Dmitry Shachnev has proposed merging lp:~mitya57/ubuntu-packaging-guide/readme-update into lp:ubuntu-packaging-guide.

Requested reviews:
  Ubuntu Packaging Guide Team (ubuntu-packaging-guide-team)

For more details, see:
https://code.launchpad.net/~mitya57/ubuntu-packaging-guide/readme-update/+merge/147508

This makes the README a proper reStructuredText file and adds some information for translators.

I've also made it available online at http://people.ubuntu.com/~mitya57/ubuntu-packaging-guide-readme.html (so that we could point translators to http://people.ubuntu.com/~mitya57/ubuntu-packaging-guide-readme.html#translating). I'll maybe add some CSS later.

BTW, I've also proposed a reStructuredText syntax enhancement that will solve our problem with translating links (if accepted): http://article.gmane.org/gmane.text.docutils.devel/6347.
-- 
https://code.launchpad.net/~mitya57/ubuntu-packaging-guide/readme-update/+merge/147508
Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~mitya57/ubuntu-packaging-guide/readme-update into lp:ubuntu-packaging-guide.

=== modified file 'README'
--- README	2012-08-28 23:27:17 +0000
+++ README	2013-02-09 11:08:21 +0000
@@ -10,41 +10,61 @@
 - A set of knowledge-base articles that dig deeper into specific bits of our
   tools and workflows.
 
-The actual articles can be found under the 'ubuntu-packaging-guide' directory
-in rst files. The html template and css can be found under 'themes/ubuntu'. If
-adding a new article, make sure to add it to the 'ubuntu-packaging-guide/index.rst'
-file so that it appears in the table of contents.
+The actual articles can be found under the ``ubuntu-packaging-guide``
+directory in rst files. The html template and css can be found under
+``themes/ubuntu``. If adding a new article, make sure to add it to the
+``ubuntu-packaging-guide/index.rst`` file so that it appears in the table of
+contents.
 
 Development is hosted on Launchpad:
 
-Bugs - https://bugs.launchpad.net/ubuntu-packaging-guide/
-Bzr Branch - lp:ubuntu-packaging-guide
-Translations -https://translations.launchpad.net/ubuntu-packaging-guide
+:Bugs: https://bugs.launchpad.net/ubuntu-packaging-guide/
+:Bzr Branch: lp:ubuntu-packaging-guide
+:Translations: https://translations.launchpad.net/ubuntu-packaging-guide
 
 This project is licensed under the CC-BY-SA-3.0, the full text of which can be
-found in COPYING. Further information cand be found in 'debian/copyright'.
-
-
-Sphinx & ReStructured text
---------------------------
-
-The guide is built using Sphinx (http://sphinx.pocoo.org/). Articles should be
-written in ReStructured text. The following links might be helpful:
-
-http://docutils.sourceforge.net/docs/user/rst/quickstart.html
-http://docutils.sourceforge.net/docs/user/rst/quickref.html
+found in ``COPYING``. Further information can be found in ``debian/copyright``.
+
+
+Sphinx & reStructuredText
+-------------------------
+
+The guide is built using `Sphinx <http://sphinx.pocoo.org/>`_. Articles should
+be written in reStructuredText. The following links might be helpful:
+
+* http://docutils.sourceforge.net/docs/user/rst/quickstart.html
+* http://docutils.sourceforge.net/docs/user/rst/quickref.html
 
 
 Building
 --------
 
 The power of Sphinx is that it can generate documentation in many formats.
-Running 'make all' will generate the guide in html, dirhtml, singlehtml, pickle,
-json, htmlhelp, qthelp, devhelp, epub, latex, latexpdf, text, and man formats.
-They will be written to the '_build' directory.
+Running ``make all`` will generate the guide in html, dirhtml, singlehtml,
+pickle, json, htmlhelp, qthelp, devhelp, epub, latex, latexpdf, text, and
+man formats. They will be written to the ``_build`` directory.
 
 Not all of these formats are important to us. You can build an individual
-format with, for example, 'make html'. Run 'make help' for a list of all
+format with, for example, ``make html``. Run ``make help`` for a list of all
 targets.
 
 Please at least test your fixes by building the html version.
+
+Translating
+-----------
+
+We use Sphinx l10n module and Gettext for translating Ubuntu Packaging Guide.
+Translation takes place on
+`Launchpad <http://translations.launchpad.net/ubuntu-packaging-guide>`_, and
+translated ``.po`` files are automatically imported to the bzr branch.
+
+Some notes about translating the guide:
+
+- Only inline links can be translated currently. Do not translate named
+  links.
+- Some formatting is part of reStructuredText and should not be changed,
+  including emphasis (which uses asterisks or underscores), paragraph ending
+  before a code block (``::``) and double backtick quotes (``\`\```).
+
+To test your translation, use ``make BUILDER-LANGUAGE`` command (for example,
+``make html-it`` will build HTML docs in Italian language).

=== modified file 'debian/changelog'
--- debian/changelog	2013-02-09 10:07:33 +0000
+++ debian/changelog	2013-02-09 11:08:21 +0000
@@ -6,6 +6,7 @@
     - Make sure .mo files are built in locale targets.
   * auto-pkg-test.rst: Updated links for raring.
   * Add a work-around for the blank pages in PDF bug (LP: #1095513).
+  * Update README and add some information for translators.
 
   [ Daniel Holbach ]
   * Document where to find a list of required autopkgtests and where