Date: Mon, 17 Jun 2013 14:00:35 +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: r41932 - head/en_US.ISO8859-1/books/fdp-primer/overview Message-ID: <201306171400.r5HE0ZSu003547@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon Jun 17 14:00:35 2013 New Revision: 41932 URL: http://svnweb.freebsd.org/changeset/doc/41932 Log: Modernize the FDP introduction and Quick Start sections. Submitted 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 Mon Jun 17 08:10:55 2013 (r41931) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 14:00:35 2013 (r41932) @@ -34,279 +34,254 @@ <chapter id="overview"> <title>Overview</title> - <para>Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that - documentation is produced. 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 clearly explain - <emphasis>how the FDP is organized</emphasis>, <emphasis>how to - write and submit documentation to the FDP</emphasis>, and - <emphasis>how to effectively use the tools available to you when - writing documentation</emphasis>.</para> - - <indexterm> - <primary>Membership</primary> - </indexterm> - <para>Everyone is welcome to join the FDP. There is no minimum - membership requirement, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - &a.doc;.</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>After you have finished reading this document you - should:</para> + will be able to:</para> <itemizedlist> <listitem> - <para>Know which documentation is maintained by the FDP.</para> + <para>Identify which parts of &os; are maintained by the <acronym>FDP</acronym>.</para> </listitem> <listitem> - <para>Be able to read and understand the XML source code for - the documentation maintained by the FDP.</para> + <para>Install the required tools and files.</para> </listitem> <listitem> - <para>Be able to make changes to the documentation.</para> + <para>Make changes to the documentation.</para> </listitem> <listitem> - <para>Be able to submit your changes back for review and - eventual inclusion in the FreeBSD documentation.</para> + <para>Submit changes back for review and + eventual inclusion in the &os; documentation.</para> </listitem> </itemizedlist> <sect1 id="overview-doc"> - <title>The FreeBSD Documentation Set</title> + <title>The &os; Documentation Set</title> - <para>The FDP is responsible for four categories of FreeBSD + <para>The <acronym>FDP</acronym> is responsible for four categories of &os; documentation.</para> - <variablelist> - <varlistentry> - <term>Manual pages</term> - - <listitem> - <para>The English language system manual pages are not - written by the FDP, as they are part of the base system. - However, the FDP can (and has) re-worded parts of existing - manual pages to make them clearer, or to correct - inaccuracies.</para> - - <para>The translation teams are responsible for translating - the system manual pages into different languages. These - translations are kept within the FDP.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ</term> - - <listitem> - <para>The FAQ aims to address (in short question and answer - format) questions that are asked, or should be asked, on - the various mailing lists and newsgroups devoted to - FreeBSD. The format does not permit long and - comprehensive answers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>The Handbook aims to be the comprehensive on-line - resource and reference for FreeBSD users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web site</term> - - <listitem> - <para>This is the main FreeBSD presence on the World Wide - Web, visible at <ulink - url="&url.base;/index.html">http://www.FreeBSD.org/</ulink>; - and many mirrors around the world. The web site is many - people's first exposure to FreeBSD.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The documentation for the web site, &os; Handbook, and FAQ - are available in the <literal>doc/</literal> Subversion - repository, which is located at - <literal>https://svn.FreeBSD.org/doc/</literal>.</para>; - - <para>Manual pages are available in the <literal>src/</literal> - Subversion repository, which is available at - <literal>https://svn.FreeBSD.org/base/</literal>.</para>; - - <para>This means that the logs of changes to these - files are visible to anyone, and anyone can use - <application>svn</application> to view the changes.</para> - - <para>In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the - Subversion repository as well (where the author has agreed to - this). In other cases the author has decided to keep his - documentation separate from the main FreeBSD repository. The - FDP endeavors to provide links to as much of this documentation - as possible.</para> - </sect1> - - <sect1 id="overview-before"> - <title>Before You Start</title> + <itemizedlist> - <para>This document assumes that you already know:</para> + <listitem> + <para><emphasis>Handbook</emphasis>: The Handbook is the comprehensive online + resource and reference for &os; users.</para> + </listitem> + - <itemizedlist> <listitem> - <para>How to maintain an up-to-date local copy of the FreeBSD - documentation by maintaining a local copy of the FreeBSD - Subversion repository using - <application>svn</application>.</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>How to download and install new software using either - the FreeBSD Ports system or &man.pkg.add.1;.</para> - </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 + inaccuracies.</para> + </listitem> + + <listitem> + <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> </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 + repository at + <literal>https://svn.FreeBSD.org/doc/</literal>.</para>; + + <para>Source for manual pages is available in a separate + Subversion repository located at + <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> + + <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> </sect1> <sect1 id="overview-quick-start"> <title>Quick Start</title> - <para>If you just want to get going, and feel confident you can - pick things up as you go along, follow these - instructions.</para> + <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> <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> - meta-port.</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput> -&prompt.root; <userinput>make JADETEX=no install</userinput></screen> - </step> - - <step> - <para>Get a local copy of the FreeBSD <filename>doc</filename> - tree using <application>svn</application>.</para> - - <para>If network bandwidth or local drive space is a concern, - then at minimum, the <filename>head/share</filename> and - <filename>head/<replaceable>language</replaceable>/share</filename> - directories will need to be checked out. For - example:</para> - - <screen>&prompt.user; <userinput>mkdir -p head/share</userinput> -&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput> -&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/share head/share</userinput> -&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen> - - <para>If you have plenty of disk space then you could check - out everything.</para> - - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head head</userinput></screen> - - <note> - <para><ulink - url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>; - is a public <literal>SVN</literal> server. - Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> - </note> + 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;#svn-mirrors">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 + 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>If you are preparing a change to an existing book or - article, check it out of the repository as necessary. If - you are planning on contributing a new book or article then - use an existing one as a guide.</para> - - <para>For example, if you want to contribute a new article - about setting up a VPN between FreeBSD and Windows 2000 you - might do the following.</para> + <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 + found in <xref linkend="xml-markup"/>.</para> + </step> - <procedure> <step> - <para>Check out the <filename>articles</filename> - directory.</para> + <para>Once the edits are complete, check for problems by running:</para> - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/articles</userinput></screen>; - </step> + <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen> - <step> - <para>Copy an existing article to use as a template. In - this case, you have decided that your new article - belongs in a directory called - <filename>vpn-w2k</filename>.</para> - - <screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput> -&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen> - </step> - </procedure> - - <para>If you wanted to edit an existing document, such as the - FAQ, which is in - <filename>head/en_US.ISO8859-1/books/faq</filename> you - would check it out of the repository like this.</para> - - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>; - </step> - - <step> - <para>Edit the <filename>.xml</filename> files using your - editor of choice.</para> - </step> - - <step> - <para>Test the markup using the <maketarget>lint</maketarget> - target. This will quickly find any errors in the document - without actually performing the time-consuming - transformation.</para> - - <screen>&prompt.user; <userinput>make lint</userinput></screen> - - <para>When you are ready to actually build the document, you - may specify a single format or a list of formats in the - <varname>FORMATS</varname> variable. Currently, - <literal>html</literal>, <literal>html-split</literal>, - <literal>txt</literal>, <literal>ps</literal>, - <literal>pdf</literal>, and <literal>rtf</literal> are - supported. The most up to date list of supported formats is - listed at the top of the - <filename>head/share/mk/doc.docbook.mk</filename> file. - Make sure to use quotes around the list of formats when you - build more than one format with a single command.</para> - - <para>For example, to convert the document to - <literal>html</literal> only, you would use:</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen> - - <para>But when you want to convert the document to both - <literal>html</literal> and <literal>txt</literal> format, - you could use either two separate &man.make.1; runs, - with:</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput> -&prompt.user; <userinput>make FORMATS=txt</userinput></screen> - - <para>or, you can do it in one command:</para> - - <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen> - </step> - - <step> - <para>Submit your changes using &man.send-pr.1;.</para> - </step> - </procedure> - </sect1> -</chapter> + <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> + </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 + <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 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306171400.r5HE0ZSu003547>