- </ol>
-
- <p>
- Finished docs should be occasionally submitted to CVS (<tt class=
- "FILENAME">doc/webserver/*/*.html</tt>) so that those without the
- ability to build them locally, have access to them if needed. This is
- especially important just prior to a new release! Please do this
- <span class="emphasis"><i class="EMPHASIS">after</i></span> the <tt
- class="LITERAL">$VERSION</tt> and other release specific data in <tt
- class="FILENAME">configure.in</tt> has been updated (this is done
- just prior to a new release).
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="SGML">3.1. Quickstart to Docbook and SGML</a>
- </h2>
- <p>
- If you are not familiar with SGML, it is a markup language similar
- to HTML. Actually, not a mark up language per se, but a language
- used to define markup languages. In fact, HTML is an SGML
- application. Both will use <span class="QUOTE">"tags"</span> to
- format text and other content. SGML tags can be much more varied,
- and flexible, but do much of the same kinds of things. The tags, or
- <span class="QUOTE">"elements"</span>, are definable in SGML. There
- is no set <span class="QUOTE">"standards"</span>. Since we are
- using <span class="APPLICATION">Docbook</span>, our tags are those
- that are defined by <span class="APPLICATION">Docbook</span>. Much
- of how the finish document is rendered is determined by the <span
- class="QUOTE">"stylesheets"</span>. The stylesheets determine how
- each tag gets translated to HTML, or other formats.
- </p>
- <p>
- Tags in Docbook SGML need to be always <span class=
- "QUOTE">"closed"</span>. If not, you will likely generate errors.
- Example: <tt class="LITERAL"><title>My
- Title</title></tt>. They are also case-insensitive, but we
- strongly suggest using all lower case. This keeps compatibility
- with [Docbook] <span class="APPLICATION">XML</span>.
- </p>
- <p>
- Our documents use <span class="QUOTE">"sections"</span> for the
- most part. Sections will be processed into HTML headers (e.g. <tt
- class="LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The
- <span class="APPLICATION">Docbook</span> stylesheets will use these
- to also generate the Table of Contents for each doc. Our TOC's are
- set to a depth of three. Meaning <tt class="LITERAL">sect1</tt>,
- <tt class="LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt>
- will have TOC entries, but <tt class="LITERAL">sect4</tt> will not.
- Each section requires a <tt class="LITERAL"><title></tt>
- element, and at least one <tt class="LITERAL"><para></tt>.
- There is a limit of five section levels in Docbook, but generally
- three should be sufficient for our purposes.
- </p>
- <p>
- Some common elements that you likely will use:
- </p>
- <p>
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><para></para></i></span>, paragraph
- delimiter. Most text needs to be within paragraph elements
- (there are some exceptions).
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><emphasis></emphasis></i></span>, the
- stylesheets make this italics.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><filename></filename></i></span>,
- files and directories.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><command></command></i></span>,
- command examples.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><literallayout></literallayout></i></span>,
- like <tt class="LITERAL"><pre></tt>, more or less.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><itemizedlist></itemizedlist></i></span>,
- list with bullets.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><listitem></listitem></i></span>,
- member of the above.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><screen></screen></i></span>, screen
- output, implies <tt class=
- "LITERAL"><literallayout></tt>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class="EMPHASIS"><ulink
- url="example.com"></ulink></i></span>, like HTML <tt
- class="LITERAL"><a></tt> tag.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><quote></quote></i></span>, for, doh,
- quoting text.
- </td>
- </tr>
- </tbody>
- </table>
-
- <p>
- Look at any of the existing docs for examples of all these and
- more.
- </p>
- <p>
- You might also find <span class="QUOTE">"<a href=
- "http://opensource.bureau-cornavin.com/crash-course/index.html"
- target="_top">Writing Documentation Using DocBook - A Crash
- Course</a>"</span> useful.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="DOCSTYLE">3.2. <span class="APPLICATION">Privoxy</span>
- Documentation Style</a>
- </h2>
- <p>
- It will be easier if everyone follows a similar writing style. This
- just makes it easier to read what someone else has written if it is
- all done in a similar fashion.
- </p>
- <p>
- Here it is:
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- All tags should be lower case.
- </p>
- </li>
- <li>
- <p>
- Tags delimiting a <span class="emphasis"><i class=
- "EMPHASIS">block</i></span> of text (even small blocks) should
- be on their own line. Like:
- </p>
- <p class="LITERALLAYOUT">
- <para><br>
- Some text goes here.<br>
- </para><br>
-
- </p>
- Tags marking individual words, or few words, should be in-line:
- <p class="LITERALLAYOUT">
- Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
-
-
- </p>
- </li>
- <li>
- <p>
- Tags should be nested and step indented for block text like:
- (except in-line tags)
- </p>
- <p class="LITERALLAYOUT">
- <para><br>
- <itemizedlist><br>
- <para><br>
- <listitem><br>
- Some text goes here in our list example.<br>
-
- </listitem><br>
- </para><br>
- </itemizedlist><br>
- </para><br>
-
- </p>
- This makes it easier to find the text amongst the tags ;-)<br>
- </li>
- <li>
- <p>
- Use white space to separate logical divisions within a
- document, like between sections. Running everything together
- consistently makes it harder to read and work on.
- </p>
- </li>
- <li>
- <p>
- Do not hesitate to make comments. Comments can either use the
- <comment> element, or the <!-- --> style comment
- familiar from HTML. (Note in Docbook v4.x <comment> is
- replaced by <remark>.)
- </p>
- </li>
- <li>
- <p>
- We have an international audience. Refrain from slang, or
- English idiosyncrasies (too many to list :). Humor also does
- not translate well sometimes.
- </p>
- </li>
- <li>
- <p>
- Try to keep overall line lengths in source files to 80
- characters or less for obvious reasons. This is not always
- possible, with lengthy URLs for instance.
- </p>
- </li>
- <li>
- <p>
- Our documents are available in differing formats. Right now,
- they are just plain text, HTML, and PDF, but others are always
- a future possibility. Be careful with URLs (<ulink>), and
- avoid this mistake:
- </p>
- <p>
- My favorite site is <ulink
- url="http://example.com">here</ulink>.
- </p>
- <p>
- This will render as <span class="QUOTE">"My favorite site is
- here"</span>, which is not real helpful in a text doc. Better
- like this:
- </p>
- <p>
- My favorite site is <ulink
- url="http://example.com">example.com</ulink>.
- </p>
- </li>
- <li>
- <p>
- All documents should be spell checked occasionally. <span
- class="APPLICATION">aspell</span> can check SGML with the <tt
- class="LITERAL">-H</tt> option. (<span class=
- "APPLICATION">ispell</span> I think too.)
- </p>
- </li>
- </ul>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="AEN217">3.3. Privoxy Custom Entities</a>
- </h2>
- <p>
- <span class="APPLICATION">Privoxy</span> documentation is using a
- number of customized <span class="QUOTE">"entities"</span> to
- facilitate documentation maintenance.
- </p>
- <p>
- We are using a set of <span class="QUOTE">"boilerplate"</span>
- files with generic text, that is used by multiple docs. This way we
- can write something once, and use it repeatedly without having to
- re-write the same content over and over again. If editing such a
- file, keep in mind that it should be <span class="emphasis"><i
- class="EMPHASIS">generic</i></span>. That is the purpose; so it can
- be used in varying contexts without additional modifications.
- </p>
- <p>
- We are also using what <span class="APPLICATION">Docbook</span>
- calls <span class="QUOTE">"internal entities"</span>. These are
- like variables in programming. Well, sort of. For instance, we have
- the <tt class="LITERAL">p-version</tt> entity that contains the
- current <span class="APPLICATION">Privoxy</span> version string.
- You are strongly encouraged to use these where possible. Some of
- these obviously require re-setting with each release (done by the
- Makefile). A sampling of custom entities are listed below. See any
- of the main docs for examples.
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- Re- <span class="QUOTE">"boilerplate"</span> text entities are
- defined like:
- </p>
- <p>
- <tt class="LITERAL"><!entity supported SYSTEM
- "supported.sgml"></tt>
- </p>
- <p>
- In this example, the contents of the file, <tt class=
- "FILENAME">supported.sgml</tt> is available for inclusion
- anywhere in the doc. To make this happen, just reference the
- now defined entity: <tt class="LITERAL">&supported;</tt>
- (starts with an ampersand and ends with a semi-colon), and the
- contents will be dumped into the finished doc at that point.
- </p>
- </li>
- <li>
- <p>
- Commonly used <span class="QUOTE">"internal entities"</span>:
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-version</i></span>: the <span class=
- "APPLICATION">Privoxy</span> version string, e.g. <span
- class="QUOTE">"3.0.18"</span>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-status</i></span>: the project status,
- either <span class="QUOTE">"alpha"</span>, <span class=
- "QUOTE">"beta"</span>, or <span class=
- "QUOTE">"stable"</span>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-not-stable</i></span>: use to conditionally
- include text in <span class="QUOTE">"not stable"</span>
- releases (e.g. <span class="QUOTE">"beta"</span>).
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-stable</i></span>: just the opposite.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-text</i></span>: this doc is only generated
- as text.
- </td>
- </tr>
- </tbody>
- </table>
- </li>
- </ul>