- Rename .sgml files to .xml

- Reflect the rename in referencing files

Approved by:	doceng (implicit)

1 files changed, 484 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
new file mode 100644
index 0000000000..35a1e05b13
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
@@ -0,0 +1,484 @@
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!-- Copyright (c) 1999 Nik Clayton, All rights reserved.
+
+     Redistribution and use in source (SGML DocBook) and 'compiled' forms
+     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+     modification, are permitted provided that the following conditions
+     are met:
+
+      1. Redistributions of source code (SGML DocBook) must retain the above
+         copyright notice, this list of conditions and the following
+         disclaimer as the first lines of this file unmodified.
+
+      2. Redistributions in compiled form (transformed to other DTDs,
+         converted to PDF, PostScript, RTF and other formats) must reproduce
+         the above copyright notice, this list of conditions and the
+         following disclaimer in the documentation and/or other materials
+         provided with the distribution.
+
+     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+     POSSIBILITY OF SUCH DAMAGE.
+
+     $FreeBSD$
+-->
+
+<chapter id="translations">
+  <title>Translations</title>
+
+  <para>This is the FAQ for people translating the FreeBSD
+    documentation (FAQ, Handbook, tutorials, manual pages, and others)
+    to different languages.</para>
+
+  <para>It is <emphasis>very</emphasis> heavily based on the
+    translation FAQ from the FreeBSD German Documentation Project,
+    originally written by Frank Gr&uuml;nder
+    <email>elwood@mc5sys.in-berlin.de</email> and translated back to
+    English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
+
+  <para>The FAQ is maintained by the &a.doceng;.</para>
+
+  <qandaset>
+    <qandaentry>
+      <question>
+	<para>Why a FAQ?</para>
+      </question>
+
+      <answer>
+	<para>More and more people are approaching the freebsd-doc
+	  mailing list and volunteering to translate FreeBSD
+	  documentation to other languages.  This FAQ aims to answer
+	  their questions so they can start translating documentation
+	  as quickly as possible.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
+	  mean?</para>
+      </question>
+
+      <answer>
+	<para><phrase>i18n</phrase> means
+	  <phrase>internationalization</phrase> and
+	  <phrase>l10n</phrase> means <phrase>localization</phrase>.
+	  They are just a convenient shorthand.</para>
+
+	<para><phrase>i18n</phrase> can be read as <quote>i</quote>
+	  followed by 18 letters, followed by <quote>n</quote>.
+	  Similarly, <phrase>l10n</phrase> is <quote>l</quote>
+	  followed by 10 letters, followed by <quote>n</quote>.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>Is there a mailing list for translators?</para>
+      </question>
+
+      <answer>
+	<para>Yes.  Different translation groups have their own
+	  mailing lists.  The <ulink
+	    url="http://www.freebsd.org/docproj/translations.html">list
+	    of translation projects</ulink> has more information about
+	  the mailing lists and web sites run by each translation
+	  project.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>Are more translators needed?</para>
+      </question>
+
+      <answer>
+	<para>Yes.  The more people work on translation the faster it
+	  gets done, and the faster changes to the English
+	  documentation are mirrored in the translated
+	  documents.</para>
+
+	<para>You do not have to be a professional translator to be
+	  able to help.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>What languages do I need to know?</para>
+      </question>
+
+      <answer>
+	<para>Ideally, you will have a good knowledge of written
+	  English, and obviously you will need to be fluent in the
+	  language you are translating to.</para>
+
+	<para>English is not strictly necessary.  For example, you
+	  could do a Hungarian translation of the FAQ from the Spanish
+	  translation.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>What software do I need to know?</para>
+      </question>
+
+      <answer>
+	<para>It is strongly recommended that you maintain a local
+	  copy of the FreeBSD Subversion repository (at least the
+	  documentation part).  This can be done by running:</para>
+
+	<screen>&prompt.user; <userinput><command>svn</command> checkout svn://svn.FreeBSD.org/doc/head/ head</userinput></screen>
+
+	<note>
+	  <para>This will require the <filename
+	      role="package">devel/subversion</filename> package to
+	    be installed.</para>
+	</note>
+
+	<para>You should be comfortable using
+	  <application>svn</application>.  This will allow you to see
+	  what has changed between different versions of the files
+	  that make up the documentation.</para>
+
+	<para>For example, to view the differences between revisions
+	  <literal>r33733</literal> and <literal>r33734</literal> of
+	  <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
+	  run:</para>
+
+	<screen>&prompt.user; <userinput><command>svn</command> diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename></userinput></screen>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>How do I find out who else might be translating to the
+	  same language?</para>
+      </question>
+
+      <answer>
+	<para>The <ulink
+	    url="http://www.FreeBSD.org/docproj/translations.html">Documentation
+	    Project translations page</ulink> lists the translation
+	  efforts that are currently known about.  If others are
+	  already working on translating documentation to your
+	  language, please do not duplicate their efforts.  Instead,
+	  contact them to see how you can help.</para>
+
+	<para>If no one is listed on that page as translating for your
+	  language, then send a message to the &a.doc; in case someone
+	  else is thinking of doing a translation, but has not
+	  announced it yet.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>No one else is translating to my language.  What do I
+	  do?</para>
+      </question>
+
+      <answer>
+	<para>Congratulations, you have just started the
+	  <quote>FreeBSD <replaceable>your-language-here</replaceable>
+	  Documentation Translation Project</quote>.  Welcome
+	  aboard.</para>
+
+	<para>First, decide whether or not you have got the time to
+	  spare.  Since you are the only person working on your
+	  language at the moment it is going to be your responsibility
+	  to publicize your work and coordinate any volunteers that
+	  might want to help you.</para>
+
+	<para>Write an email to the Documentation Project mailing
+	  list, announcing that you are going to translate the
+	  documentation, so the Documentation Project translations
+	  page can be maintained.</para>
+
+	<para>If there is already someone in your country providing
+	  FreeBSD mirroring services you should contact them and ask
+	  if you can have some webspace for your project, and possibly
+	  an email address or mailing list services.</para>
+
+	<para>Then pick a document and start translating.  It is best
+	  to start with something fairly small&mdash;either the FAQ,
+	  or one of the tutorials.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>I have translated some documentation, where do I send
+	  it?</para>
+      </question>
+
+      <answer>
+	<para>That depends.  If you are already working with a
+	  translation team (such as the Japanese team, or the German
+	  team) then they will have their own procedures for handling
+	  submitted documentation, and these will be outlined on their
+	  web pages.</para>
+
+	<para>If you are the only person working on a particular
+	  language (or you are responsible for a translation project
+	  and want to submit your changes back to the FreeBSD project)
+	  then you should send your translation to the FreeBSD project
+	  (see the next question).</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>I am the only person working on translating to this
+	  language, how do I submit my translation?</para>
+
+	<para>or</para>
+
+	<para>We are a translation team, and want to submit
+	  documentation that our members have translated for
+	  us.</para>
+      </question>
+
+      <answer>
+	<para>First, make sure your translation is organized properly.
+	  This means that it should drop into the existing
+	  documentation tree and build straight away.</para>
+
+	<para>Currently, the FreeBSD documentation is stored in a top
+	  level directory called <filename>head/</filename>.
+	  Directories below this are named according to the language
+	  code they are written in, as defined in ISO639
+	  (<filename>/usr/share/misc/iso639</filename> on a version of
+	  FreeBSD newer than 20th January 1999).</para>
+
+	<para>If your language can be encoded in different ways (for
+	  example, Chinese) then there should be directories below
+	  this, one for each encoding format you have provided.</para>
+
+	<para>Finally, you should have directories for each
+	  document.</para>
+
+	<para>For example, a hypothetical Swedish translation might
+	  look like:</para>
+
+	<programlisting>head/
+    sv_SE.ISO8859-1/
+                     Makefile
+                     htdocs/
+                           docproj/
+                     books/
+                           faq/
+                               Makefile
+                               book.xml</programlisting>
+
+	<para><literal>sv_SE.ISO8859-1</literal> is the name of the
+	  translation, in
+	  <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
+	  form.  Note the two Makefiles, which will be used to build
+	  the documentation.</para>
+
+	<para>Use &man.tar.1; and &man.gzip.1; to compress up your
+	  documentation, and send it to the project.</para>
+
+	<screen>&prompt.user; <userinput>cd doc</userinput>
+&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
+&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>
+
+	<para>Put <filename>swedish-docs.tar.gz</filename> somewhere.
+	  If you do not have access to your own webspace (perhaps your
+	  ISP does not let you have any) then you can email
+	  &a.doceng;, and arrange to email the files when it is
+	  convenient.</para>
+
+	<para>Either way, you should use &man.send-pr.1; to submit a
+	  report indicating that you have submitted the documentation.
+	  It would be very helpful if you could get other people to
+	  look over your translation and double check it first, since
+	  it is unlikely that the person committing it will be fluent
+	  in the language.</para>
+
+	<para>Someone (probably the Documentation Project Manager,
+	  currently &a.doceng;) will then take your translation and
+	  confirm that it builds.  In particular, the following things
+	  will be looked at:</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>Do all your files use RCS strings (such as
+	      "ID")?</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Does <command>make all</command> in the
+	      <filename>sv_SE.ISO8859-1</filename> directory work
+	      correctly?</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Does <command>make install</command> work
+	      correctly?</para>
+	  </listitem>
+	</orderedlist>
+
+	<para>If there are any problems then whoever is looking at the
+	  submission will get back to you to work them out.</para>
+
+	<para>If there are no problems your translation will be
+	  committed as soon as possible.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>Can I include language or country specific text in my
+	  translation?</para>
+      </question>
+
+      <answer>
+	<para>We would prefer that you did not.</para>
+
+	<para>For example, suppose that you are translating the
+	  Handbook to Korean, and want to include a section about
+	  retailers in Korea in your Handbook.</para>
+
+	<para>There is no real reason why that information should not
+	  be in the English (or German, or Spanish, or Japanese, or
+	  &hellip;) versions as well.  It is feasible that an English
+	  speaker in Korea might try to pick up a copy of FreeBSD
+	  whilst over there.  It also helps increase FreeBSD's
+	  perceived presence around the globe, which is not a bad
+	  thing.</para>
+
+	<para>If you have country specific information, please submit
+	  it as a change to the English Handbook (using
+	  &man.send-pr.1;) and then translate the change back to your
+	  language in the translated Handbook.</para>
+
+	<para>Thanks.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>How should language specific characters be
+	  included?</para>
+      </question>
+
+      <answer>
+	<para>Non-ASCII characters in the documentation should be
+	  included using SGML entities.</para>
+
+	<para>Briefly, these look like an ampersand (&amp;), the name
+	  of the entity, and a semi-colon (;).</para>
+
+	<para>The entity names are defined in ISO8879, which is in the
+	  ports tree as <filename
+	    role="package">textproc/iso8879</filename>.</para>
+
+	<para>A few examples include:</para>
+
+	<segmentedlist>
+	  <segtitle>Entity</segtitle>
+
+	  <segtitle>Appearance</segtitle>
+
+	  <segtitle>Description</segtitle>
+
+	  <seglistitem>
+	    <seg>&amp;eacute;</seg>
+	    <seg>&eacute;</seg>
+	    <seg>Small <quote>e</quote> with an acute accent</seg>
+	  </seglistitem>
+
+	  <seglistitem>
+	    <seg>&amp;Eacute;</seg>
+	    <seg>&Eacute;</seg>
+	    <seg>Large <quote>E</quote> with an acute accent</seg>
+	  </seglistitem>
+
+	  <seglistitem>
+	    <seg>&amp;uuml;</seg>
+	    <seg>&uuml;</seg>
+	    <seg>Small <quote>u</quote> with an umlaut</seg>
+	  </seglistitem>
+	</segmentedlist>
+
+	<para>After you have installed the iso8879 port, the files in
+	  <filename>/usr/local/share/sgml/iso8879</filename> contain
+	  the complete list.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>Addressing the reader</para>
+      </question>
+
+      <answer>
+	<para>In the English documents, the reader is addressed as
+	  <quote>you</quote>, there is no formal/informal distinction
+	  as there is in some languages.</para>
+
+	<para>If you are translating to a language which does
+	  distinguish, use whichever form is typically used in other
+	  technical documentation in your language.  If in doubt, use
+	  a mildly polite form.</para>
+      </answer>
+    </qandaentry>
+
+    <qandaentry>
+      <question>
+	<para>Do I need to include any additional information in my
+	  translations?</para>
+      </question>
+
+      <answer>
+	<para>Yes.</para>
+
+	<para>The header of the English version of each document will
+	  look something like this:</para>
+
+	<programlisting>&lt;!--
+     The FreeBSD Documentation Project
+
+     &dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &dollar;
+--&gt;</programlisting>
+
+	<para>The exact boilerplate may change, but it will always
+	  include a &dollar;FreeBSD&dollar; line and the phrase
+	  <literal>The FreeBSD Documentation Project</literal>.
+	  Note that the &dollar;FreeBSD part is expanded automatically
+	  by Subversion, so it should be empty (just
+	  <literal>&dollar;FreeBSD&dollar;</literal>) for new
+	  files.</para>
+
+	<para>Your translated documents should include their own
+	  &dollar;FreeBSD&dollar; line, and change the
+	  <literal>FreeBSD Documentation Project</literal> line to
+	  <literal>The FreeBSD <replaceable>language</replaceable>
+	    Documentation Project</literal>.</para>
+
+	<para>In addition, you should add a third line which indicates
+	  which revision of the English text this is based on.</para>
+
+	<para>So, the Spanish version of this file might start:</para>
+
+	<programlisting>&lt;!--
+     The FreeBSD Spanish Documentation Project
+
+     &dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
+     Original revision: r38674
+--&gt;</programlisting>
+      </answer>
+    </qandaentry>
+  </qandaset>
+</chapter>