Index: head/en_US.ISO8859-1/books/fdp-primer/book.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/book.xml	(revision 54255)
+++ head/en_US.ISO8859-1/books/fdp-primer/book.xml	(revision 54256)
@@ -1,278 +1,281 @@
 <?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" -->
 ]>
 <!-- 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.
 
 -->
 <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>
 
     <author>
       <orgname>The FreeBSD Documentation Project</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>
       <year>2015</year>
       <year>2016</year>
       <year>2017</year>
+      <year>2018</year>
+      <year>2019</year>
+      <year>2020</year>
       <holder role="mailto:doceng@FreeBSD.org">DocEng</holder>
     </copyright>
 
     <pubdate />
 
     <releaseinfo />
 
     &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>This is a work in progress.  Corrections and
 	additions are always welcome.</para>
     </abstract>
   </info>
 
   <preface xml:id="preface">
     <title>Preface</title>
 
     <sect1 xml:id="preface-prompts">
       <title>Shell Prompts</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>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>User</entry>
 	      <entry>Prompt</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>Normal user</entry>
 	      <entry>&prompt.user;</entry>
 	    </row>
 
 	    <row>
 	      <entry><systemitem
 		  class="username">root</systemitem></entry>
 	      <entry>&prompt.root;</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect1>
 
     <sect1 xml:id="preface-conventions">
       <title>Typographic Conventions</title>
 
       <para>This table describes the typographic conventions
 	used in this book.</para>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Meaning</entry>
 	      <entry>Examples</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>The names of commands.</entry>
 	      <entry>Use <command>ls -l</command> to list all
 		files.</entry>
 	    </row>
 
 	    <row>
 	      <entry>The names of files.</entry>
 	      <entry>Edit <filename>.login</filename>.</entry>
 	    </row>
 
 	    <row>
 	      <entry>On-screen computer output.</entry>
 	      <entry><screen>You have mail.</screen></entry>
 	    </row>
 
 	    <row>
 	      <entry>What the user types, contrasted with on-screen
 		computer output.</entry>
 
 	      <entry><screen>&prompt.user; <userinput>date +"The time is %H:%M"</userinput>
 The time is 09:18</screen></entry>
 	    </row>
 
 	    <row>
 	      <entry>Manual page references.</entry>
 	      <entry>Use &man.su.1; to change user identity.</entry>
 	    </row>
 
 	    <row>
 	      <entry>User and group names.</entry>
 	      <entry>Only <systemitem
 		  class="username">root</systemitem> can do
 		this.</entry>
 	    </row>
 
 	    <row>
 	      <entry>Emphasis.</entry>
 	      <entry>The user <emphasis>must</emphasis> do
 		this.</entry>
 	    </row>
 
 	    <row>
 	      <entry>Text that the user is expected to replace with
 		the actual text.</entry>
 
 	      <entry>To search for a keyword in the manual pages, type
 		<command>man -k
 		  <replaceable>keyword</replaceable></command></entry>
 	    </row>
 
 	    <row>
 	      <entry>Environment variables.</entry>
 	      <entry><envar>$HOME</envar> is set to the user's home
 		directory.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect1>
 
     <sect1 xml:id="preface-notes">
       <title>Notes, Tips, Important Information, Warnings, and
 	Examples</title>
 
       <para>Notes, warnings, and examples appear within the
 	text.</para>
 
       <note>
 	<para>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
 	  helpful to the user, like showing an easier way to do
 	  something.</para>
       </tip>
 
       <important>
 	<para>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
 	  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
 	  as the inadvertent deletion of important files.</para>
       </warning>
 
       <example>
 	<title>A Sample Example</title>
 
 	<para>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>
 
       <para>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.manpages;
   &chap.writing-style;
   &chap.editor-config;
   &chap.see-also;
 
   &app.examples;
 
   <index/>
 </book>
Index: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml	(revision 54255)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml	(revision 54256)
@@ -1,264 +1,273 @@
 <?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>Optional: to generate PDF documentation, install the
+	  <package>textproc/fop</package> package as it is not
+	  installed by default by <package>textproc/docproj</package>.
+	</para>
+
+	<screen>&prompt.root; <userinput>pkg install fop</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 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 &gt; <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>[&nbsp;Add an attachment&nbsp;]</guibutton>
 	  button to attach the diff file.  Finally, use the
 	  <guibutton>[&nbsp;Submit Bug&nbsp;]</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>