diff options
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.xml | 279 |
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>[ 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 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>[ Browse... ]</guibutton> button to + attach the <literal>.diff.txt</literal>.</para> + </step> + </procedure> + </sect1> +</chapter> |