aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml279
1 files changed, 119 insertions, 160 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
index 7694d17704..66eb8593f2 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -47,7 +47,7 @@
<acronym>FDP</acronym>. Willingness to contribute is the only
membership requirement.</para>
- <para>This primer shows the reader how to:</para>
+ <para>This primer shows how to:</para>
<itemizedlist>
<listitem>
@@ -64,8 +64,8 @@
</listitem>
<listitem>
- <para>Submit changes back for review and eventual inclusion in
- the &os; documentation.</para>
+ <para>Submit changes back for review and inclusion in the &os;
+ documentation.</para>
</listitem>
</itemizedlist>
@@ -110,185 +110,144 @@
<para>Translation teams are responsible for translating the
Handbook and web site into different languages. Manual pages
- are not translated.</para>
+ are not translated at present.</para>
<para>Documentation source for the &os; web site, Handbook, and
- <acronym>FAQ</acronym> is available in the Subversion
+ <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
- Subversion repository located at
+ source repository located at
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
<para>Documentation commit messages are visible with
- <application>svn</application>. Commit messages are also
+ <command>svn log</command>. Commit messages are also
archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para>
- <para>In addition, 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>
+ <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>
<sect1 id="overview-quick-start">
<title>Quick Start</title>
- <para>Here we describe the steps contributors must take before
- making changes to the <acronym>FDP</acronym>. New
- contributors will interact with other members of the &os;
- Documentation Team, which can assist in learning to use
- <acronym>XML</acronym> and the suggestions in
- <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>
+ <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
+ <ulink url="http://www.efnet.org/">EFnet</ulink>. These people
+ can help with questions or problems involving the
+ documentation.</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>
package or port. This meta-port installs all of the
- utilities needed by the <acronym>FDP</acronym>.</para>
+ software needed to edit and build &os; documentation.</para>
+ </step>
+
+ <step>
+ <para>Install a local working copy of the documentation from a
+ mirror of the &os; repository in
+ <filename class="directory">~/doc</filename> (see
+ <xref linkend="working-copy"/>).</para>
+
+ <screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>~/doc</replaceable></userinput></screen>
</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
- class="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>Locate the file to edit. Run
- <command>svn up</command> within the local working copy to
- make sure that it is up to date. Before making major
- changes to a file, discuss the proposed changes 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.
- References to the commonly used tags and entities can be
- found in <xref linkend="xhtml-markup"/> and
- <xref linkend="docbook-markup"/>.</para>
- </step>
-
- <step>
- <para>After edits are complete, 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 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
- <command>make</command> 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>[&nbsp;Browse...&nbsp;]</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 around 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>
+ <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 /usr/doc</userinput>
+&prompt.user; <userinput>svn diff > <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 class="directory">bsdinstall</filename> portion of
+ the Handbook.</para>
+ </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, 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>[&nbsp;Browse...&nbsp;]</guibutton> button to
+ attach the <literal>.diff.txt</literal>.</para>
+ </step>
+ </procedure>
+ </sect1>
+</chapter>