-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
+<!entity % dummy "IGNORE">
+<!entity supported SYSTEM "supported.sgml">
+<!entity newfeatures SYSTEM "newfeatures.sgml">
+<!entity p-intro SYSTEM "privoxy.sgml">
+<!entity history SYSTEM "history.sgml">
+<!entity seealso SYSTEM "seealso.sgml">
+<!entity contacting SYSTEM "contacting.sgml">
+<!entity copyright SYSTEM "copyright.sgml">
+<!entity p-version "2.9.14">
+<!entity p-status "beta">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
+<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
+<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
+]>
<!--
File : $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
Based on the Internet Junkbuster originally written
by and Copyright (C) 1997 Anonymous Coders and
Junkbusters Corporation. http://www.junkbusters.com
+
+
+ ========================================================================
+ NOTE: Please read developer-manual/documentation.html before touching
+ anything in this, or other Privoxy documentation. You have been warned!
+ Failure to abide by this rule will result in the revocation of your license
+ to live a peaceful existence!
+ ========================================================================
+
-->
<article id="index">
<artheader>
<title>Privoxy Developer Manual</title>
- <pubdate>$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $</pubdate>
<authorgroup>
<author>
</authorgroup>
<abstract>
- <para>
+<![%dummy;[
+ <para>
+ <comment>
+ This is here to keep vim syntax file from breaking :/
+ If I knew enough to fix it, I would.
+ PLEASE DO NOT REMOVE! HB: hal@foobox.net
+ </comment>
+ </para>
+ ]]>
+<para>
The developer manual gives the users information on how to help the developer
team. It provides guidance on coding, testing, documentation and other
issues.
</para>
-<para>
- <application>Privoxy</application> is a web proxy with advanced filtering
- capabilities for protecting privacy, filtering web page content, managing
- cookies, controlling access, and removing ads, banners, pop-ups and other
- obnoxious Internet junk. <application>Privoxy</application> has a very
- flexible configuration and can be customized to suit individual needs and
- tastes. <application>Privoxy</application> has application for both
- stand-alone systems and multi-user networks.
-</para>
+<!-- Include privoxy.sgml boilerplate text: -->
-<para>
- <application>Privoxy</application> is based on the code of the
- <application>Internet Junkbuster</application>.
- <application>Junkbuster</application> was originally written by JunkBusters
- Corporation, and was released as free open-source software under the GNU GPL.
- Stefan Waldherr made many improvements, and started the SourceForge project
- to continue development. Other developers have since joined Stefan.
-</para>
+<!-- &p-intro; Someone interested enough in the project to contribute
+ will already know at this point what Privoxy is. -->
+
+<!-- end boilerplate -->
<para>
- You can find the latest version of the
user manual at <ulink
+ You can find the latest version of the
this manual at <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
- Please see the Contact section in the user-manual if you want to contact the
- developers.
+ Please see <ulink url="contact.html">the Contact section</ulink>
+ on how to contact the developers.
</para>
<!-- <para> -->
</abstract>
</artheader>
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="introduction"><title>Introduction</title>
- <para>To be filled.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="intro" label=""><title></title>
+<!-- dummy section to force TOC on page by itself -->
+<!-- DO NOT REMOVE! please ;) -->
+<para> </para>
+</sect1>
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+ <sect1 label="1" id="introduction"><title>Introduction</title>
+<!--
+
+ I don't like seeing blank space :) So added *something* here.
+
+ -->
+ <para>
+ <application>Privoxy</application>, as an heir to
+ <application>Junkbuster</application>, is an Open Source project
+ and licensed under the GPL. As such, <application>Privoxy</application>
+ development is potentially open to anyone who has the time, knowledge,
+ and desire to contribute in any capacity. Our goals are simply to
+ continue the mission, to improve <application>Privoxy</application>, and
+ to make it available to as wide an audience as possible.
+ </para>
+ <para>
+ One does not have to be a programmer to contribute. Packaging, testing,
+ and porting, are all important jobs as well.
+ </para>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="quickstart"><title>Quickstart to Privoxy Development</title>
<para>
-You'll need an account on Sourceforge to support our development. Mail you ID
-to the list and wait until a project manager has added you.
-
-For the time beeing (read, this section is under construction), please note the
-following guidelines for changing stuff in the code. If it is
- <orderedlist numeration="arabic">
- <listitem><para>
- A bugfix / clean-up / cosmetic thing: shoot
- </para></listitem>
- <listitem><para>
- A new feature that can be turned off: shoot
- </para></listitem>
- <listitem><para>
- A clear improvement w/o side effects on other parts of the code: shoot
- </para></listitem>
- <listitem><para>
- A matter of taste: ask the list
- </para></listitem>
- <listitem><para>
- A major redesign of some part of the code: ask the list
- </para></listitem>
- </orderedlist>
-</para>
- </sect1>
-
+ You'll need an account on <ulink
+ url="http://sourceforge.net/">Sourceforge</ulink> to support our
+ development. Mail your ID to <ulink
+ url="mailto:developers@privoxy.org">the list</ulink> and wait until a
+ project manager has added you.
+ </para>
+ <para>
+ For the time being (read, this section is under construction), please
+ refer to the extensive comments in the source code.
+ </para>
+ </sect1>
+
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="documentation"><title>Documentation Guidelines</title>
+ <sect1 id="cvs"><title>The CVS Repository</title>
<para>
- All docs are in SGML format and located in the <computeroutput>doc/source</computeroutput> directory.
- </para>
- <para>
- How do you update the webserver (i.e. the pages on sourceforge)?
+ If you intend to help us with programming, documentation or packaging
+ you will need write access to our holy grail, the CVS repository.
+ Please read this chapter completely before accessing via CVS.
+ </para>
+
+ <sect2 id="cvsaccess"><title>Access to CVS</title>
+ <para>
+ The project's CVS repository is hosted on
+ <ulink url="http://sourceforge.net/">SourceForge.</ulink>
+ Please refer to the chapters 6 and 7 in
+ <ulink url="http://sourceforge.net/docman/?group_id=1">SF's site
+ documentation</ulink> for the technical access details for your
+ operating system. For historical reasons, the CVS server is
+ called <literal>cvs.ijbswa.sourceforge.net</literal>, the repository is
+ called <literal>ijbswa</literal>, and the source tree module is called
+ <literal>current</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="cvscommit"><title>CVS Commit Guideline</title>
+ <para>
+ The source tree is the heart of every software project. Every effort must
+ be made to ensure that it is readable, compilable and consistent at all
+ times. We therefore ask anyone with CVS access to strictly adhere to the
+ following guidelines:
+ <itemizedlist>
+ <listitem><para>
+ Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
+ that small change without testing it thoroughly first. When we're
+ close to a public release, ask a fellow developer to review your
+ changes.
+ </para></listitem>
+ <listitem><para>
+ Your commit message should give a concise overview of <emphasis>what you
+ changed</emphasis> (no big details) and <emphasis>why you changed it</emphasis>
+ Just check previous messages for good examples.
+ </para></listitem>
+ <listitem><para>
+ Don't use the same message on multiple files, unless it equally applies to
+ all those files.
+ </para></listitem>
+ <listitem><para>
+ If your changes span multiple files, and the code won't recompile unless
+ all changes are commited (e.g. when changing the signature of a function),
+ then commit all files one after another, without long delays in beween.
+ If necessary, prepare the commit messages in advance.
+ </para></listitem>
+ <listitem><para>
+ Before changing things on CVS, make sure that your changes are in line
+ with the team's general consensus on what should be done (see below).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="cvswhenask"><title>Discussing Changes First</title>
+ <para>
+ We don't have a too formal policy on this, just use common sense. Hints: If it is..
<orderedlist numeration="arabic">
- <listitem><para>
- Run <computeroutput>make dok</computeroutput> (which uses the documents in <computeroutput>doc/source</computeroutput> to update all
- text files in <computeroutput>doc/text</computeroutput> and to update
-all web documents in <computeroutput>doc/webserver</computeroutput>.
- </para></listitem>
- <listitem><para>
- Run <computeroutput>make webserver</computeroutput> which copies all files from
-<computeroutput>doc/webserver</computeroutput> to the sourceforge webserver
-via scp.
- </para></listitem>
+ <listitem><para>
+ ..a bugfix / clean-up / cosmetic thing: shoot
+ </para></listitem>
+ <listitem><para>
+ ..a new feature that can be turned off: shoot
+ </para></listitem>
+ <listitem><para>
+ ..a clear improvement w/o side effects on other parts of the code: shoot
+ </para></listitem>
+ <listitem><para>
+ ..a matter of taste: <ulink url="mailto:developers@privoxy.org">ask the list</ulink>
+ </para></listitem>
+ <listitem><para>
+ ..a major redesign of some part of the code: <ulink url="mailto:developers@privoxy.org">ask
+ the list</ulink>
+ </para></listitem>
</orderedlist>
+ </para>
+ <para>
+ Note that near a major public release, we get a bit more cautious - if
+ unsure, it doesn't hurt to ask first. There is always the possibility
+ to submit a patch to the <ulink
+ url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patches
+ tracker</ulink> instead.
+ </para>
+ </sect2>
+ </sect1>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="documentation"><title>Documentation Guidelines</title>
+ <para>
+ All formal documents are maintained in Docbook SGML and located in the
+ <computeroutput>doc/source/*</computeroutput> directory. You will need
+ <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ and either <application>jade</application> or
+ <application>openjade</application> (recommended) installed in order to
+ build docs from source. Currently there is <ulink
+ url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
+ <ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
+ course this, the <citetitle>developer-manual</citetitle> in this format.
+ The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
+ <citetitle>privoxy.1</citetitle> (man page) files are also now maintained
+ as Docbook SGML. The finished files are all in the top-level source
+ directory are generated files! Also, <filename>index.html</filename>, the
+ <application>Privoxy</application> home page, is maintained as SGML.
+ <emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
+ contact someone involved in the documentation (at present Stefan and
+ Hal).
+ </para>
+ <para>
+ Other, less formal documents (e.g. <filename>LICENSE</filename>,
+ <filename>INSTALL</filename>) are maintained as plain text files in the
+ top-level source directory. At least for the time being.
+ </para>
+ <para>
+ Packagers are encouraged to include this documentation. For those without
+ the ability to build the docs locally, text versions of each are kept in
+ CVS. HTML versions are also now being kept in CVS under
+ <filename>doc/webserver/*</filename>.
+ </para>
+ <para>
+ Formal documents are built with the Makefile targets of
+ <computeroutput>make dok</computeroutput>, or alternately
+ <computeroutput>make redhat-dok</computeroutput>. If you have problems,
+ try both. The build process uses the document SGML sources in
+ <computeroutput>doc/source/*/*</computeroutput> to update all text files in
+ <computeroutput>doc/text/</computeroutput> and to update all HTML
+ documents in <computeroutput>doc/webserver/</computeroutput>.
+ </para>
+ <para>
+ Documentation writers should please make sure documents build
+ successfully before committing to CVS, if possible.
+ </para>
+ <para>
+ How do you update the webserver (i.e. the pages on privoxy.org)?
+
+ <orderedlist numeration="arabic">
+ <listitem><para>
+ First, build the docs by running <computeroutput>make
+ dok</computeroutput> (or alternately <computeroutput>make
+ redhat-dok</computeroutput>).
+ </para></listitem>
+ <listitem><para>
+ Run <computeroutput>make webserver</computeroutput> which copies all
+ files from <computeroutput>doc/webserver</computeroutput> to the
+ sourceforge webserver via scp.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ Finished docs should be occasionally submitted to CVS
+ (<filename>doc/webserver/*/*.html</filename>) 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 <emphasis>after</emphasis> the <literal>$VERSION</literal> and
+ other release specific data in <filename>configure.in</filename> has been
+ updated (this is done just prior to a new release).
</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="sgml">
+<title>Quickstart to Docbook and SGML</title>
+<para>
+ 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
+ <quote>tags</quote> 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 <quote>elements</quote>, are definable in SGML. There is no set
+ <quote>standards</quote>. Since we are using
+ <application>Docbook</application>, our tags are those that are defined by
+ <application>Docbook</application>. Much of how the finish document is
+ rendered is determined by the <quote>stylesheets</quote>.
+ The stylesheets determine how each tag gets translated to HTML, or other
+ formats.
+</para>
+
+<para>
+ Tags in Docbook SGML need to be always <quote>closed</quote>. If not, you
+ will likely generate errors. Example: <literal><title>My
+ Title</title></literal>. They are also case-insensitive, but we
+ strongly suggest using all lower case. This keeps compatibility with
+ [Docbook] <application>XML</application>.
+</para>
+
+<para>
+ Our documents use <quote>sections</quote> for the most part. Sections
+ will be processed into HTML headers (e.g. <literal>h1</literal> for
+ <literal>sect1</literal>). The <application>Docbook</application> 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 <literal>sect1</literal>,
+ <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
+ entries, but <literal>sect4</literal> will not. Each section requires
+ a <literal><title></literal> element, and at least one
+ <literal><para></literal>. There is a limit of five section
+ levels in Docbook, but generally three should be sufficient for our
+ purposes.
+</para>
+
+<para>
+ Some common elements that you likely will use:
+</para>
+
+<para>
+ <simplelist>
+ <member>
+ <emphasis><para></para></emphasis>, paragraph delimiter. Most
+ text needs to be within paragraph elements (there are some exceptions).
+ </member>
+ <member>
+ <emphasis><emphasis></emphasis></emphasis>, the stylesheets
+ make this italics.
+ </member>
+ <member>
+ <emphasis><filename></filename></emphasis>, files and directories.
+ </member>
+ <member>
+ <emphasis><command></command></emphasis>, command examples.
+ </member>
+ <member>
+ <emphasis><literallayout></literallayout></emphasis>, like
+ <literal><pre></literal>, more or less.
+ </member>
+ <member>
+ <emphasis><itemizedlist></itemizedlist></emphasis>, list with bullets.
+ </member>
+ <member>
+ <emphasis><listitem></listitem></emphasis>, member of the above.
+ </member>
+ <member>
+ <emphasis><screen></screen></emphasis>, screen output, implies
+ <literal><literallayout></literal>.
+ </member>
+ <member>
+ <emphasis><ulink url="example.com"></ulink></emphasis>, like
+ HTML <literal><a></literal> tag.
+ </member>
+ <member>
+ <emphasis><quote></quote></emphasis>, for, doh, quoting text.
+ </member>
+ </simplelist>
+</para>
+
+<para>
+ Look at any of the existing docs for examples of all these and more.
+</para>
+
+<para>
+ You might also find <quote><ulink
+ url="http://www.bureau-cornavin.com/opensource/crash-course/">Writing Documentation
+ Using DocBook - A Crash Course</ulink></quote> useful.
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+ <sect2 id="docstyle">
+ <title><application>Privoxy</application> Documentation Style</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Here it is:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ All tags should be lower case.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tags delimiting a <emphasis>block</emphasis> of text (even small
+ blocks) should be on their own line. Like:
+ <literallayout>
+ <para>
+ Some text goes here.
+ </para>
+ </literallayout>
+ Tags marking individual words, or few words, should be in-line:
+ <literallayout>
+ Just to <emphasis>emphasize</emphasis>, some text goes here.
+ </literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tags should be nested and step indented for block text like: (except
+ in-line tags)
+ <literallayout>
+ <para>
+ <itemizedlist>
+ <para>
+ <listitem>
+ Some text goes here in our list example.
+ </listitem>
+ </para>
+ </itemizedlist>
+ </para>
+ </literallayout>
+ This makes it easier to find the text amongst the tags ;-)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ We have an international audience. Refrain from slang, or English
+ idiosyncrasies (too many to list :). Humor also does not translate
+ well sometimes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Our documents are available in differing formats. Right now, they
+ are just plain text, and HTML, but PDF, and others is always a
+ future possibility. Be careful with URLs (<ulink>), and avoid
+ this mistake:
+ </para>
+ <para>
+ My favorite site is <ulink url="http://example.com">here</ulink>.
+ </para>
+ <para>
+ This will render as <quote>My favorite site is here</quote>, which is
+ not real helpful in a text doc. Better like this:
+ </para>
+ <para>
+ My favorite site is <ulink url="http://example.com">example.com</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All documents should be spell checked occasionally.
+ <application>aspell</application> can check SGML with the
+ <literal>-H</literal> option. (<application>ispell</application> I think
+ too.)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+
+ <!-- ~~~~~ New section ~~~~~ -->
+
+ <sect2><title>Privoxy Custom Entities</title>
+ <para>
+ <application>Privoxy</application> documentation is using
+ a number of customized <quote>entities</quote> to facilitate
+ documentation maintenance.
+ </para>
+ <para>
+ We are using a set of <quote>boilerplate</quote> 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
+ <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
+ contexts without additional modifications.
+ </para>
+ <para>
+ We are also using what <application>Docbook</application> calls
+ <quote>internal entities</quote>. These are like variables in
+ programming. Well, sort of. For instance, we have the
+ <literal>p-version</literal> entity that contains the current
+ <application>Privoxy</application> 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.
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Re- <quote>boilerplate</quote> text entities are defined like:
+ </para>
+ <para>
+ <literal><!entity supported SYSTEM "supported.sgml"></literal>
+ </para>
+ <para>
+ In this example, the contents of the file,
+ <filename>supported.sgml</filename> is available for inclusion anywhere
+ in the doc. To make this happen, just reference the now defined
+ entity: <literal>&supported;</literal> (starts with an ampersand
+ and ends with a semi-colon), and the contents will be dumped into
+ the finished doc at that point.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Commonly used <quote>internal entities</quote>:
+ </para>
+ <simplelist>
+ <member>
+ <emphasis>p-version</emphasis>: the <application>Privoxy</application>
+ version string, e.g. <quote>&p-version;</quote>.
+ </member>
+ <member>
+ <emphasis>p-status</emphasis>: the project status, either
+ <quote>alpha</quote>, <quote>beta</quote>, or <quote>stable</quote>.
+ </member>
+ <member>
+ <emphasis>p-not-stable</emphasis>: use to conditionally include
+ text in <quote>not stable</quote> releases (e.g. <quote>beta</quote>).
+ </member>
+ <member>
+ <emphasis>p-stable</emphasis>: just the opposite.
+ </member>
+ <member>
+ <emphasis>p-text</emphasis>: this doc is only generated as text.
+ </member>
+ </simplelist>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ There are others in various places that are defined for a specific
+ purpose. Read the source!
+ </para>
+
+ </sect2>
+
</sect1>
<!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
<para><emphasis>Exception:</emphasis></para>
<para>If you are trying to add a small logic comment and do not
- wish to "disrubt" the flow of the code, feel free to use a 1
+ wish to "disrupt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.</para>
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
<para><emphasis>Note:</emphasis> In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
- condidtion that is obvious from the purpose of the block,
+ condition that is obvious from the purpose of the block,
one-liners as above may optically preserve the loop structure
and make it easier to read.</para>
- <para><emphasis>Status:</emphasis> developer-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
<para><emphasis>Example exception:</emphasis></para>
<programlisting>
<para>if ( condition ) { structure->flag = 1; } else {
structure->flag = 0; }</para>
- <para><emphasis>Note:</emphasis> The former is readable and consice. The later
+ <para><emphasis>Note:</emphasis> The former is readable and concise. The later
is wordy and inefficient. Please assume that any developer new
to the project has at least a "good" knowledge of C/C++. (Hope
I do not offend by that last comment ... 8-)</para>
function2( ... ) { }</para>
<para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
- lines afterwards. This makes the end of function standout to
+ lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
- seperate functions, this is still a good coding practice. In
+ separate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!</para>
- <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
+ <para><emphasis>Status:</emphasis> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</para>
and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
arrayPtr[0].</para>
- <para><emphasis>Status:</emphasis> developer-discrection if and only if the
+ <para><emphasis>Status:</emphasis> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</para>
</sect3>
<para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.</para>
+ "file.h" behavior.</para>
</sect3>
<para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
pointer), then including the proper header file is necessary.
If you only want to prototype a pointer, however, the header
- file is unneccessary.</para>
+ file is unnecessary.</para>
- <para><emphasis>Status:</emphasis> Use with discrection.</para>
+ <para><emphasis>Status:</emphasis> Use with discretion.</para>
</sect3>
default :
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */</programlisting>
This API call *should* be included in a default statement.</para>
<para><emphasis>Another Note:</emphasis> This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
+ as a robust programming issue. The "anomaly code goes here" may
be no more than a print to the STDERR stream (as in
load_config). Or it may really be an ABEND condition.</para>
on 1 line. You should, although, provide a good comment on
their functions.</para>
- <para><emphasis>Status:</emphasis> developer-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
</sect3>
<para><emphasis>Explanation:</emphasis></para>
- <para>Create a local stuct (on the stack) if the variable will
+ <para>Create a local struct (on the stack) if the variable will
live and die within the context of one function call.</para>
<para>Only "malloc" a struct (on the heap) if the variable's life
<para><emphasis>Example:</emphasis></para>
<programlisting>
If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.
+list, then it should definitely be allocated via `malloc'.
</programlisting>
</sect3>
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accomodate this.</para>
+ free/unload/destuctor type function to accommodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
functions for C run-time library functions ... such as
`strdup'.</para>
- <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
+ <para><emphasis>Status:</emphasis> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</para>
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- exitinst code, use FIXME</title>
+ existing code, use FIXME</title>
<para><emphasis>Explanation:</emphasis></para>
<para>If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
+ your changes, but are not *quite* sure of the repercussions,
add this:</para>
<para>/* FIXME: this code has a logic error on platform XYZ, *
- attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif</para>
<para>or:</para>
<para><emphasis>Note:</emphasis> If you make it clear that this may or may not
be a "good thing (tm)", it will be easier to identify and
- include in the project (or conversly exclude from the
+ include in the project (or conversely exclude from the
project).</para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<para><emphasis>Note:</emphasis> The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
- skip the verbige and get to the heart of the code (via
+ skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</para>
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
</sect1>
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="cvs"><title>Version Control Guidelines</title>
- <para>To be filled. note on cvs comments. don't comment what you did, comment
-why you did it.
-</para>
- </sect1>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="testing"><title>Testing Guidelines</title>
<para>To be filled.
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="testing-plan"><title>Testplan for releases</title>
<para>
-Explain release numbers. major, minor. developer releases. etc.
+ Explain release numbers. major, minor. developer releases. etc.
<orderedlist numeration="arabic">
<listitem><para>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="newrelease"><title>Releasing a new version</title>
+ <sect1 id="newrelease"><title>Releasing a New Version</title>
<para>
- To minimize trouble with distribution contents, webpage
- errors and the like, I (Stefan) strongly encourage you
- to follow this section if you prepare a new release of
- code or new pages on the webserver.
+ When we release versions of <application>Privoxy</application>,
+ our work leaves our cozy secret lab and has to work in the cold
+ RealWorld[tm]. Once it is released, there is no way to call it
+ back, so it is very important that great care is taken to ensure
+ that everything runs fine, and not to introduce problems in the
+ very last minute.
</para>
+ <para>
+ So when releasing a new version, please adhere exactly to the
+ procedure outlined in this chapter.
+ </para>
+
<para>
The following programs are required to follow this process:
- <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
-<filename>gmake</filename> (GNU's version of make), ???.
+ <filename>ncftpput</filename> (ncftp), <filename>scp, ssh</filename> (ssh),
+ <filename>gmake</filename> (GNU's version of make), autoconf, cvs.
</para>
- <sect2 id="newrelease-web"><title>Update the webserver</title>
- <para>
- All files must be group-readable and group-writable (or no one else
- will be able to change them). To update the webserver, create any
- pages locally in the <filename>doc/webserver</filename> directory (or
- create new directories under <filename>doc/webserver</filename>), then do
- </para>
- <para>
- <programlisting>
- make webserver
- </programlisting>
- </para>
- <para>
- Note that <filename>make dok</filename> creates
- <filename>doc/webserver/user-manual</filename>,
- <filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
- <filename>doc/webserver/man-page</filename> automatically.
- </para>
- <para>
- Verify on the webserver that the permissions are set correctly. Do
- NOT use any other means of transferring files to the webserver.
- </para>
+
+ <para>
+ In the following text, replace X, Y and Z with the actual version number
+ (X = major, Y = minor, Z = point):
+ </para>
+
+ <sect2 id="beforerelease">
+ <title>Before the Release</title>
+ <para>
+ The following <emphasis>must be done by one of the
+ developers</emphasis> prior to each new release.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Make sure that everybody who has worked on the code in the last
+ couple of days has had a chance to yell <quote>no!</quote> in case
+ they have pending changes/fixes in their pipelines.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Increment the version number and increase or reset the RPM release number
+ in <filename>configure.in</filename> as appropriate.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the default <filename>actionsfile</filename> has changed since last
+ release, bump up its version info in this line:
+ </para>
+ <para>
+ <programlisting>
+ {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
+</programlisting>
+ </para>
+ <para>
+ Then change the version info in doc/webserver/actions/index.php,
+ line: '$required_actions_file_version = "A.B";'
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the HTML documentation is not in sync with the SGML sources
+ you need to regenerate it. (If in doubt, just do it.) See the
+ Section "Updating the webserver" in this manual for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Commit all files that were changed in the above steps!</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tag all files in CVS with the version number with
+ <quote><command>cvs tag v_X_Y_Z</command></quote>.
+ Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</sect2>
+
+ <sect2 id="therelease">
+ <title>Building and Releasing the Packages</title>
+ <para>
+ Now the individual packages can be built and released. Note that for
+ GPL reasons the first package to be released is always the source tarball.
+ </para>
+
+ <para>
+ For <emphasis>all</emphasis> types of packages, including the source tarball,
+ <emphasis>you must make sure that you build from clean sources by exporting
+ the right version from CVS into an empty directory:</emphasis>.
+ </para>
+
+ <para>
+ <programlisting>
+ mkdir dist # delete or choose different name if it already exists
+ cd dist
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+</programlisting>
+ </para>
+
+ <para>
+ <emphasis>Do NOT change</emphasis> a single bit, including, but not limited to
+ version information after export from CVS. This is to make sure that
+ all release packages, and with them, all future bug reports, are based
+ on exactly the same code.
+ </para>
+
+ <para>
+ Please find additional instructions for the source tarball and the
+ individual platform dependent binary packages below.
+ </para>
- <sect2 id="newrelease-rpm"><title>SuSE or RedHat</title>
- <para>
- Ensure that you have the latest code version. Hence run
- </para>
- <para>
- <programlisting>
- cvs update .
- </programlisting>
- </para>
- <para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Update the release number
- directly in the specific spec file (particularly, set the release
- number to <filename>1</filename> if you have increased the version
- number before). Run
+ <sect3 id="newrelease-tarball"><title>Source Tarball</title>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
- Then do
+ Then do:
</para>
<para>
<programlisting>
- make suse-dist or make redhat-dist
- </programlisting>
+ make tarball-dist
+</programlisting>
</para>
<para>
To upload the package to Sourceforge, simply issue
</para>
<para>
<programlisting>
- make suse-upload or make redhat-upload
- </programlisting>
+ make tarball-upload
+</programlisting>
</para>
<para>
- Goto the displayed URL and release the file publically on Sourceforge.
+ Go to the displayed URL and release the file publicly on Sourceforge.
+ For the change log field, use the relevant section of the
+ <filename>ChangeLog</filename> file.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-os2"><title>OS/2</title>
- <para>
- Ensure that you have the latest code version. Hence run
- </para>
- <para>
- <programlisting>
- cvs update .
- </programlisting>
- </para>
- <para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
- </sect2>
-
- <sect2 id="newrelease-solaris"><title>Solaris</title>
- <para>
- Login to Sourceforge's compilefarm via ssh
- </para>
- <para>
- <programlisting>
- ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system (not the Debian one). If you have
- downloaded Privoxy before,
+ <sect3 id="newrelease-rpm"><title>SuSE or Red Hat</title>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- cd current && cvs update .
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Verify the version number in
- <filename>configure.in</filename>. If necessary, change the version
- number. Run
+ Then do
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ make suse-dist (or make redhat-dist)
+</programlisting>
</para>
<para>
- Then run
+ To upload the package to Sourceforge, simply issue
</para>
<para>
<programlisting>
- gmake solaris-dist
- </programlisting>
+ make suse-upload (or make redhat-upload)
+</programlisting>
</para>
<para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
- solaris-upload</filename> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publically
- </para>
- </sect2>
+ Go to the displayed URL and release the file publicly on Sourceforge.
+ Use the release notes and çhange log from the source tarball package.
+ </para>
+ </sect3>
- <sect2 id="newrelease-windows"><title>Windows</title>
+ <sect3 id="newrelease-os2"><title>OS/2</title>
<para>
- Ensure that you have the latest code version. Hence run
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then get the OS/2 Setup module:
</para>
<para>
<programlisting>
- cvs update .
- </programlisting>
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+</programlisting>
</para>
<para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
+ You will need a mix of development tools.
+ The main compilation takes place with IBM Visual Age C++.
+ Some ancillary work takes place with GNU tools, available from
+ various sources like hobbes.nmsu.edu.
+ Specificially, you will need <filename>autoheader</filename>,
+ <filename>autoconf</filename> and <filename>sh</filename> tools.
+ The packaging takes place with WarpIN, available from various sources, including
+ its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
</para>
<para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ Change directory to the <filename>os2setup</filename> directory.
+ Edit the os2build.cmd file to set the final executable filename.
+ For example,
</para>
<para>
- Then do FIXME.
- </para>
- </sect2>
-
- <sect2 id="newrelease-debian"><title>Debian</title>
- <para>
- Ensure that you have the latest code version. Hence run
+ <programlisting>
+ installExeName='privoxyos2_setup_X.Y.Z.exe'
+</programlisting>
</para>
<para>
+ Next, edit the <filename>IJB.wis</filename> file so the release number matches
+ in the <filename>PACKAGEID</filename> section:
+ </para>
+ <para>
<programlisting>
- cvs update .
- </programlisting>
+ PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
+</programlisting>
</para>
<para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
+ You're now ready to build. Run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ os2build
+</programlisting>
</para>
<para>
- Then do FIXME.
+ You will find the WarpIN-installable executable in the
+ <filename>./files</filename> directory. Upload this anonymously to
+ <filename>uploads.sourceforge.net/incoming</filename>, create a release
+ for it, and you're done. Use the release notes and Change Log from the
+ source tarball package.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-macosx"><title>Mac OSX</title>
+ <sect3 id="newrelease-solaris"><title>Solaris</title>
<para>
- Login to Sourceforge's compilefarm via ssh
- </para>
- <para>
- <programlisting>
- ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system. If you have downloaded Privoxy
- before,
+ Login to Sourceforge's compilefarm via ssh:
</para>
<para>
<programlisting>
- cd current && cvs update .
- </programlisting>
+ ssh cf.sourceforge.net
+</programlisting>
</para>
<para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Verify the version number in
- <filename>configure.in</filename>. If necessary, change the version
- number. Run
+ Choose the right operating system (not the Debian one).
+ When logged in, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
Then run
</para>
<para>
<programlisting>
- make macosx-dist
- </programlisting>
+ gmake solaris-dist
+</programlisting>
</para>
<para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
- macosx-upload</filename> on the Sourceforge machine (no ncftpput). You now have
+ which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
+ solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publically
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
+ <sect3 id="newrelease-windows"><title>Windows</title>
<para>
- Change the version number of <application>Privoxy</application> in the
- configure.in file. Run
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- Then ...
+ You should ensure you have the latest version of Cygwin (from
+ <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>).
+ Run the following commands from within a Cygwin bash shell.
+ </para>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then get the Windows setup module:
+ </para>
+ <para>
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
+</programlisting>
+ </para>
+ <para>
+ Then you can build the package. This is fully automated, and is
+ controlled by <filename>winsetup/GNUmakefile</filename>.
+ All you need to do is:
+ </para>
+ <para>
+ <programlisting>
+ cd winsetup
+ make
+</programlisting>
</para>
<para>
- Login to Sourceforge's compilefarm via ssh
+ Now you can manually rename <filename>privoxy_setup.exe</filename> to
+ <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
+ SourceForge. When releasing the package on SourceForge, use the release notes
+ and Change Log from the source tarball package.
+ </para>
+ </sect3>
+
+ <sect3 id="newrelease-debian"><title>Debian</title>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then, run:
</para>
<para>
<programlisting>
- ssh cf.sourceforge.net
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
- Choose the right operating system. If you have downloaded Privoxy
- before,
+ Then do FIXME.
+ </para>
+ </sect3>
+
+ <sect3 id="newrelease-macosx"><title>Mac OSX</title>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then get the Mac OSX setup module:
</para>
<para>
<programlisting>
- cd current && cvs update .
- </programlisting>
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
+</programlisting>
</para>
<para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Verify the version number in
- <filename>configure.in</filename>. If necessary, change the version
- number. Run
+ Then run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd osxsetup
+ build
+</programlisting>
</para>
<para>
- Then run
+ This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
+ <filename>configure</filename> as well as <filename>make</filename>.
+ Finally, it will copy over the necessary files to the ./osxsetup/files directory
+ for further processing by <filename>PackageMaker</filename>.
+ </para>
+ <para>
+ Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
+ name to match the release, and hit the "Create package" button.
+ If you specify ./Privoxy.pkg as the output package name, you can then create
+ the distributable zip file with the command:
</para>
<para>
<programlisting>
- make freebsd-dist
- </programlisting>
+zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
+</programlisting>
</para>
<para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
- freebsd-upload</filename> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publically
+ You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
+ <filename>uploads.sourceforge.net/incoming</filename>,
+ create a release for it, and you're done. Use the release notes
+ and Change Log from the source tarball package.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-tarball"><title>Tarball</title>
+ <sect3 id="newrelease-freebsd"><title>FreeBSD</title>
<para>
- Ensure that you have the latest code version. Hence run
+ Login to Sourceforge's compilefarm via ssh:
</para>
<para>
<programlisting>
- cvs update .
- </programlisting>
+ ssh cf.sourceforge.net
+</programlisting>
</para>
<para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
+ Choose the right operating system.
+ When logged in, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- make clobber
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
- Then do
+ Then run:
</para>
<para>
<programlisting>
- make tarball-dist
- </programlisting>
- </para>
- <para>
- To upload the package to Sourceforge, simply issue
+ gmake freebsd-dist
+</programlisting>
</para>
<para>
- <programlisting>
- make tarball-upload
- </programlisting>
+ which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
+ freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
+ to manually upload the archive to Sourceforge's ftp server and release
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
</para>
- <para>
- Goto the displayed URL and release the file publically on Sourceforge.
- </para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
+ <sect3 id="newrelease-hpux"><title>HP-UX 11</title>
<para>
- Ensure that you have the latest code version. Hence run
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- cvs update .
- </programlisting>
- </para>
- <para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
Then do FIXME.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-amiga"><title>Amiga OS</title>
+ <sect3 id="newrelease-amiga"><title>Amiga OS</title>
<para>
- Ensure that you have the latest code version. Hence run
- </para>
- <para>
- <programlisting>
- cvs update .
- </programlisting>
- </para>
- <para>
- first. If necessary, change the version number of
- <application>Privoxy</application> in the
- <filename>configure.in</filename> file. Run
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
Then do FIXME.
</para>
- </sect2>
+ </sect3>
- <sect2 id="newrelease-aix"><title>AIX</title>
+ <sect3 id="newrelease-aix"><title>AIX</title>
<para>
- Login to Sourceforge's compilefarm via ssh
- </para>
- <para>
- <programlisting>
- ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system. If you have downloaded Privoxy
- before,
+ Login to Sourceforge's compilefarm via ssh:
</para>
<para>
<programlisting>
- cd current && cvs update .
- </programlisting>
+ ssh cf.sourceforge.net
+</programlisting>
</para>
<para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Verify the version number in
- <filename>configure.in</filename>. If necessary, change the version
- number. Run
+ Choose the right operating system.
+ When logged in, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above). Then run:
</para>
<para>
<programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
+ cd current
+ autoheader && autoconf && ./configure
+</programlisting>
</para>
<para>
- Then run
+ Then run:
</para>
<para>
<programlisting>
- make aix-dist
- </programlisting>
+ make aix-dist
+</programlisting>
</para>
<para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
- aix-upload</filename> on the Sourceforge machine (no ncftpput). You now have
+ which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
+ aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publically
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
</para>
- </sect2>
+ </sect3>
+ </sect2>
+
+ <sect2 id="releasing">
+ <title>Uploading and Releasing Your Package</title>
+ <para>
+ After the package is ready, it is time to upload it
+ to SourceForge, and go through the release steps. The upload
+ is done via FTP:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Upload to: <ulink url="ftp://upload.sourceforge.net/incoming">ftp://upload.sourceforge.net/incoming</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ user: <literal>anonymous</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ password: <literal>ijbswa-developers@lists.sourceforge.net</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Once this done go to <ulink url="http://sourceforge.net/project/admin/editpackages.php?group_id=11118">http://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
+ making sure you are logged in. Find your target platform in the
+ second column, and click <literal>Add Release</literal>. You will
+ then need to create a new release for your package, using the format
+ of <literal>$VERSION ($CODE_STATUS)</literal>, e.g. <emphasis>&p-version;
+ (beta)</emphasis>.
+ </para>
+ <para>
+ Now just follow the prompts. Be sure to add any appropriate Release
+ notes. You should see your freshly uploaded packages in
+ <quote>Step 2. Add Files To This Release</quote>. Check the
+ appropriate box(es). Remember at each step to hit the
+ <quote>Refresh/Submit</quote> buttons! You should now see your
+ file(s) listed in Step 3. Fill out the forms with the appropriate
+ information for your platform, being sure to hit <quote>Update</quote>
+ for each file. If anyone is monitoring your platform, check the
+ <quote>email</quote> box at the very bottom to notify them of
+ the new package. This should do it!
+ </para>
+ <para>
+ If you have made errors, or need to make changes, you can go through
+ essentially the same steps, but select <literal>Edit Release</literal>,
+ instead of <literal>Add Release</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="afterrelease">
+ <title>After the Release</title>
+ <para>
+ When all (or: most of the) packages have been uploaded and made available,
+ send an email to the <ulink url="mailto:ijbswa-announce@lists.sourceforge.net">announce
+ mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
+ include the
+ <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
+ location</ulink>, the release notes and the change log.
+ </para>
+ </sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="contact"><title>Contact the developers</title>
- <para>Please see the user manual for information on how to contact the developers.
- </para>
+ <sect1 id="webserver-update"><title>Update the Webserver</title>
+ <para>
+ When updating the webserver, please follow these steps to make
+ sure that no broken links, incosistent contents or permission
+ problems will occur:
+ </para>
+ <para>
+ If you have changed anything in the documentation source SGML files,
+ do:
+ </para>
+ <para>
+ <programlisting>
+ make dok # (or make redkat-dok if make dok doesn't work for you)
+</programlisting>
+ </para>
+ <para>
+ That will generate <filename>doc/webserver/user-manual</filename>,
+ <filename>doc/webserver/developer-manual</filename>,
+ <filename>doc/webserver/faq</filename> and
+ <filename>doc/webserver/index.html</filename> automatically.
+ </para>
+ <para>
+ If you changed the manual page source, generate
+ <filename>doc/webserver/man-page/privoxy-man-page.html</filename>
+ by running <quote><command>make man</command></quote>. (This is
+ a separate target due to dependencies on some obscure perl scripts.
+ See comments in <filename>GNUmakefile</filename>.)
+ </para>
+ <para>
+ If you want to add new files to the webserver, create them locally in
+ the <filename>doc/webserver/*</filename> directory (or
+ create new directories under <filename>doc/webserver</filename>).
+ </para>
+ <para>
+ Next, commit any changes from the above steps to CVS. All set? Then do
+ </para>
+ <para>
+ <programlisting>
+ make webserver
+</programlisting>
+ </para>
+ <para>
+ This will do the upload to <ulink url="http://www.privoxy.org/">the
+ webserver</ulink> (www.privoxy.org) and ensure all files and directories
+ there are group writable.
+ </para>
+ <para>
+ Please do <emphasis>NOT</emphasis> use any other means of transferring
+ files to the webserver to avoid permission problems.
+ </para>
+ </sect1>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
+<!-- Include contacting.sgml -->
+ &contacting;
+<!-- end contacting -->
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="copyright"><title>Copyright and History</title>
- <para>Please see the user manual for information on Copyright and History.
- </para>
+
+<sect2><title>Copyright</title>
+<!-- Include copyright.sgml -->
+ ©right;
+<!-- end -->
+</sect2>
+
+<sect2><title>History</title>
+<!-- Include history.sgml -->
+ &history;
+<!-- end -->
+</sect2>
+
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="seealso"><title>See also</title>
- <para>Please see the user manual for information on references.
- </para>
+<!-- Include seealso.sgml -->
+ &seealso;
+<!-- end -->
+
</sect1>
<!--
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.37 2002/04/26 17:23:29 swa
+ bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
+
+ Revision 1.36 2002/04/26 05:25:23 hal9
+ Mass commit to catch a few scattered fixes.
+
+ Revision 1.35 2002/04/17 15:16:15 oes
+ Added link to docbook crash course
+
+ Revision 1.34 2002/04/15 23:39:32 oes
+ - Extended & fixed the release section
+ - Added CVS guideline sections
+ - Separated webserver section from release section
+ - Commented out boilerplate inclusion (If you don't know yet what it is,
+ you shouldn't mess with its code ;-)
+ - Nits & fixes
+
+ Revision 1.33 2002/04/12 03:49:53 hal9
+ Spell checked. Clarification on where docs are kept.
+
+ Revision 1.32 2002/04/11 21:29:58 jongfoster
+ Documenting Win32 release procedure
+
+ Revision 1.31 2002/04/11 09:32:52 oes
+ more nits
+
+ Revision 1.30 2002/04/11 09:24:53 oes
+ nits
+
+ Revision 1.29 2002/04/10 18:45:14 swa
+ generated
+
+ Revision 1.28 2002/04/08 22:59:26 hal9
+ Version update. Spell chkconfig correctly :)
+
+ Revision 1.27 2002/04/08 15:31:18 hal9
+ Touch ups to documentation section.
+
+ Revision 1.26 2002/04/07 23:50:08 hal9
+ Documentation changes to reflect HTML docs now in CVS, and new generated files
+ list.
+
+ Revision 1.25 2002/04/06 05:07:28 hal9
+ -Add privoxy-man-page.sgml, for man page.
+ -Add authors.sgml for AUTHORS (and p-authors.sgml)
+ -Reworked various aspects of various docs.
+ -Added additional comments to sub-docs.
+
+ Revision 1.24 2002/04/04 21:33:37 hal9
+ More on documenting the documents.
+
+ Revision 1.23 2002/04/04 18:46:47 swa
+ consistent look. reuse of copyright, history et. al.
+
+ Revision 1.22 2002/04/04 17:27:56 swa
+ more single file to be included at multiple points. make maintaining easier
+
+ Revision 1.21 2002/04/04 06:48:37 hal9
+ Structural changes to allow for conditional inclusion/exclusion of content
+ based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
+ definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
+ eventually be set by Makefile.
+ More boilerplate text for use across multiple docs.
+
+ Revision 1.20 2002/04/04 03:28:27 david__schmidt
+ Add Mac OSX section
+
+ Revision 1.19 2002/04/03 15:09:42 david__schmidt
+ Add OS/2 build section
+
+ Revision 1.18 2002/04/03 03:51:48 hal9
+ Touch ups.
+
+ Revision 1.17 2002/04/03 01:21:17 hal9
+ Implementing Andreas's suggestions for Release sections.
+
+ Revision 1.16 2002/03/31 23:04:40 hal9
+ Fleshed out the doc section, and added something for an intro so it was not
+ blank.
+
+ Revision 1.15 2002/03/30 22:29:47 swa
+ wrong make flavour
+
+ Revision 1.14 2002/03/30 19:04:08 swa
+ people release differently. no good.
+ I want to make parts of the docs only.
+
Revision 1.13 2002/03/27 01:16:41 hal9
ditto
projects / privoxy.git / blobdiff