Date: Wed, 16 Jan 2013 07:52:20 -0800 (PST) From: Dru Lavigne <dru.lavigne@att.net> To: freebsd-doc@freebsd.org Subject: fixes to fdp-primer patch Message-ID: <1358351540.31448.YahooMailClassic@web184906.mail.gq1.yahoo.com>
index | next in thread | raw e-mail
[-- Attachment #1 --]
The attached patch fixes the anchor issues, BOM, and adds the suggested igor switch. It also changes the suggested filename in step 8.
Cheers,
Dru
[-- Attachment #2 --]
Index: overview/chapter.xml
===================================================================
--- overview/chapter.xml (revision 40654)
+++ 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.
+<!--
+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 <link
+ linkend="xml-markup">XML Markup section</link> 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 <link
+ linkend="writing-style-guide"> Indentation section of the
+ Writing Style Guide.</link></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
+
+ <screen><userinput>igor -R filename.xml | less -RS</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 > descriptive_name.diff</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>
home |
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1358351540.31448.YahooMailClassic>