Index: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 52691)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 52692)
@@ -1,264 +1,264 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 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.
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
<title>Overview</title>
<para>Welcome to the &os; Documentation Project
(<acronym>FDP</acronym>). Quality documentation is crucial
to the success of &os;, and we value your contributions very
highly.</para>
<para>This document describes how the <acronym>FDP</acronym> is
organized, how to write and submit documentation, and how to
effectively use the available tools.</para>
<para>Everyone is welcome to contribute to the
<acronym>FDP</acronym>. Willingness to contribute is the only
membership requirement.</para>
<para>This primer shows how to:</para>
<itemizedlist>
<listitem>
<para>Identify which parts of &os; are maintained by the
<acronym>FDP</acronym>.</para>
</listitem>
<listitem>
<para>Install the required documentation tools and files.</para>
</listitem>
<listitem>
<para>Make changes to the documentation.</para>
</listitem>
<listitem>
<para>Submit changes back for review and inclusion in the &os;
documentation.</para>
</listitem>
</itemizedlist>
<sect1 xml:id="overview-quick-start">
<title>Quick Start</title>
<para>Some preparatory steps must be taken before editing the &os;
documentation. First, subscribe to the &a.doc;. Some team
members also interact on the <literal>#bsddocs</literal>
<acronym>IRC</acronym> channel on
<link xlink:href="http://www.efnet.org/">EFnet</link>. These
people can help with questions or problems involving the
documentation.</para>
<procedure>
<step>
<para>Install the
<package>textproc/docproj</package> meta-package
and <application>Subversion</application>.
This meta-package installs all of the software needed to
edit and build &os; documentation. The
<application>Subversion</application> package is needed to
obtain a working copy of the documentation and generate
patches with.</para>
<screen>&prompt.root; <userinput>pkg install docproj subversion</userinput></screen>
</step>
<step>
<para>Install a local working copy of the documentation from
the &os; repository in
<filename>~/doc</filename> (see
<xref linkend="working-copy"/>).</para>
- <screen>&prompt.user; <userinput>svn checkout http://repo.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>Configure the text editor:</para>
<itemizedlist>
<listitem>
<para>Word wrap set to 70 characters.</para>
</listitem>
<listitem>
<para>Tab stops set to 2.</para>
</listitem>
<listitem>
<para>Replace each group of 8 leading spaces with a
single tab.</para>
</listitem>
</itemizedlist>
<para>Specific editor configurations are listed in
<xref linkend="editor-config"/>.</para>
</step>
<step>
<para>Update the local working copy:</para>
<screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
</step>
<step>
<para>Edit the documentation files that require changes. If a
file needs major changes, consult the mailing list for
input.</para>
<para>References to tag and entity usage can be found in
<xref linkend="xhtml-markup"/> and
<xref linkend="docbook-markup"/>.</para>
</step>
<step>
<para>After editing, check for problems by running:</para>
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
<para>Review the output and edit the file to fix any problems
shown, then rerun the command to find any remaining
problems. Repeat until all of the errors are
resolved.</para>
</step>
<step>
<para><emphasis>Always</emphasis> build-test changes before
submitting them. Running <userinput>make</userinput> in the
top-level directory of the documentation being edited will
generate that documentation in split HTML format. For
example, to build the English version of the Handbook in
<acronym>HTML</acronym>, run <command>make</command> in the
<filename>en_US.ISO8859-1/books/handbook/</filename>
directory.</para>
</step>
<step>
<para>When changes are complete and tested, generate a
<quote>diff file</quote>:</para>
<screen>&prompt.user; <userinput>cd ~/doc</userinput>
&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
<para>Give the diff file a descriptive name. In the example
above, changes have been made to the
<filename>bsdinstall</filename> portion of
the Handbook.</para>
</step>
<step>
<para>Submit the diff file using the web-based <link
xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation">Problem
Report</link> system. If using the web form, enter a
Summary of <emphasis>[patch] <replaceable>short description
of problem</replaceable></emphasis>. Select the
Component <literal>Documentation</literal>. In the
Description field, enter a short description of the changes
and any important details about them. Use the
<guibutton>[ Add an attachment ]</guibutton>
button to attach the diff file. Finally, use the
<guibutton>[ Submit Bug ]</guibutton> button to
submit your diff to the problem report system.</para>
</step>
</procedure>
</sect1>
<sect1 xml:id="overview-doc">
<title>The &os; Documentation Set</title>
<para>The <acronym>FDP</acronym> is responsible for four
categories of &os; documentation.</para>
<itemizedlist>
<listitem>
<para><emphasis>Handbook</emphasis>: The Handbook is the
comprehensive online resource and reference for &os;
users.</para>
</listitem>
<listitem>
<para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym>
uses a short question and answer format to address questions
that are frequently asked on the various mailing lists and
forums devoted to &os;. This format does not permit long
and comprehensive answers.</para>
</listitem>
<listitem>
<para><emphasis>Manual pages</emphasis>: The English language
system manual pages are usually not written by the
<acronym>FDP</acronym>, as they are part of the base system.
However, the <acronym>FDP</acronym> can reword parts of
existing manual pages to make them clearer or to correct
inaccuracies.</para>
</listitem>
<listitem>
<para><emphasis>Web site</emphasis>: This is the main &os;
presence on the web, visible at <link
xlink:href="https://www.freebsd.org/index.html">
https://www.FreeBSD.org/</link>
and many mirrors around the world. The web site is
typically a new user's first exposure to &os;.</para>
</listitem>
</itemizedlist>
<para>Translation teams are responsible for translating the
Handbook and web site into different languages. Manual pages
are not translated at present.</para>
<para>Documentation source for the &os; web site, Handbook, and
<acronym>FAQ</acronym> is available in the documentation
repository at
<literal>https://svn.FreeBSD.org/doc/</literal>.</para>
<para>Source for manual pages is available in a separate
source repository located at
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
<para>Documentation commit messages are visible with
<command>svn log</command>. Commit messages are also
archived at <uri xlink:href="&a.svn-doc-all.url;">
&a.svn-doc-all.url;</uri>.</para>
<para>Web frontends to both of these repositories are available
at <link xlink:href="https://svnweb.FreeBSD.org/doc/"></link>
and <link
xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para>
<para>Many people have written tutorials or how-to articles about
&os;. Some are stored as part of the <acronym>FDP</acronym>
files. In other cases, the author has decided to keep the
documentation separate. The <acronym>FDP</acronym> endeavors to
provide links to as much of this external documentation as
possible.</para>
</sect1>
</chapter>
Index: head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 52691)
+++ head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 52692)
@@ -1,483 +1,483 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml: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ü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>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 <link
xlink:href="https://www.freebsd.org/docproj/translations.html">list
of translation projects</link> has more information about
the mailing lists and web sites run by each translation
project. In addition there is
<email>freebsd-translators@freebsd.org</email> for general
translation discussion.</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>svn checkout http://repo.FreeBSD.org/doc/head/ head</userinput></screen>
+ <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen>
<para><link
xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link>
is a public <literal>SVN</literal> server. Verify the
server certificate from the list of <link
xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
mirror sites</link>.</para>
<note>
<para>This will require the
<package>devel/subversion</package> 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>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
<para>Please see the complete explanation of using
<application>Subversion</application> in &os; in the <link
xlink:href="&url.books.handbook;/svn.html">&os;
Handbook</link>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How do I find out who else might be translating to the
same language?</para>
</question>
<answer>
<para>The <link
xlink:href="https://www.FreeBSD.org/docproj/translations.html">Documentation
Project translations page</link> 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—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 Bugzilla 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
…) 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
Bugzilla) 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 (&), 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 <package>textproc/iso8879</package>.</para>
<para>A few examples include:</para>
<segmentedlist>
<segtitle>Entity</segtitle>
<segtitle>Appearance</segtitle>
<segtitle>Description</segtitle>
<seglistitem>
<seg>&eacute;</seg>
<seg>é</seg>
<seg>Small <quote>e</quote> with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&Eacute;</seg>
<seg>É</seg>
<seg>Large <quote>E</quote> with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&uuml;</seg>
<seg>ü</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/xml/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><!--
The FreeBSD Documentation Project
$FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $
--></programlisting>
<para>The exact boilerplate may change, but it will always
include a $FreeBSD$ line and the phrase
<literal>The FreeBSD Documentation Project</literal>.
Note that the $FreeBSD part is expanded automatically
by Subversion, so it should be empty (just
<literal>$FreeBSD$</literal>) for new
files.</para>
<para>Your translated documents should include their own
$FreeBSD$ 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><!--
The FreeBSD Spanish Documentation Project
$FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $
Original revision: r38674
--></programlisting>
</answer>
</qandaentry>
</qandaset>
</chapter>
Index: head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52691)
+++ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52692)
@@ -1,184 +1,184 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 2013 Warren Block
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE
AUTHORS OR CONTRIBUTORS 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 SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="working-copy">
<title>The Working Copy</title>
<para>The <emphasis>working copy</emphasis> is a copy of the &os;
repository documentation tree downloaded onto the local computer.
Changes are made to the local working copy, tested, and then
submitted as patches to be committed to the main
repository.</para>
<para>A full copy of the documentation tree can occupy 700 megabytes
of disk space. Allow for a full gigabyte of space to have room
for temporary files and test versions of various output
formats.</para>
<para><link
xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link>
is used to manage the &os; documentation files. It is obtained by
installing the <application>Subversion</application>
package:</para>
<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
<sect1 xml:id="working-copy-doc-and-src">
<title>Documentation and Manual Pages</title>
<para>&os; documentation is not just books and articles. Manual
pages for all the commands and configuration files are also part
of the documentation, and part of the <acronym>FDP</acronym>'s
territory. Two repositories are involved:
<literal>doc</literal> for the books and articles, and
<literal>base</literal> for the operating system and manual
pages. To edit manual pages, the <literal>base</literal>
repository must be checked out separately.</para>
<para>Repositories may contain multiple versions of documentation
and source code. New modifications are almost always made only
to the latest version, called <literal>head</literal>.</para>
</sect1>
<sect1 xml:id="working-copy-choosing-directory">
<title>Choosing a Directory</title>
<para>&os; documentation is traditionally stored in
<filename>/usr/doc/</filename>, and system
source code with manual pages in
<filename>/usr/src/</filename>. These
directory trees are relocatable, and users may want to put the
working copies in other locations to avoid interfering with
existing information in the main directories. The examples
that follow use <filename>~/doc</filename>
and <filename>~/src</filename>, both
subdirectories of the user's home directory.</para>
</sect1>
<sect1 xml:id="working-copy-checking-out">
<title>Checking Out a Copy</title>
<para>A download of a working copy from the repository is called
a <emphasis>checkout</emphasis>, and done with
<command>svn checkout</command>. This example checks out a
copy of the latest version (<literal>head</literal>) of
the main documentation tree:</para>
- <screen>&prompt.user; <userinput>svn checkout http://repo.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen>
<para>A checkout of the source code to work on manual pages is
very similar:</para>
- <screen>&prompt.user; <userinput>svn checkout http://repo.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-updating">
<title>Updating a Working Copy</title>
<para>The documents and files in the &os; repository change daily.
People modify files and commit changes frequently. Even a short
time after an initial checkout, there will already be
differences between the local working copy and the main &os;
repository. To update the local version with the changes that
have been made to the main repository, use
<command>svn update</command> on the directory containing the
local working copy:</para>
<screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen>
<para>Get in the protective habit of using
<command>svn update</command> before editing document files.
Someone else may have edited that file very recently, and the
local working copy will not include the latest changes until it
has been updated. Editing the newest version of a file is much
easier than trying to combine an older, edited local file with
the newer version from the repository.</para>
</sect1>
<sect1 xml:id="working-copy-revert">
<title>Reverting Changes</title>
<para>Sometimes it turns out that changes were
not necessary after all, or the writer just wants to start over.
Files can be <quote>reset</quote> to their unchanged form with
<command>svn revert</command>. For example, to erase the edits
made to <filename>chapter.xml</filename> and reset it to
unmodified form:</para>
<screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen>
</sect1>
<sect1 xml:id="working-copy-making-diff">
<title>Making a Diff</title>
<para>After edits to a file or group of files are completed, the
differences between the local working copy and the version on
the &os; repository must be collected into a single file for
submission. These <emphasis>diff</emphasis> files are produced
by redirecting the output of <command>svn diff</command> into a
file:</para>
<screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
&prompt.user; <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen>
<para>Give the file a meaningful name that identifies the
contents. The example above is for spelling fixes to the whole
documentation tree.</para>
<para>If the diff file is to be submitted with the web
<quote><link
xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit
a &os; problem report</link></quote> interface, add a
<filename>.txt</filename> extension to give the earnest and
simple-minded web form a clue that the contents are plain
text.</para>
<para>Be careful: <command>svn diff</command> includes all changes
made in the current directory and any subdirectories. If there
are files in the working copy with edits that are not ready to
be submitted yet, provide a list of only the files that are to
be included:</para>
<screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput>
&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen>
</sect1>
<sect1 xml:id="working-copy-subversion-references">
<title><application>Subversion</application> References</title>
<para>These examples show very basic usage of
<application>Subversion</application>. More detail is available
in the <link
xlink:href="http://svnbook.red-bean.com/">Subversion
Book</link> and the <link
xlink:href="http://subversion.apache.org/docs/">Subversion
documentation</link>.</para>
</sect1>
</chapter>