[mapserver-commits] r9059 - in trunk/docs: de/development
en/development
svn at osgeo.org
svn at osgeo.org
Sat May 30 06:56:03 EDT 2009
Author: gislars
Date: 2009-05-30 06:56:03 -0400 (Sat, 30 May 2009)
New Revision: 9059
Modified:
trunk/docs/de/development/documentation.txt
trunk/docs/en/development/documentation.txt
Log:
added instructions how translations are handled
Modified: trunk/docs/de/development/documentation.txt
===================================================================
--- trunk/docs/de/development/documentation.txt 2009-05-29 04:05:07 UTC (rev 9058)
+++ trunk/docs/de/development/documentation.txt 2009-05-30 10:56:03 UTC (rev 9059)
@@ -8,23 +8,23 @@
:Contact: hobu.inc at gmail.com
:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com
-:Revision: $Revision: 8659 $
-:Date: $Date: 2009-03-08 16:31:00 +0100 (So, 08. Mär 2009) $
+:Revision: $Revision: 9040 $
+:Date: $Date: 2009-05-25 15:10:48 +0200 (Mo, 25. Mai 2009) $
.. contents:: Table of Contents
:depth: 2
:backlinks: top
-
+
Background
----------
-The current structure of the MapServer documentation process is for
+The current structure of the MapServer documentation process is for
developers with :ref:`SVN` commit access to maintain their documents
-in reStructuredText format, and therefore all documents live in the
-/docs directory in SVN. The `Sphinx`_ documentation generator is
-used to convert the reStructuredText files to html, and the live
+in reStructuredText format, and therefore all documents live in the
+/docs directory in SVN. The `Sphinx`_ documentation generator is
+used to convert the reStructuredText files to html, and the live
website is then updated on an hourly basis.
-
+
General Guidelines
------------------
@@ -33,12 +33,12 @@
* MapScript instead of mapscript, Mapscript, or map script.
* PostGIS instead of postgis.
* HowTo instead of howto or HOWTO.
-* Email addresses should be manually spam protected:
-
+* Email addresses should be manually spam protected:
+
::
hobu.inc at gmail.com instead of hobu.inc at gmail.com
-
+
reStructuredText Reference Guides
---------------------------------
@@ -47,50 +47,52 @@
reStructuredText Formatting
---------------------------
-* All text should be hard breaks at or around the 80 column mark, just as
+* All text should be hard breaks at or around the 80 column mark, just as
the source code.
* No ``.. sectnum::`` in the contents directives
-* All external links should live at the bottom of your document, under
+* All external links should live at the bottom of your document, under
the heading:
-
+
::
-
+
.. #### rST Link Section ####
* Always include the :Revision: and :Date: lines (as-is) at the top of your
document, such as:
-
+
::
-
- :Revision: $Revision: 8659 $
- :Date: $Date: 2009-03-08 16:31:00 +0100 (So, 08. Mär 2009) $
+ :Revision: $Revision: 9040 $
+ :Date: $Date: 2009-05-25 15:10:48 +0200 (Mo, 25. Mai 2009) $
+
Installing and Using Sphinx for rst-html Generation
---------------------------------------------------
**On Windows:**
#. install `Python 2.X`_
-#. download `setuptools`_
+#. download `setuptools`_
#. make sure that the 'C:\Python2X\Scripts' directory is your path
#. execute the following at commandline:
::
-
+
easy_install Sphinx
-
+
...you should see message: "Finished processing dependencies for Sphinx"
-#. inside the MapServer /docs directory, create /build/doctrees and /build/html
- directories
#. inside the /docs directory, execute:
::
-
- sphinx-build -b html -d build\doctrees . build\html
-
- ...you should see a message: "build succeeded, ..."
-
+ make html
+ or
+
+ ::
+
+ make latex
+
+ the HTML output will be written to the _build/html sub-directory.
+
**On Linux:**
#. make sure you have the Python dev and setuptools packages installed.
@@ -113,7 +115,7 @@
make html
- or
+ or
::
@@ -121,7 +123,52 @@
the HTML output will be written to the build/html sub-directory.
+.. note::
+ If there are more than one translation, the above commands will automatically
+ build all translations.
+
+
+How translations are handled
+----------------------------
+
+
+* All translations are organized in subdirectories in MapServer /docs directory
+* The directories are named using `ISO3166-1 alpha-2 country codes`_, which
+ will also reference to the corresponding flag icon
+* Translations are based on the English docs
+* The directory structure and filenames must be kept, they are used to
+ generate links between the different translations
+
+.. note::
+
+ To start a new translation, copy the directory docs/en to docs/<lang>,
+ where <lang> is one of the country codes.
+
+* It is not recommended to remove untranslated files, as this would end in an
+ 404 error for the user.
+* To keep the translations in sync with the English docs, the translators
+ can monitor commits to the repository.
+
+.. note::
+
+ One way to monitor changes is to subscribe the rss feed at
+ http://trac.osgeo.org/mapserver/log/trunk/docs
+
+**On Linux:**
+
+* You have to define which languages are available by setting LANGUAGES in the
+ Makefile:
+
+ ::
+
+ LANGUAGES = en de
+
+The build script will then process the subdirectories *en* and *de*. If they
+are not accessible, an error message will be returned.
+
+
+
Reference Labels
----------------
@@ -145,5 +192,4 @@
.. _`Quick reStructuredText`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`setuptools`: http://pypi.python.org/pypi/setuptools#windows
.. _`Python 2.X`: http://www.python.org/
-
-
+.. _`ISO3166-1 alpha-2 country codes`: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
Modified: trunk/docs/en/development/documentation.txt
===================================================================
--- trunk/docs/en/development/documentation.txt 2009-05-29 04:05:07 UTC (rev 9058)
+++ trunk/docs/en/development/documentation.txt 2009-05-30 10:56:03 UTC (rev 9059)
@@ -14,17 +14,17 @@
.. contents:: Table of Contents
:depth: 2
:backlinks: top
-
+
Background
----------
-The current structure of the MapServer documentation process is for
+The current structure of the MapServer documentation process is for
developers with :ref:`SVN` commit access to maintain their documents
-in reStructuredText format, and therefore all documents live in the
-/docs directory in SVN. The `Sphinx`_ documentation generator is
-used to convert the reStructuredText files to html, and the live
+in reStructuredText format, and therefore all documents live in the
+/docs directory in SVN. The `Sphinx`_ documentation generator is
+used to convert the reStructuredText files to html, and the live
website is then updated on an hourly basis.
-
+
General Guidelines
------------------
@@ -33,12 +33,12 @@
* MapScript instead of mapscript, Mapscript, or map script.
* PostGIS instead of postgis.
* HowTo instead of howto or HOWTO.
-* Email addresses should be manually spam protected:
-
+* Email addresses should be manually spam protected:
+
::
hobu.inc at gmail.com instead of hobu.inc at gmail.com
-
+
reStructuredText Reference Guides
---------------------------------
@@ -47,20 +47,20 @@
reStructuredText Formatting
---------------------------
-* All text should be hard breaks at or around the 80 column mark, just as
+* All text should be hard breaks at or around the 80 column mark, just as
the source code.
* No ``.. sectnum::`` in the contents directives
-* All external links should live at the bottom of your document, under
+* All external links should live at the bottom of your document, under
the heading:
-
+
::
-
+
.. #### rST Link Section ####
* Always include the :Revision: and :Date: lines (as-is) at the top of your
document, such as:
-
+
::
-
+
:Revision: $Revision$
:Date: $Date$
@@ -70,14 +70,14 @@
**On Windows:**
#. install `Python 2.X`_
-#. download `setuptools`_
+#. download `setuptools`_
#. make sure that the 'C:\Python2X\Scripts' directory is your path
#. execute the following at commandline:
::
-
+
easy_install Sphinx
-
+
...you should see message: "Finished processing dependencies for Sphinx"
#. inside the /docs directory, execute:
@@ -85,7 +85,7 @@
make html
- or
+ or
::
@@ -115,7 +115,7 @@
make html
- or
+ or
::
@@ -123,7 +123,52 @@
the HTML output will be written to the build/html sub-directory.
+.. note::
+ If there are more than one translation, the above commands will automatically
+ build all translations.
+
+
+How translations are handled
+----------------------------
+
+
+* All translations are organized in subdirectories in MapServer /docs directory
+* The directories are named using `ISO3166-1 alpha-2 country codes`_, which
+ will also reference to the corresponding flag icon
+* Translations are based on the English docs
+* The directory structure and filenames must be kept, they are used to
+ generate links between the different translations
+
+.. note::
+
+ To start a new translation, copy the directory docs/en to docs/<lang>,
+ where <lang> is one of the country codes.
+
+* It is not recommended to remove untranslated files, as this would end in an
+ 404 error for the user.
+* To keep the translations in sync with the English docs, the translators
+ can monitor commits to the repository.
+
+.. note::
+
+ One way to monitor changes is to subscribe the rss feed at
+ http://trac.osgeo.org/mapserver/log/trunk/docs
+
+**On Linux:**
+
+* You have to define which languages are available by setting LANGUAGES in the
+ Makefile:
+
+ ::
+
+ LANGUAGES = en de
+
+The build script will then process the subdirectories *en* and *de*. If they
+are not accessible, an error message will be returned.
+
+
+
Reference Labels
----------------
@@ -147,5 +192,4 @@
.. _`Quick reStructuredText`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`setuptools`: http://pypi.python.org/pypi/setuptools#windows
.. _`Python 2.X`: http://www.python.org/
-
-
+.. _`ISO3166-1 alpha-2 country codes`: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
More information about the mapserver-commits
mailing list