Date: Wed, 9 Jan 2013 13:08:58 -0800 (PST) From: Dru Lavigne <dru.lavigne@att.net> To: freebsd-doc@freebsd.org Subject: [patch] Quick Start Guide to FDP Primer Message-ID: <1357765738.95165.YahooMailClassic@web184902.mail.gq1.yahoo.com>
index | next in thread | raw e-mail
[-- Attachment #1 --]
Attached is the svn diff for proposed changes to the Quick Start Guide of the FDP Primer. Igor is mostly happy, except for a few tab indents I can't figure out.
Note that this patch incorporates the information in the Tools section into the Overview section. As a new user I got bitten by following the Quick Start only to find that it did not mention all of the needed tools until the next chapter. Tools was also quite redundant in the docproj/jadetex discussion, none of which was mentioned in the earlier Quick Start section. If accepted, the svn diff shows the removal of Tools.
I tried to include in the Quick Start all of the info I could think of to get a new user started and ready to go. The content should be reviewed to make sure it isn't missing anything useful or suggests something which isn't standard practice.
Thanks to bcr@ for his patience in getting my head wrapped around indentation.
Cheers,
Dru
[-- Attachment #2 --]
Index: tools/chapter.xml
===================================================================
--- tools/chapter.xml (revision 40548)
+++ tools/chapter.xml (working copy)
@@ -1,289 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
-<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
-
- Redistribution and use in source (SGML DocBook) and 'compiled' forms
- (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
- modification, are permitted provided that the following conditions
- are met:
-
- 1. Redistributions of source code (SGML DocBook) must retain the above
- copyright notice, this list of conditions and the following
- disclaimer as the first lines of this file unmodified.
-
- 2. Redistributions in compiled form (transformed to other DTDs,
- converted to PDF, PostScript, RTF and other formats) must reproduce
- the above copyright notice, this list of conditions and the
- following disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
- $FreeBSD$
--->
-
-<chapter id="tools">
- <title>Tools</title>
-
- <para>The FDP uses a number of different software tools to help
- manage the FreeBSD documentation, convert it to different output
- formats, and so on. You will need to use these tools yourself if
- you are to work with the FreeBSD documentation.</para>
-
- <para>All these tools are available as FreeBSD Ports and Packages,
- greatly simplifying the work you have to do to install
- them.</para>
-
- <para>You will need to install these tools before you work through
- any of the examples in later chapters. The actual usage of these
- tools is covered in later chapters.</para>
-
- <tip>
- <title>Use <filename role="package">textproc/docproj</filename> If
- Possible</title>
-
- <para>You can save yourself a lot of time if you install the
- <filename role="package">textproc/docproj</filename> port. This
- is a <emphasis>meta-port</emphasis> which does not contain any
- software itself. Instead, it depends on various other ports
- being installed correctly. Installing this port
- <emphasis>should</emphasis> automatically download and install
- all of the packages listed in this chapter that you need.</para>
-
- <para>One of the packages that you might need is the
- <application>JadeTeX</application> macro set. In turn, this
- macro set requires &tex; to be installed. &tex; is a large
- package, and you only need it if you want to produce Postscript
- or PDF output.</para>
-
- <para>To save yourself time and space you must specify whether or
- not you want <application>JadeTeX</application> (and therefore
- &tex;) installed when you install this port. Either do:</para>
-
- <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
-
- <para>or</para>
-
- <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
-
- <para>as necessary. Alternatively you may install
- <filename role="package">textproc/docproj-jadetex</filename> or
- <filename role="package">textproc/docproj-nojadetex</filename>.
- These slave ports define the <makevar>JADETEX</makevar> variable
- for you, therefore they will install the same suite of
- applications on your machine. Note that you can produce only
- XHTML or ASCII text output if you do not install
- <application>JadeTeX</application>. PostScript or PDF output
- requires &tex;.</para>
- </tip>
-
- <sect1 id="tools-mandatory">
- <title>Mandatory Tools</title>
-
- <sect2>
- <title>Software</title>
-
- <para>These programs are required before you can usefully work
- with the FreeBSD documentation, and they will allow you to
- convert the documentation to XHTML, plain text, and RTF
- formats. They are all included in <filename
- role="package">textproc/docproj</filename>.</para>
-
- <variablelist>
- <varlistentry>
- <term><application>Jade</application>
- (<filename role="package">textproc/jade</filename>)</term>
-
- <listitem>
- <para>A DSSSL implementation. Used for converting marked
- up documents to other formats, including HTML and
- &tex;.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Tidy</application>
- (<filename role="package">www/tidy</filename>)</term>
-
- <listitem>
- <para>An (X)HTML <quote>pretty printer</quote>, used to
- reformat some of the automatically generated pages so
- that it is easier to follow.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Links</application>
- (<filename role="package">www/links</filename>)</term>
-
- <listitem>
- <para>A text-mode WWW browser that can also convert
- XHTML files to plain text.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>peps</application>
- (<filename role="package">graphics/peps</filename>)</term>
-
- <listitem>
- <para>Some of the documentation includes images, some of
- which are stored as EPS files. These must be converted
- to PNG before most web browsers will display
- them.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>DTDs and Entities</title>
-
- <para>These are the DTDs and entity sets used by the FDP. They
- need to be installed before you can work with any of the
- documentation.</para>
-
- <variablelist>
- <varlistentry>
- <term>XHTML DTD (<filename
- role="package">textproc/xhtml</filename>)</term>
-
- <listitem>
- <para>XHTML is the markup language of choice for the World
- Wide Web, and is used throughout the FreeBSD web
- site.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DocBook DTD (<filename
- role="package">textproc/docbook</filename>)</term>
-
- <listitem>
- <para>DocBook is designed for marking up technical
- documentation. All the FreeBSD documentation is written
- in DocBook.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ISO 8879 entities
- (<filename
- role="package">textproc/iso8879</filename>)</term>
-
- <listitem>
- <para>19 of the ISO 8879:1986 character entity sets used
- by many DTDs. Includes named mathematical symbols,
- additional characters in the Latin character set
- (accents, diacriticals, and so on), and Greek
- symbols.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Stylesheets</title>
-
- <para>The stylesheets are used when converting and formatting
- the documentation for display on screen, printing, and so
- on.</para>
-
- <variablelist>
- <varlistentry>
- <term>Modular DocBook Stylesheets
- (<filename
- role="package">textproc/dsssl-docbook-modular</filename>)</term>
-
- <listitem>
- <para>The Modular DocBook Stylesheets are used when
- converting documentation marked up in DocBook to other
- formats, such as HTML or RTF.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-
- <sect1 id="tools-optional">
- <title>Optional Tools</title>
-
- <para>You do not need to have any of the following installed.
- However, you may find it easier to work with the documentation
- if you do, and they may give you more flexibility in the output
- formats that can be generated.</para>
-
- <sect2>
- <title>Software</title>
-
- <variablelist>
- <varlistentry>
- <term><application>JadeTeX</application> and
- <application>teTeX</application>
- (<filename role="package">print/jadetex</filename> and
- <filename role="package">print/teTeX</filename>)</term>
-
- <listitem>
- <para><application>Jade</application> and
- <application>teTeX</application> are used to convert
- DocBook documents to DVI, Postscript, and PDF formats.
- The <application>JadeTeX</application> macros are needed
- in order to do this.</para>
-
- <para>If you do not intend to convert your documentation
- to one of these formats (i.e., HTML, plain text, and RTF
- are sufficient) then you do not need to install
- <application>JadeTeX</application> and
- <application>teTeX</application>. This can be a
- significant space and time saver, as
- <application>teTeX</application> is over 30MB in
- size.</para>
-
- <important>
- <para>If you decide to install
- <application>JadeTeX</application> and
- <application>teTeX</application> then you will need to
- configure <application>teTeX</application> after
- <application>JadeTeX</application> has been installed.
- <filename>print/jadetex/pkg-message</filename>
- contains detailed instructions explaining what you
- need to do.</para>
- </important>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Emacs</application> or
- <application>XEmacs</application>
- (<filename role="package">editors/emacs</filename> or
- <filename role="package">editors/xemacs</filename>)</term>
-
- <listitem>
- <para>Both these editors include a special mode for
- editing documents marked up according to an SGML DTD.
- This mode includes commands to reduce the amount of
- typing you need, and help reduce the possibility of
- errors.</para>
-
- <para>You do not need to use them; any text editor can be
- used to edit marked up documents. You may find they
- make you more efficient.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>If anyone has recommendations for other software that is
- useful when manipulating XML documents, please let &a.doceng;
- know, so they can be added to this list.</para>
- </sect2>
- </sect1>
-</chapter>
Index: doc-build/chapter.xml
===================================================================
--- doc-build/chapter.xml (revision 40548)
+++ doc-build/chapter.xml (working copy)
@@ -44,9 +44,8 @@
<itemizedlist>
<listitem>
- <para>Know what you need to build the FDP documentation, in
- addition to those mentioned in the
- <link linkend="tools">XML tools chapter</link>.</para>
+ <para>Know what you need to build the FDP documentation.
+ </para>
</listitem>
<listitem>
@@ -311,7 +310,7 @@
if these are not set by the document make file.</para>
<para><makevar>PREFIX</makevar> is the prefix under which the
- <link linkend="tools">documentation building tools</link>
+ documentation building tools
are installed. For normal package and port installation,
this is <filename>/usr/local</filename>.</para>
Index: Makefile
===================================================================
--- Makefile (revision 40548)
+++ Makefile (working copy)
@@ -29,7 +29,6 @@
SRCS+= structure/chapter.xml
SRCS+= doc-build/chapter.xml
SRCS+= the-website/chapter.xml
-SRCS+= tools/chapter.xml
SRCS+= translations/chapter.xml
SRCS+= writing-style/chapter.xml
Index: overview/chapter.xml
===================================================================
--- overview/chapter.xml (revision 40548)
+++ overview/chapter.xml (working copy)
@@ -1,5 +1,6 @@
-<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
-<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!--
+Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
@@ -34,21 +35,21 @@
<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
+ <para>Welcome to the FreeBSD Documentation Project (FDP). Good
+ quality documentation is very important to the success of FreeBSD,
+ and the FreeBSD Documentation Project is how a lot of that
documentation is produced. 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>
+ <para>This document begins with a Quick Start Guide to assist
+ new contributors in getting started with the FreeBSD
+ documentation set. It is followed by an XML Primer which
+ provides a reference to the entities used by the FreeBSD
+ documentation team. This document also describes the
+ documentation build process, provides a Style Guide, and
+ describes the process of maintaining the FreeBSD website and
+ documentation translations.</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
@@ -90,8 +91,8 @@
<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
+ However, the FDP can re-word existing
+ manual pages to make them clearer or to correct
inaccuracies.</para>
<para>The translation teams are responsible for translating
@@ -105,7 +106,7 @@
<listitem>
<para>The FAQ aims to address (in short question and answer
- format) questions that are asked, or should be asked, on
+ format) questions that are commonly asked on
the various mailing lists and newsgroups devoted to
FreeBSD. The format does not permit long and
comprehensive answers.</para>
@@ -156,146 +157,254 @@
as possible.</para>
</sect1>
- <sect1 id="overview-before">
- <title>Before You Start</title>
-
- <para>This document assumes that you already know:</para>
-
- <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>
- </listitem>
-
- <listitem>
- <para>How to download and install new software using either
- the FreeBSD Ports system or &man.pkg.add.1;.</para>
- </listitem>
- </itemizedlist>
- </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 in order to make changes to the FDP. As you start
+ contributing edits, you will interact with other members of
+ the FreeBSD document team. They can assist you as you learn how
+ to use the XML entities and learn the FreeBSD Documentation
+ Style Guide. If you contribute regularly, a documentation team
+ member may be assigned as a mentor to guide you through the
+ process from contributor to documentation committer.</para>
+ <para>The required steps to get you started are as follows:</para>
+
<procedure>
<step>
- <para>Install the
- <filename role="package">textproc/docproj</filename>
- meta-port.</para>
+ <para>Join the &a.doc; and #bsddocs channel on EFnet
+ IRC.</para>
- <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
-&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
+ <para>New contributors will send their documentation edits to
+ &a.doc; for review. The mailing list and IRC channel are
+ excellent resources for collaboration between doc editors
+ and for new contributors to receive help as they learn how
+ to use the FDP.</para>
</step>
<step>
- <para>Get a local copy of the FreeBSD <filename>doc</filename>
- tree using <application>svn</application>.</para>
+ <para>Install the necessary software and DTDs.</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>
+ <para>The FDP uses a number of different software tools to
+ obtain and manage FreeBSD documentation and convert it to
+ different output formats. If these tools are not already
+ installed on your system, you will need to install them from
+ the FreeBSD Ports or Packages collection.</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 svn://svn.FreeBSD.org/doc/head/share head/share</userinput>
-&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen>
+ <para><filename role="package">docproj</filename> is
+ required to work with the FreeBSD documentation. You have a
+ choice of two ports. If you install <filename
+ role="package">textproc/docproj-nojadetex</filename>, you
+ will be able to convert the documentation to XHTML, plain
+ text, and RTF formats. If you instead install <filename
+ role="package">textproc/docproj</filename>, you will also be
+ able to produce DVI, Postscript and PDF output. However,
+ this port depends on &tex; which is a large port.
+ Regardless of which <filename
+ role="package">docproj</filename> port you choose to
+ install, it will automatically install the following
+ required tools:</para>
- <para>If you have plenty of disk space then you could check
- out everything.</para>
+ <itemizedlist>
+ <listitem>
+ <para><filename role="package">textproc/jade</filename>: A
+ DSSSL implementation used for converting marked up
+ documents to other formats, including HTML and
+ &tex;.</para>
+ </listitem>
- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head head</userinput></screen>
+ <listitem>
+ <para><filename role="package">www/tidy</filename>: An
+ (X)HTML <quote>pretty printer</quote>, used to
+ format some of the automatically generated pages.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename role="package">www/links</filename>: A
+ text-mode WWW browser that can also convert XHTML files
+ to plain text.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename role="package">graphics/peps</filename>:
+ Converts EPS images to PNG format so that web browsers
+ can display them.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In order to download the FreeBSD documentation,
+ <filename role="package">devel/subversion</filename> must be
+ installed.</para>
+
+ <para>Before submitting your changes, you need to first verify
+ syntax and grammar errors using the <filename
+ role="package">textproc/igor</filename> proofreader.</para>
+
+ <para>The following DTDs and entity sets are used by the FDP
+ and must be installed:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename role="package">textproc/xhtml</filename>:
+ The markup language used throughout the FreeBSD web
+ site.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename role="package">textproc/docbook</filename>:
+ All of the FreeBSD documentation is written in
+ DocBook.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename role="package">textproc/iso8879</filename>:
+ Character entity sets used by many DTDs. Includes named
+ mathematical symbols, additional characters such as
+ accents and diacriticals in the Latin character set, and
+ Greek symbols.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following stylesheets are needed for converting and
+ formatting the documentation:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename role=
+ "package">textproc/dsssl-docbook-modular</filename>:
+ Used when converting documentation marked up in DocBook
+ to other formats, such as HTML or RTF.</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>Configure your editor.</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>Before making any documentation edits, make sure
+ that your editor of choice is properly configured. How to
+ do so varies by editor, so if you need assistance, ask on
+ the #bsddocs IRC channel. The editor should be configured
+ as follows:</para>
- <procedure>
- <step>
- <para>Check out the <filename>articles</filename>
- directory.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Word wrap: 70 characters.</para>
+ </listitem>
+ </itemizedlist>
+ </step>
- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen>
- </step>
+ <step>
+ <para>Get a local copy of the FreeBSD <filename>doc</filename>
+ tree using <application>svn</application>.</para>
- <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>
+ <para>The following example syncs with the doc tree on the
+ main FreeBSD subversion server. You should replace the URL
+ with the one used by your
+ <ulink url="http://www.freebsd.org/handbook/svn-mirrors.html">;
+ closest geographic mirror.</ulink></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>
+ <screen>&prompt.user; <userinput>svn checkout
+ svn://svn.FreeBSD.org/doc/head <replaceable>head</replaceable></userinput></screen>
- <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>
+ <para> To ensure that you have the latest copy of the
+ documentation set, repeat this command before making any
+ edits to the files in the FDP.</para>
+ </step>
- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>
+ <step>
+
+ <para>Determine which <filename>.xml</filename> you wish to
+ edit using your pre-configured editor. If you are just
+ starting, it is recommended that you only edit one file,
+ then perform the following steps before beginning
+ to edit another file.</para>
+
+ <para>When making your edits, you will learn as you go which
+ tags and entities are used to achieve the desired
+ formatting. One way to learn is to compare some text in the
+ HTML formatted version of the document to the tags which
+ surround the text or the entities that represent that text
+ in the <filename>.xml</filename> file. A reference to the
+ commonly used tags and entities can be found in the <ulink
+url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#xml-markup">;
+ XML Markup section</ulink> of this document.</para>
+
+ <para>You will find that while you may have to research some
+ tags, you will be able to devote most of your time to making
+ content edits. What will take some getting used to is
+ proper indentation as described in the <ulink
+url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#AEN3211">;
+ Style Guide.<ulink></para>
</step>
<step>
- <para>Edit the <filename>.xml</filename> files using your
- editor of choice.</para>
+ <para>Test the validity of your changes by running
+ <userinput>igor filename.xml | more</userinput></screen>.
+
+ As you review the output, edit your file to fix the listed
+ tab and whitespace errors, spelling mistakes, and
+ improper grammar. Continue to rerun this command until you
+ have fixed all of the errors that you deem fixable. If you
+ get stuck trying to fix formatting errors, check to see
+ if anyone is available on the IRC channel to assist
+ you.</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>
+ <para>Verify that the file successfully builds.</para>
- <screen>&prompt.user; <userinput>make lint</userinput></screen>
+ <para>By default, typing <userinput>make</userinput> in the
+ top-level directory of the type of documentation that you
+ are editing will generate that type of documentation in
+ HTML format. For example, if you are editing 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 your
+ edits do not break the buile of that section of the
+ FDP.</para>
- <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.
+ <para>If you wish to build the output in other formats, other
+ <userinput>make</userinput> targets are defined in
+ <filename>head/share/mk/doc.docbook.mk</filename>.
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>
+ <para>For example, to convert the document to both
+ <literal>html</literal> and <literal>txt</literal>, use the
+ following command:</para>
- <screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
+ <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
+ </step>
- <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>
+ <step>
+ <para>Once you have successfully completed these steps,
+ generate a diff file of your changes. Make sure that
+ you are in the top-level directory of the section of the FDP
+ that contains your edits, then run this command:</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>
+ <screen>&prompt.user; <userinput>svn diff > article.xml</userinput></screen>
</step>
<step>
- <para>Submit your changes using &man.send-pr.1;.</para>
+ <para>Email the diff file to &a.doc; and wait for
+ feedback. Use an email subject of <quote>[patch] some
+ description</quote>. The body of the email should
+ contain a short description of the edits and any discussion
+ points that you wish to raise regarding the edits.</para>
+
+ <para>It is important to remember that the FreeBSD
+ Documentation team 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 for you or contact you if additional
+ edits are required. If you do not receive a response in a
+ day or so, ask on the #bsddocs IRC channel if anyone has had
+ a chance to review your edit or if additional information is
+ required.</para>
</step>
</procedure>
</sect1>
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1357765738.95165.YahooMailClassic>