Date: Mon, 17 Jun 2013 17:13:54 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41934 - head/en_US.ISO8859-1/books/fdp-primer/overview Message-ID: <201306171713.r5HHDspD068008@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Mon Jun 17 17:13:54 2013 New Revision: 41934 URL: http://svnweb.freebsd.org/changeset/doc/41934 Log: White space fix only, translators can ignore. Approved by: bcr (mentor) 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 Jun 17 15:47:47 2013 (r41933) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 17:13:54 2013 (r41934) @@ -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> + <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>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 + <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> - - <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> + <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> </step> </procedure> </sect1> - </chapter> + </chapter> \ No newline at end of file
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306171713.r5HHDspD068008>