White space fix only, translators can ignore.
Approved by: bcr (mentor)
This commit is contained in:
Dru Lavigne
parent
fda0407257
commit
355fe0ff85
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=41934
1 changed files with 139 additions and 132 deletions
|
|
@ -34,24 +34,27 @@
|
|||
<chapter id="overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Welcome to the &os; Documentation Project (<acronym>FDP</acronym>). Quality
|
||||
documentation is very important to the success of &os;. 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 explain
|
||||
how the <acronym>FDP</acronym> is organized, how to
|
||||
write and submit documentation, and
|
||||
how to effectively use the available tools.</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>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
|
||||
will be able to:</para>
|
||||
<para>After you have finished reading this document you will be
|
||||
able to:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Identify which parts of &os; are maintained by the <acronym>FDP</acronym>.</para>
|
||||
<para>Identify which parts of &os; are maintained by the
|
||||
<acronym>FDP</acronym>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -63,55 +66,57 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Submit changes back for review and
|
||||
eventual inclusion in the &os; documentation.</para>
|
||||
<para>Submit changes back for review and eventual inclusion in
|
||||
the &os; documentation.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<sect1 id="overview-doc">
|
||||
<title>The &os; Documentation Set</title>
|
||||
|
||||
<para>The <acronym>FDP</acronym> is responsible for four categories of &os;
|
||||
documentation.</para>
|
||||
<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>
|
||||
<para><emphasis>Handbook</emphasis>: The Handbook is the
|
||||
comprehensive online resource and reference for &os;
|
||||
users.</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
|
||||
<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>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Web site</emphasis>: This is the main &os; presence on the
|
||||
web, visible at <ulink
|
||||
<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>
|
||||
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
|
||||
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>
|
||||
|
||||
|
|
@ -120,65 +125,63 @@
|
|||
<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>
|
||||
are visible to anyone usingv<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>
|
||||
<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>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>
|
||||
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
|
||||
<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>
|
||||
|
||||
<step>
|
||||
<step>
|
||||
<para>Install the
|
||||
<filename role="package">textproc/docproj</filename>
|
||||
package or port. This meta-port
|
||||
installs all of the utilities needed by the <acronym>FDP</acronym>.</para>
|
||||
</step>
|
||||
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;/subversion-mirrors.html">Subversion mirror sites</ulink>.
|
||||
If <filename role="directory">/usr/doc</filename> already
|
||||
exists, move or delete it first to prevent file
|
||||
conflicts.</para>
|
||||
url="&url.books.handbook;/subversion-mirrors.html">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
|
||||
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>
|
||||
|
|
@ -192,96 +195,100 @@
|
|||
single tab.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<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
|
||||
<step>
|
||||
<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
|
||||
<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>Once the edits are complete, check for problems by running:</para>
|
||||
<step>
|
||||
<para>Once the edits are complete, check for problems by
|
||||
running:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
|
||||
|
||||
<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>
|
||||
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
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue