os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Modernize the FDP introduction and Quick Start sections.

Browse source 
Submitted by:	dru
This commit is contained in:
Warren Block 2013-06-17 14:00:35 +00:00
parent c7cb17bb5c
commit bb120bcacd
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=41932
1 changed files with 190 additions and 215 deletions

405
en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
View file

@ -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>
<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>
<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>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>
<itemizedlist>
<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>
<listitem>
<para><emphasis>Handbook</emphasis>: The Handbook is the comprehensive online
resource and reference for &os; users.</para>
</listitem>
<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>
<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>
<varlistentry>
<term>FAQ</term>
<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>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>
<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>
<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
<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>Manual pages are available in the <literal>src/</literal>
Subversion repository, which is available at
<para>Source for manual pages is available in a separate
Subversion repository located 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>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 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
<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-before">
<title>Before You Start</title>
<para>This document assumes that you already know:</para>
<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>
</listitem>
<listitem>
<para>How to download and install new software using either
the FreeBSD Ports system or &man.pkg.add.1;.</para>
</listitem>
</itemizedlist>
</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>
package or port. This meta-port
installs all of the utilities needed by the <acronym>FDP</acronym>.</para>
</step>
<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
<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>Get a local copy of the FreeBSD <filename>doc</filename>
tree using <application>svn</application>.</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>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>
</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>
<procedure>
<step>
<para>Check out the <filename>articles</filename>
directory.</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>
<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>
<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>
<para>Once the edits are complete, check for problems by running:</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>
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
<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>
<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>
<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>
<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>Edit the <filename>.xml</filename> files using your
editor of choice.</para>
</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>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>
<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>[&nbsp;Browse...&nbsp;]</guibutton> button to attach the
<literal>.diff.txt</literal> file and enter the captcha
phrase.</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>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>