svn commit: r41932 - head/en_US.ISO8859-1/books/fdp-primer/overview
Warren Block
wblock at FreeBSD.org
Mon Jun 17 14:00:36 UTC 2013
Author: wblock
Date: Mon Jun 17 14:00:35 2013
New Revision: 41932
URL: http://svnweb.freebsd.org/changeset/doc/41932
Log:
Modernize the FDP introduction and Quick Start sections.
Submitted by: dru
Modified:
head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 08:10:55 2013 (r41931)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 14:00:35 2013 (r41932)
@@ -34,279 +34,254 @@
<chapter id="overview">
<title>Overview</title>
- <para>Welcome to the FreeBSD Documentation Project. Good quality
- documentation is very important to the success of FreeBSD, and the
- FreeBSD Documentation Project (FDP) is how a lot of that
- documentation is produced. Your contributions are very
+ <para>Welcome to the &os; Documentation Project (<acronym>FDP</acronym>). Quality
+ documentation is very important to the success of &os;. Your contributions are very
valuable.</para>
- <para>This document's main purpose is to clearly explain
- <emphasis>how the FDP is organized</emphasis>, <emphasis>how to
- write and submit documentation to the FDP</emphasis>, and
- <emphasis>how to effectively use the tools available to you when
- writing documentation</emphasis>.</para>
-
- <indexterm>
- <primary>Membership</primary>
- </indexterm>
- <para>Everyone is welcome to join the FDP. There is no minimum
- membership requirement, no quota of documentation you need to
- produce per month. All you need to do is subscribe to the
- &a.doc;.</para>
+ <para>This document's main purpose is to explain
+ 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>. There is no membership requirement or minimum quota of
+ documentation that needs to be produced.</para>
<para>After you have finished reading this document you
- should:</para>
+ will be able to:</para>
<itemizedlist>
<listitem>
- <para>Know which documentation is maintained by the FDP.</para>
+ <para>Identify which parts of &os; are maintained by the <acronym>FDP</acronym>.</para>
</listitem>
<listitem>
- <para>Be able to read and understand the XML source code for
- the documentation maintained by the FDP.</para>
+ <para>Install the required tools and files.</para>
</listitem>
<listitem>
- <para>Be able to make changes to the documentation.</para>
+ <para>Make changes to the documentation.</para>
</listitem>
<listitem>
- <para>Be able to submit your changes back for review and
- eventual inclusion in the FreeBSD documentation.</para>
+ <para>Submit changes back for review and
+ eventual inclusion in the &os; documentation.</para>
</listitem>
</itemizedlist>
<sect1 id="overview-doc">
- <title>The FreeBSD Documentation Set</title>
+ <title>The &os; Documentation Set</title>
- <para>The FDP is responsible for four categories of FreeBSD
+ <para>The <acronym>FDP</acronym> is responsible for four categories of &os;
documentation.</para>
- <variablelist>
- <varlistentry>
- <term>Manual pages</term>
-
- <listitem>
- <para>The English language system manual pages are not
- written by the FDP, as they are part of the base system.
- However, the FDP can (and has) re-worded parts of existing
- manual pages to make them clearer, or to correct
- inaccuracies.</para>
-
- <para>The translation teams are responsible for translating
- the system manual pages into different languages. These
- translations are kept within the FDP.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FAQ</term>
-
- <listitem>
- <para>The FAQ aims to address (in short question and answer
- format) questions that are asked, or should be asked, on
- the various mailing lists and newsgroups devoted to
- FreeBSD. The format does not permit long and
- comprehensive answers.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Handbook</term>
-
- <listitem>
- <para>The Handbook aims to be the comprehensive on-line
- resource and reference for FreeBSD users.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Web site</term>
-
- <listitem>
- <para>This is the main FreeBSD presence on the World Wide
- Web, visible at <ulink
- url="&url.base;/index.html">http://www.FreeBSD.org/</ulink>
- and many mirrors around the world. The web site is many
- people's first exposure to FreeBSD.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The documentation for the web site, &os; Handbook, and FAQ
- are available in the <literal>doc/</literal> Subversion
- repository, which is located at
- <literal>https://svn.FreeBSD.org/doc/</literal>.</para>
-
- <para>Manual pages are available in the <literal>src/</literal>
- Subversion repository, which is available at
- <literal>https://svn.FreeBSD.org/base/</literal>.</para>
-
- <para>This means that the logs of changes to these
- files are visible to anyone, and anyone can use
- <application>svn</application> to view the changes.</para>
-
- <para>In addition, many people have written tutorials or other web
- sites relating to FreeBSD. Some of these are stored in the
- Subversion repository as well (where the author has agreed to
- this). In other cases the author has decided to keep his
- documentation separate from the main FreeBSD repository. The
- FDP endeavors to provide links to as much of this documentation
- as possible.</para>
- </sect1>
-
- <sect1 id="overview-before">
- <title>Before You Start</title>
+ <itemizedlist>
- <para>This document assumes that you already know:</para>
+ <listitem>
+ <para><emphasis>Handbook</emphasis>: The Handbook is the comprehensive online
+ resource and reference for &os; users.</para>
+ </listitem>
+
- <itemizedlist>
<listitem>
- <para>How to maintain an up-to-date local copy of the FreeBSD
- documentation by maintaining a local copy of the FreeBSD
- Subversion repository using
- <application>svn</application>.</para>
+ <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>How to download and install new software using either
- the FreeBSD Ports system or &man.pkg.add.1;.</para>
- </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 <ulink
+ url="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</ulink>
+ 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.</para>
+
+ <para>Documentation source for the &os; web site, Handbook, and <acronym>FAQ</acronym>
+ is available in the Subversion
+ repository at
+ <literal>https://svn.FreeBSD.org/doc/</literal>.</para>
+
+ <para>Source for manual pages is available in a separate
+ Subversion repository located at
+ <literal>https://svn.FreeBSD.org/base/</literal>.</para>
+
+ <para>The commit messages to the <acronym>FDP</acronym>
+ are visible to anyone using
+ <application>svn</application>. They are also archived at
+ &a.svn-doc-all.url;.</para>
+
+ <para>In addition, many people have written tutorials or how-to
+ articles about &os;. Some are stored in the
+ <acronym>FDP</acronym>. In other
+ cases, the author has decided to keep the documentation separate
+ from the <acronym>FDP</acronym>. The
+ <acronym>FDP</acronym> endeavors to provide links to as much of this documentation
+ as possible.</para>
</sect1>
<sect1 id="overview-quick-start">
<title>Quick Start</title>
- <para>If you just want to get going, and feel confident you can
- pick things up as you go along, follow these
- instructions.</para>
+ <para>This section outlines the steps which new contributors need
+ to follow before they can make changes to the <acronym>FDP</acronym>. New contributors
+ will interact with other members of
+ the &os; Documentation Team which can assist in learning
+ how to use <acronym>XML</acronym> and the <xref
+ linkend="writing-style-guide"/>. If
+ a new user contributes regularly, a Documentation Team member may be
+ assigned as a mentor to guide the user through the process from
+ contributor to documentation committer.</para>
<procedure>
<step>
+ <para>
+ Subscribe to the &a.doc;. Some members of the mailing
+ list also interact on the <literal>#bsddocs</literal> <acronym>IRC</acronym>
+ channel on <ulink
+ url="http://www.efnet.org/">EFnet</ulink>.</para>
+ </step>
+
+ <step>
<para>Install the
<filename role="package">textproc/docproj</filename>
- meta-port.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
-&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
- </step>
-
- <step>
- <para>Get a local copy of the FreeBSD <filename>doc</filename>
- tree using <application>svn</application>.</para>
-
- <para>If network bandwidth or local drive space is a concern,
- then at minimum, the <filename>head/share</filename> and
- <filename>head/<replaceable>language</replaceable>/share</filename>
- directories will need to be checked out. For
- example:</para>
-
- <screen>&prompt.user; <userinput>mkdir -p head/share</userinput>
-&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput>
-&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/share head/share</userinput>
-&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen>
-
- <para>If you have plenty of disk space then you could check
- out everything.</para>
-
- <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head head</userinput></screen>
-
- <note>
- <para><ulink
- url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>
- is a public <literal>SVN</literal> server.
- Select the closest mirror and verify the mirror server
- certificate from the list of <ulink
- url="&url.books.handbook;/svn-mirrors.html">Subversion
- mirror sites</ulink>.</para>
- </note>
+ package or port. This meta-port
+ installs all of the utilities needed by the <acronym>FDP</acronym>.</para>
+ </step>
+
+ <step>
+ <para>Install a local working copy of the documentation
+ from a mirror of the &os; repository. For the fastest
+ download, pick the nearest mirror from the list of <ulink
+ url="&url.books.handbook;#svn-mirrors">Subversion mirror sites</ulink>.
+ If <filename role="directory">/usr/doc</filename> already
+ exists, move or delete it first to prevent file
+ conflicts.</para>
+
+ <screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen>
+ </step>
+
+ <step>
+ <para>Before making any documentation edits, configure your
+ editor to conform to <acronym>FDP</acronym> standards. How to do so varies
+ by editor. Some editor configurations are listed in <xref
+ linkend="writing-style"/>. The editor
+ should be configured as follows:</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>
</step>
<step>
- <para>If you are preparing a change to an existing book or
- article, check it out of the repository as necessary. If
- you are planning on contributing a new book or article then
- use an existing one as a guide.</para>
-
- <para>For example, if you want to contribute a new article
- about setting up a VPN between FreeBSD and Windows 2000 you
- might do the following.</para>
+ <para>Determine which file to edit. Run <command>svn up</command> within the
+ local working copy to make sure that it is
+ current. Before making major
+ changes to a file, discuss the proposed changes first with
+ the &a.doc;.</para>
+
+ <para>When making edits, determine which
+ tags and entities are needed to achieve the desired
+ formatting. One way to learn is to compare some text in
+ the <acronym>HTML</acronym> formatted version of the document to the tags
+ which surround the text or the entities that represent
+ that text in the <acronym>XML</acronym> file. A
+ reference to the commonly used tags and entities can be
+ found in <xref linkend="xml-markup"/>.</para>
+ </step>
- <procedure>
<step>
- <para>Check out the <filename>articles</filename>
- directory.</para>
+ <para>Once the edits are complete, check for problems by running:</para>
- <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/articles</userinput></screen>
- </step>
+ <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
- <step>
- <para>Copy an existing article to use as a template. In
- this case, you have decided that your new article
- belongs in a directory called
- <filename>vpn-w2k</filename>.</para>
-
- <screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput>
-&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen>
- </step>
- </procedure>
-
- <para>If you wanted to edit an existing document, such as the
- FAQ, which is in
- <filename>head/en_US.ISO8859-1/books/faq</filename> you
- would check it out of the repository like this.</para>
-
- <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>
- </step>
-
- <step>
- <para>Edit the <filename>.xml</filename> files using your
- editor of choice.</para>
- </step>
-
- <step>
- <para>Test the markup using the <maketarget>lint</maketarget>
- target. This will quickly find any errors in the document
- without actually performing the time-consuming
- transformation.</para>
-
- <screen>&prompt.user; <userinput>make lint</userinput></screen>
-
- <para>When you are ready to actually build the document, you
- may specify a single format or a list of formats in the
- <varname>FORMATS</varname> variable. Currently,
- <literal>html</literal>, <literal>html-split</literal>,
- <literal>txt</literal>, <literal>ps</literal>,
- <literal>pdf</literal>, and <literal>rtf</literal> are
- supported. The most up to date list of supported formats is
- listed at the top of the
- <filename>head/share/mk/doc.docbook.mk</filename> file.
- Make sure to use quotes around the list of formats when you
- build more than one format with a single command.</para>
-
- <para>For example, to convert the document to
- <literal>html</literal> only, you would use:</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
-
- <para>But when you want to convert the document to both
- <literal>html</literal> and <literal>txt</literal> format,
- you could use either two separate &man.make.1; runs,
- with:</para>
-
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput>
-&prompt.user; <userinput>make FORMATS=txt</userinput></screen>
-
- <para>or, you can do it in one command:</para>
-
- <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
- </step>
-
- <step>
- <para>Submit your changes using &man.send-pr.1;.</para>
- </step>
- </procedure>
- </sect1>
-</chapter>
+ <para>While reviewing the output, edit the file to fix the
+ listed tab errors, spelling mistakes, and improper
+ grammar. Save the changes and rerun this command to find
+ any remaining problems. Repeat until all of the errors that
+ you deem fixable are resolved. If you get stuck trying to
+ fix errors, ask for assistance on the &a.doc;.</para>
+ </step>
+
+ <step>
+ <para><emphasis>Always</emphasis> build-test changes before submitting them. By
+ default, typing <userinput>make</userinput> in the
+ top-level directory of the type of documentation being
+ edited will generate that documentation in
+ split HTML format. For example, to build the English
+ version of the Handbook, type <userinput>make</userinput>
+ in the
+ <filename>en_US.ISO8859-1/books/handbook/</filename>
+ directory. This step is necessary to make sure that the
+ edits do not break the build.</para>
+ </step>
+
+ <step>
+ <para>In order to build the output in other formats,
+ other <application>make</application> targets are defined
+ in <filename>head/share/mk/doc.docbook.mk</filename>.
+ Use quotes around the list of formats when
+ building more than one format with a single
+ command.</para>
+
+ <para>For example, to convert the document to both
+ <literal>.html</literal> and <literal>.txt</literal>, use
+ this command:</para>
+
+ <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
+
+ <para>Once these steps are successfully completed,
+ generate a <quote>diff file</quote> of the changes. While in
+ <filename class="directory">/usr/doc</filename>, run this
+ command, replacing <replaceable>bsdinstall</replaceable>
+ with the name of the directory containing the edits:</para>
+
+ <screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
+ </step>
+
+ <step>
+ <para>Submit the diff file using the web-based <ulink
+ url="&url.base;/support.html#gnats">Problem Report</ulink>
+ system or with &man.send-pr.1;. If using the web form,
+ input 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>. The body of the
+ message should contain a short description of the edits
+ and any important discussion points. Use the <guibutton>[ Browse... ]</guibutton> button to attach the
+ <literal>.diff.txt</literal> file and enter the captcha
+ phrase.</para>
+
+ <para>It is important to remember that the <acronym>FDP</acronym>
+ is comprised of volunteers who review
+ edits in their spare time and who live in different time
+ zones across the globe. It takes time to review edits and
+ to either commit them or respond if additional edits are
+ required. If you do not receive a response in a reasonable
+ amount of time, send a follow-up email to the &a.doc; and ask if anyone
+ has had a chance to review the patch or if additional
+ information is required.</para>
+ </step>
+ </procedure>
+ </sect1>
+ </chapter>
More information about the svn-doc-all
mailing list