Simplify the quick start a bit more by referring to later sections. Use
~/doc for the working copy to be consistent with later sections.
This commit is contained in:
Warren Block
parent
0af71ffe4f
commit
c80d7d92b6
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42383
1 changed files with 24 additions and 41 deletions
|
|
@ -163,21 +163,14 @@
|
|||
|
||||
<step>
|
||||
<para>Install a local working copy of the documentation
|
||||
from a mirror of the &os; repository. If <filename
|
||||
class="directory">/usr/doc</filename> already exists, move
|
||||
or delete it first to prevent file conflicts.</para>
|
||||
from a mirror of the &os; repository (see <xref linkend="working-copy"/>) in <filename class="directory">~/doc</filename>.</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen>
|
||||
|
||||
<para>For the fastest download, pick the nearest mirror from
|
||||
the list of <ulink
|
||||
url="&url.books.handbook;/subversion-mirrors.html">Subversion
|
||||
mirror sites</ulink>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>The editor to be used should be configured as
|
||||
follows:</para>
|
||||
<para>Configure the text editor:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -195,22 +188,22 @@
|
|||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
Some specific editor configurations
|
||||
are listed in <xref linkend="writing-style"/>.</para>
|
||||
Specific editor configurations
|
||||
are listed in <xref linkend="editor-config"/>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Run <command>svn up</command> to update the local
|
||||
working copy. Edit the documentation files that need
|
||||
changes. Before making major changes to a file, ask for
|
||||
input on the &a.doc;.</para>
|
||||
<para>Update the local working copy:</para>
|
||||
|
||||
<para>To learn which tags and entities are needed to achieve
|
||||
the desired formatting, compare some text in the
|
||||
<acronym>HTML</acronym> formatted version of the document
|
||||
to the text, tags, and entities in the
|
||||
<acronym>XML</acronym> file. References to the commonly
|
||||
used tags and entities can be found in
|
||||
<screen>&prompt.user; <userinput>svn up ~/doc</userinput></screen>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Edit the documentation files that require
|
||||
changes. If a file needs major changes, consult the
|
||||
&a.doc; 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>
|
||||
|
|
@ -230,25 +223,24 @@
|
|||
|
||||
<step>
|
||||
<para><emphasis>Always</emphasis> build-test changes before
|
||||
submitting them. By default, typing
|
||||
submitting them. Running
|
||||
<userinput>make</userinput> in the top-level directory of
|
||||
the type of documentation being edited will generate that
|
||||
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>, type <command>make</command> in
|
||||
the <filename>en_US.ISO8859-1/books/handbook/</filename>
|
||||
directory. This step is necessary to make sure that edits
|
||||
do not break the build.</para>
|
||||
directory.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>After successfully completing the previous steps,
|
||||
generate a <quote>diff file</quote> of the changes:</para>
|
||||
<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 name that describes the contents.
|
||||
<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>
|
||||
|
|
@ -258,24 +250,15 @@
|
|||
<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]
|
||||
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>. The body of the message
|
||||
should contain a short description of the edits and any
|
||||
important discussion points. Use the
|
||||
<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>[ Browse... ]</guibutton> button to
|
||||
attach the <literal>.diff.txt</literal>.</para>
|
||||
|
||||
<para>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 can
|
||||
take some time to review changes. If a response is not
|
||||
received 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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue