Date: Sun, 14 Jul 2013 13:03:00 +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: r42279 - head/en_US.ISO8859-1/books/fdp-primer/overview Message-ID: <201307141303.r6ED30C4030540@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Jul 14 13:03:00 2013 New Revision: 42279 URL: http://svnweb.freebsd.org/changeset/doc/42279 Log: Simplify and clarify. Reviewed by: dru 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 Sun Jul 14 08:24:02 2013 (r42278) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Sun Jul 14 13:03:00 2013 (r42279) @@ -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,7 +64,7 @@ </listitem> <listitem> - <para>Submit changes back for review and eventual inclusion in + <para>Submit changes back for review and inclusion in the &os; documentation.</para> </listitem> </itemizedlist> @@ -110,22 +110,22 @@ <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 + <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 @@ -136,8 +136,8 @@ <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 + <para>Some preparatory steps must be taken before + editing the &os; documentation. 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 @@ -148,8 +148,8 @@ <procedure> <step> - <para>Subscribe to the &a.doc;. Some members of the mailing - list also interact on the <literal>#bsddocs</literal> + <para>Subscribe to the &a.doc;. Some mailing list + members also interact on the <literal>#bsddocs</literal> <acronym>IRC</acronym> channel on <ulink url="http://www.efnet.org/">EFnet</ulink>.</para>; </step> @@ -158,26 +158,25 @@ <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. 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 + 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> <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>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 + <para>The editor to be used should be configured as follows:</para> <itemizedlist> @@ -194,38 +193,43 @@ single tab.</para> </listitem> </itemizedlist> + + <para> + Some specific editor configurations + are listed in <xref linkend="writing-style"/>.</para> </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 + <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>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 + <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 tags which surround the text or the entities that - represent that text in the <acronym>XML</acronym> file. + to the text, tags, and entities + 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 + <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 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> + <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 that are + fixable are resolved. If an error seems unsolvable, + ask for assistance on the &a.doc;.</para> </step> <step> @@ -234,34 +238,24 @@ <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 + 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 the + directory. This step is necessary to make sure that 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> + <para>After successfully completing the previous steps, generate + a <quote>diff file</quote> of the changes:</para> + + <screen>&prompt.user; <userinput>cd /usr/doc</userinput> +&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> - <screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + <para>Give the diff file a name that describes the contents. + In the example above, changes have been made to the + <filename class="directory">bsdinstall</filename> portion + of the Handbook.</para> </step> <step> @@ -276,15 +270,13 @@ 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> + attach the <literal>.diff.txt</literal>.</para> - <para>It is important to remember that the + <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 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 + 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307141303.r6ED30C4030540>