Date: Mon, 22 Jul 2013 21:00:03 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42383 - head/en_US.ISO8859-1/books/fdp-primer/overview Message-ID: <201307222100.r6ML03ib016809@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon Jul 22 21:00:03 2013 New Revision: 42383 URL: http://svnweb.freebsd.org/changeset/doc/42383 Log: Simplify the quick start a bit more by referring to later sections. Use ~/doc for the working copy to be consistent with later sections. 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 Jul 22 20:27:54 2013 (r42382) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jul 22 21:00:03 2013 (r42383) @@ -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>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 + <para>Update the local working copy:</para> + + <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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307222100.r6ML03ib016809>