Date: Tue, 27 Oct 2015 22:23:27 +0000 (UTC) From: Rene Ladan <rene@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47688 - head/nl_NL.ISO8859-1/books/fdp-primer Message-ID: <201510272223.t9RMNRfx088868@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: rene Date: Tue Oct 27 22:23:27 2015 New Revision: 47688 URL: https://svnweb.freebsd.org/changeset/doc/47688 Log: Add an initial and work-in-progress Dutch PO translation of the FreeBSD ocumentation Project Primer. Some notes: - 'make tran' generates a single book.xml from the PO file which combines the contents of the separate English files. - Makefile is simplified to only have book.xml as source. Split output is supported as usual. - IMAGE_LIB is left undefined, 'make' does not complain about this. Added: head/nl_NL.ISO8859-1/books/fdp-primer/ - copied from r47683, head/en_US.ISO8859-1/books/fdp-primer/ head/nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po (contents, props changed) Modified: head/nl_NL.ISO8859-1/books/fdp-primer/Makefile head/nl_NL.ISO8859-1/books/fdp-primer/book.xml Modified: head/nl_NL.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Tue Oct 27 13:11:32 2015 (r47683) +++ head/nl_NL.ISO8859-1/books/fdp-primer/Makefile Tue Oct 27 22:23:27 2015 (r47688) @@ -20,33 +20,6 @@ INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml -SRCS+= overview/chapter.xml -SRCS+= tools/chapter.xml -SRCS+= working-copy/chapter.xml -SRCS+= structure/chapter.xml -SRCS+= doc-build/chapter.xml -SRCS+= the-website/chapter.xml -SRCS+= xml-primer/chapter.xml -SRCS+= xhtml-markup/chapter.xml -SRCS+= docbook-markup/chapter.xml -SRCS+= stylesheets/chapter.xml -SRCS+= translations/chapter.xml -SRCS+= po-translations/chapter.xml -SRCS+= writing-style/chapter.xml -SRCS+= editor-config/chapter.xml -SRCS+= see-also/chapter.xml - -SRCS+= examples/appendix.xml - -# Images from the cross-document image library -IMAGES_LIB= callouts/1.png -IMAGES_LIB+= callouts/2.png -IMAGES_LIB+= callouts/3.png -IMAGES_LIB+= callouts/4.png -IMAGES_LIB+= callouts/5.png - -# Entities -SRCS+= chapters.ent URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. Modified: head/nl_NL.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Tue Oct 27 13:11:32 2015 (r47683) +++ head/nl_NL.ISO8859-1/books/fdp-primer/book.xml Tue Oct 27 22:23:27 2015 (r47688) @@ -1,9 +1,32 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!-- ENTITY index SYSTEM "index.xml" --> -]> +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!ENTITY chap.overview SYSTEM "overview/chapter.xml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.xml"> +<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> +<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> +<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> +<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> +<!ENTITY chap.translations SYSTEM "translations/chapter.xml"> +<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> +<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> +<!ENTITY app.examples SYSTEM "examples/appendix.xml"> +<!-- ENTITY index SYSTEM "index.xml" -->]> <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -35,84 +58,75 @@ $FreeBSD$ --> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - <info><title>FreeBSD Documentation Project Primer for New - Contributors</title> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl_NL"> + <info><title>Overzicht van het FreeBSD Documentatieproject voor nieuwe bijdragers</title> - <author><orgname>The FreeBSD Documentation Project</orgname></author> + <author><orgname>Het FreeBSD Documentatieroject</orgname></author> - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <year>2010</year> - <year>2011</year> - <year>2012</year> - <year>2013</year> - <year>2014</year> - <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> - </copyright> + <copyright><year>1998</year> <year>1999</year> <year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <holder role="mailto:doceng@FreeBSD.org">DocEng</holder></copyright> <pubdate role="rcs">$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - &legalnotice; + +<legalnotice xml:id="legalnotice"> + <title>Copyright</title> + + <para>Herdistributiie en gebruik in bron- (XML DocBook) en 'gecompileerde' vormen (XML, HTML, PDF, PostScript, RTF enzovoorts) met of zonder aanpassingen, is toegestaan gegeven dat aan de volgende voorwaarden is voldaan:</para> + + <orderedlist> + <listitem> + <para>Herdistributies van broncode (XML DocBook) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer onveranderd als de eerste regels van dit bestand behouden.</para> + </listitem> + + <listitem> + <para>Herdistributies in gecompileerde vorm (getransformeerd naar andere DTDs, omgezet naar PDF, PostScript, RTF en andere formaten) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer in de documentatie en/of andere materialen geleverd met de distributie herproduceren.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 FREEBSD DOCUMENTATION PROJECT 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.</para> + </important> +</legalnotice> + <abstract> - <para>Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable, and we - appreciate it.</para> - - <para>This primer covers details needed - to start contributing to the FreeBSD Documentation - Project, or <acronym>FDP</acronym>, including tools, software, - and the philosophy behind the - Documentation Project.</para> + <para>Dank u dat u deel bent geworden van het FreeBSD Documentatieproject. Uw bijdrage is zeer waardevol, en we stellen het op prijs.</para> + + <para>Deze handleidng behandelt details die nodig zijn om te beginnen met bij te dragen aan het FreeBSD Documentatieproject, of <acronym>FDP</acronym>, inclusief gereedschappen, softare en de gedachten achter het Documentatieproject.</para> - <para>This is a work in progress. Corrections and - additions are always welcome.</para> + <para>Dit is werk in uitvoering. Correcties en aanvullingen zijn altijd welkom.</para> </abstract> </info> <preface xml:id="preface"> - <title>Preface</title> + <title>Inleiding</title> <sect1 xml:id="preface-prompts"> - <title>Shell Prompts</title> + <title>Shellprompts</title> - <para>This table shows the default system prompt and - superuser prompt. The examples use these prompts to - indicate which type of user is running the example.</para> + <para>Deze tabel laat de standaard systeemprompt en de prompt van de supergebruiker zien. Deze voorbeelden gebruiken deze prompts om aan te geven welk soort gebruiker het voorbeeld draait.</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> - <entry>User</entry> + <entry>Gebruiker</entry> <entry>Prompt</entry> </row> </thead> <tbody> <row> - <entry>Normal user</entry> - <entry>&prompt.user;</entry> + <entry>Gewone gebruiker</entry> + <entry><prompt>%</prompt></entry> </row> <row> <entry><systemitem class="username">root</systemitem></entry> - <entry>&prompt.root;</entry> + <entry><prompt>#</prompt></entry> </row> </tbody> </tgroup> @@ -120,74 +134,66 @@ </sect1> <sect1 xml:id="preface-conventions"> - <title>Typographic Conventions</title> + <title>Typografische aannames</title> - <para>This table describes the typographic conventions - used in this book.</para> + <para>Deze tabel beschrijft de typografische aannames die in dit boek gebruikt worden.</para> <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> - <entry>Meaning</entry> - <entry>Examples</entry> + <entry>Betekenis</entry> + <entry>Voorbeelden</entry> </row> </thead> <tbody> <row> - <entry>The names of commands.</entry> - <entry>Use <command>ls -l</command> to list all - files.</entry> + <entry>De naam van commando's.</entry> + <entry>Gebruik <command>ls -l</command> voor een lijst van alle bestanden.</entry> </row> <row> - <entry>The names of files.</entry> - <entry>Edit <filename>.login</filename>.</entry> + <entry>De namen van bestanden.</entry> + <entry>Bewerk <filename>.login</filename>.</entry> </row> <row> - <entry>On-screen computer output.</entry> + <entry>Uitvoer op het computerscherm.</entry> <entry><screen>You have mail.</screen></entry> </row> <row> - <entry>What the user types, contrasted with on-screen - computer output.</entry> + <entry>Wat de gebruiker typt, in contrast met uitvoer op het computerscherm.</entry> - <entry><screen>&prompt.user; <userinput>date +"The time is %H:%M"</userinput> -The time is 09:18</screen></entry> + <entry><screen><prompt>%</prompt> <userinput>date +"De tijd is %H:%M"</userinput> +De tijd is 09:18</screen></entry> </row> <row> - <entry>Manual page references.</entry> - <entry>Use &man.su.1; to change user identity.</entry> + <entry>Verwijzing naar handleidingspagina's.</entry> + <entry>Gebruik <citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> om van gebruikersidentiteit te veranderen.</entry> </row> <row> - <entry>User and group names.</entry> - <entry>Only <systemitem class="username">root</systemitem> can do - this.</entry> + <entry>Gebruiker- en groepnamen.</entry> + <entry>Alleen <systemitem class="username">root</systemitem> kan dit doen.</entry> </row> <row> - <entry>Emphasis.</entry> - <entry>The user <emphasis>must</emphasis> do - this.</entry> + <entry>Nadruk.</entry> + <entry>De gebruiker <emphasis>moet</emphasis> dit doen.</entry> </row> <row> - <entry>Text that the user is expected to replace with - the actual text.</entry> + <entry>Tekst die de gebruiker door de eigenlijke tekst dient te vervangen.</entry> - <entry>To search for a keyword in the manual pages, type - <command>man -k - <replaceable>keyword</replaceable></command></entry> + <entry>Gebruik <command>man -k<replaceable>sleutelwoord</replaceable></command> om naar een sleutelwoord in handleidingspagina's te zoeken.</entry> </row> <row> - <entry>Environment variables.</entry> - <entry><envar>$HOME</envar> is set to the user's home + <entry>Omgevingsvariabelen.</entry> + <entry xml:lang="en"><envar>$HOME</envar> is set to the user's home directory.</entry> </row> </tbody> @@ -196,32 +202,32 @@ The time is 09:18</screen></entry> </sect1> <sect1 xml:id="preface-notes"> - <title>Notes, Tips, Important Information, Warnings, and + <title xml:lang="en">Notes, Tips, Important Information, Warnings, and Examples</title> - <para>Notes, warnings, and examples appear within the + <para xml:lang="en">Notes, warnings, and examples appear within the text.</para> <note> - <para>Notes are represented like this, and contain information + <para xml:lang="en">Notes are represented like this, and contain information to take note of, as it may affect what the user does.</para> </note> <tip> - <para>Tips are represented like this, and contain information + <para xml:lang="en">Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something.</para> </tip> <important> - <para>Important information is represented like this. + <para xml:lang="en">Important information is represented like this. Typically, these show extra steps the user may need to take.</para> </important> <warning> - <para>Warnings are represented like this, and contain + <para xml:lang="en">Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. This damage may be physical, to the hardware or the user, or it may be non-physical, such @@ -229,41 +235,8795 @@ The time is 09:18</screen></entry> </warning> <example> - <title>A Sample Example</title> + <title xml:lang="en">A Sample Example</title> - <para>Examples are represented like this, and typically + <para xml:lang="en">Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action.</para> </example> </sect1> <sect1 xml:id="preface-acknowledgements"> - <title>Acknowledgments</title> + <title xml:lang="en">Acknowledgments</title> - <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, + <para xml:lang="en">My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms.</para> </sect1> </preface> - &chap.overview; - &chap.tools; - &chap.working-copy; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.xml-primer; - &chap.xhtml-markup; - &chap.docbook-markup; - &chap.stylesheets; - &chap.translations; - &chap.po-translations; - &chap.writing-style; - &chap.editor-config; - &chap.see-also; + +<!-- 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. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="overview"> + <title xml:lang="en">Overview</title> + + <para xml:lang="en">Welcome to the FreeBSD Documentation Project + (<acronym>FDP</acronym>). Quality documentation is crucial + to the success of FreeBSD, and we value your contributions very + highly.</para> + + <para xml:lang="en">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 xml:lang="en">Everyone is welcome to contribute to the + <acronym>FDP</acronym>. Willingness to contribute is the only + membership requirement.</para> + + <para xml:lang="en">This primer shows how to:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">Identify which parts of FreeBSD are maintained by the + <acronym>FDP</acronym>.</para> + </listitem> + + <listitem> + <para xml:lang="en">Install the required documentation tools and files.</para> + </listitem> + + <listitem> + <para xml:lang="en">Make changes to the documentation.</para> + </listitem> + + <listitem> + <para xml:lang="en">Submit changes back for review and inclusion in the FreeBSD + documentation.</para> + </listitem> + </itemizedlist> + + <sect1 xml:id="overview-doc"> + <title xml:lang="en">The FreeBSD Documentation Set</title> + + <para xml:lang="en">The <acronym>FDP</acronym> is responsible for four + categories of FreeBSD documentation.</para> + + <itemizedlist> + <listitem> + <para xml:lang="en"><emphasis>Handbook</emphasis>: The Handbook is the + comprehensive online resource and reference for FreeBSD + users.</para> + </listitem> + + <listitem> + <para xml:lang="en"><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 FreeBSD. This format does not permit long + and comprehensive answers.</para> + </listitem> + + <listitem> + <para xml:lang="en"><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 xml:lang="en"><emphasis>Web site</emphasis>: This is the main FreeBSD + presence on the web, visible at <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link>; + and many mirrors around the world. The web site is + typically a new user's first exposure to FreeBSD.</para> + </listitem> + </itemizedlist> + + <para xml:lang="en">Translation teams are responsible for translating the + Handbook and web site into different languages. Manual pages + are not translated at present.</para> + + <para xml:lang="en">Documentation source for the FreeBSD web site, Handbook, and + <acronym>FAQ</acronym> is available in the documentation + repository at + <literal>https://svn.FreeBSD.org/doc/</literal>.</para>; + + <para xml:lang="en">Source for manual pages is available in a separate + source repository located at + <literal>https://svn.FreeBSD.org/base/</literal>.</para>; + + <para xml:lang="en">Documentation commit messages are visible with + <command>svn log</command>. Commit messages are also + archived at <uri xlink:href="http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all">http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all</uri>.</para>; + + <para xml:lang="en">Web frontends to both of these repositories are available at <link xlink:href="https://svnweb.FreeBSD.org/doc/"/>; and <link xlink:href="https://svnweb.FreeBSD.org/base/"/>.</para>; + + <para xml:lang="en">Many people have written tutorials or how-to articles about + FreeBSD. 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> + + <sect1 xml:id="overview-quick-start"> + <title xml:lang="en">Quick Start</title> + + <para xml:lang="en">Some preparatory steps must be taken before editing the FreeBSD + documentation. First, subscribe to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc">FreeBSD documentation project mailing list</link>. 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 xml:lang="en">Install the + <package>textproc/docproj</package> + package or port. This meta-port installs all of the + software needed to edit and build FreeBSD documentation.</para> + </step> + + <step> + <para xml:lang="en">Install a local working copy of the documentation from + the FreeBSD repository in + <filename>~/doc</filename> (see + <xref linkend="working-copy"/>).</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para xml:lang="en">Configure the text editor:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">Word wrap set to 70 characters.</para> + </listitem> + + <listitem> + <para xml:lang="en">Tab stops set to 2.</para> + </listitem> + + <listitem> + <para xml:lang="en">Replace each group of 8 leading spaces with a + single tab.</para> + </listitem> + </itemizedlist> + + <para xml:lang="en">Specific editor configurations are listed in + <xref linkend="editor-config"/>.</para> + </step> + + <step> + <para xml:lang="en">Update the local working copy:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para xml:lang="en">Edit the documentation files that require changes. If a + file needs major changes, consult the mailing list for + input.</para> + + <para xml:lang="en">References to tag and entity usage can be found in + <xref linkend="xhtml-markup"/> and + <xref linkend="docbook-markup"/>.</para> + </step> + + <step> + <para xml:lang="en">After editing, check for problems by running:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para xml:lang="en">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 xml:lang="en"><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 xml:lang="en">When changes are complete and tested, generate a + <quote>diff file</quote>:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>cd ~/doc</userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + + <para xml:lang="en">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 xml:lang="en">Submit the diff file using the web-based + <link xlink:href="@@URL_RELPREFIX@@/support.html#gnats">Problem + Report</link> system. If using + the web form, enter a synopsis of + <emphasis>[patch] <replaceable>short description of + problem</replaceable></emphasis>. Select the category + <literal>docs</literal> and the class + <literal>doc-bug</literal>. In the body of the message, + enter a short description of the changes and any important + details about them. Use the + <guibutton>[ Browse... ]</guibutton> button to + attach the diff file.</para> + </step> + </procedure> + </sect1> +</chapter> + + +<!-- 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. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="tools"> + <title xml:lang="en">Tools</title> + + <para xml:lang="en">Several software tools are used to manage the FreeBSD + documentation and render it to different output formats. Some of + these tools are required and must be installed before working + through the examples in the following chapters. Some are + optional, adding capabilities or making the job of creating + documentation less demanding.</para> + + <sect1 xml:id="tools-required"> + <title xml:lang="en">Required Tools</title> + + <para xml:lang="en">Install + <package>textproc/docproj</package> from the + Ports Collection. This <emphasis>meta-port</emphasis> installs + all the applications required to do useful work with the FreeBSD + documentation. Some further notes on particular components are + given below.</para> + + <sect2> + <title xml:lang="en"><acronym>DTD</acronym>s and + <acronym>Entities</acronym></title> + + <para xml:lang="en">FreeBSD documentation uses several Document Type Definitions + (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym> + entities. These are all installed by the + <package>textproc/docproj</package> + port.</para> + + <variablelist> + <varlistentry> + <term xml:lang="en"><acronym>XHTML</acronym> <acronym>DTD</acronym> + (<package>textproc/xhtml</package>)</term> + + <listitem> + <para xml:lang="en"><acronym>XHTML</acronym> is the markup language of + choice for the World Wide Web, and is used throughout + the FreeBSD web site.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term> + + <listitem> + <para xml:lang="en">DocBook is designed for marking up technical + documentation. Most of the FreeBSD documentation is + written in DocBook.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en">ISO 8879 entities + (<package>textproc/iso8879</package>)</term> + + <listitem> + <para xml:lang="en">Character entities from the ISO 8879:1986 standard + used by many <acronym>DTD</acronym>s. Includes named + mathematical symbols, additional characters in the Latin + character set (accents, diacriticals, and so on), and + Greek symbols.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 xml:id="tools-optional"> + <title xml:lang="en">Optional Tools</title> + + <para xml:lang="en">These applications are not required, but can make working on + the documentation easier or add capabilities.</para> + + <sect2> + <title xml:lang="en">Software</title> + + <variablelist> + + <varlistentry> + <term xml:lang="en"><application>Vim</application> + (<package>editors/vim</package>)</term> + + <listitem> + <para xml:lang="en">A popular editor for working with + <acronym>XML</acronym> and derived documents, like + DocBook <acronym>XML</acronym>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:lang="en"><application>Emacs</application> or + <application>XEmacs</application> + (<package>editors/emacs</package> or + <package>editors/xemacs</package>)</term> + + <listitem> + <para xml:lang="en">Both of these editors include a special mode for + editing documents marked up according to an + <acronym>XML</acronym> <acronym>DTD</acronym>. This + mode includes commands to reduce the amount of typing + needed, and help reduce the possibility of + errors.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> +</chapter> + + +<!-- 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. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="working-copy"> + <title xml:lang="en">The Working Copy</title> + + <para xml:lang="en">The <emphasis>working copy</emphasis> is a copy of the FreeBSD + 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 xml:lang="en">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 xml:lang="en"><link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html"><application>Subversion</application></link> + is used to manage the FreeBSD documentation files. It is installed + by <package>textproc/docproj</package> as one of + the required applications.</para> + + <sect1 xml:id="working-copy-doc-and-src"> + <title xml:lang="en">Documentation and Manual Pages</title> + + <para xml:lang="en">FreeBSD 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 xml:lang="en">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 xml:lang="en">Choosing a Directory</title> + + <para xml:lang="en">FreeBSD 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 xml:lang="en">Checking Out a Copy</title> + + <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">A checkout of the source code to work on manual pages is + very similar:</para> + + <screen xml:lang="en"><prompt>%</prompt> <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-updating"> + <title xml:lang="en">Updating a Working Copy</title> + + <para xml:lang="en">The documents and files in the FreeBSD 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 FreeBSD + 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 xml:lang="en"><prompt>%</prompt> <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para xml:lang="en">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 xml:lang="en">Reverting Changes</title> + + <para xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 xml:id="working-copy-making-diff"> + <title xml:lang="en">Making a Diff</title> + + <para xml:lang="en">After edits to a file or group of files are completed, the + differences between the local working copy and the version on + the FreeBSD 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 xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + + <para xml:lang="en">Give the file a meaningful name that identifies the + contents. The example above is for spelling fixes to the whole + documentation tree.</para> + + <para xml:lang="en">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 FreeBSD + 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 xml:lang="en">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 xml:lang="en"><prompt>%</prompt> <userinput>cd <replaceable>~/doc</replaceable></userinput> +<prompt>%</prompt> <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 xml:lang="en"><application>Subversion</application> References</title> + + <para xml:lang="en">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> + + +<!-- 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. + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="structure"> + <title xml:lang="en">Documentation Directory Structure</title> + + <para xml:lang="en">Files and directories in the + <filename>doc/</filename> tree follow a + structure meant to:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">Make it easy to automate converting the document to other + formats.</para> + </listitem> + + <listitem> + <para xml:lang="en">Promote consistency between the different documentation + organizations, to make it easier to switch between working on + different documents.</para> + </listitem> + *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201510272223.t9RMNRfx088868>