All formal documents are maintained in Docbook SGML and located in the doc/source/* directory. You will need Docbook, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), and either jade or openjade (recommended) installed in order to build docs from source. Currently there is user-manual, FAQ, and, of course this, the developer-manual in this format. The README, AUTHORS privoxy.1 (man page), and config files are also now maintained as Docbook SGML. These files, when built, in the top-level source directory are generated files! Also, the Privoxy index.html (and a variation on this file, privoxy-index.html, meant for inclusion with doc packages), are maintained as SGML as well. DO NOT edit these directly. Edit the SGML source, or contact someone involved in the documentation (at present Hal).
config requires some special handling. The reason it is maintained this way is so that the extensive comments in the file mirror those in user-manual. But the conversion process requires going from SGML to HTML to text to special formatting required for the embedded comments. Some of this does not survive so well. Especially some of the examples that are longer than 80 characters. The build process for this file outputs to config.new, which should be reviewed for errors and mis-formatting. Once satisfied that it is correct, then it should be hand copied to config.
Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as plain text files in the top-level source directory. At least for the time being.
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 doc/webserver/*.
Formal documents are built with the Makefile targets of make dok, or alternately make redhat-dok. If you have problems, try both. The build process uses the document SGML sources in doc/source/*/* to update all text files in doc/text/ and to update all HTML documents in doc/webserver/.
Documentation writers should please make sure documents build successfully before committing to CVS, if possible.
How do you update the webserver (i.e. the pages on privoxy.org)?
First, build the docs by running make dok (or alternately make redhat-dok). For PDF docs, do make dok-pdf.
Run make webserver which copies all files from doc/webserver to the sourceforge webserver via scp.
Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html) 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 after the $VERSION and other release specific data in configure.in has been updated (this is done just prior to a new release).
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 "tags" 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 "elements", are definable in SGML. There is no set "standards". Since we are using Docbook, our tags are those that are defined by Docbook. Much of how the finish document is rendered is determined by the "stylesheets". The stylesheets determine how each tag gets translated to HTML, or other formats.
Tags in Docbook SGML need to be always "closed". If not, you will likely generate errors. Example: <title>My Title</title>. They are also case-insensitive, but we strongly suggest using all lower case. This keeps compatibility with [Docbook] XML.
Our documents use "sections" for the most part. Sections will be processed into HTML headers (e.g. h1 for sect1). The Docbook 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 sect1, sect2, and sect3 will have TOC entries, but sect4 will not. Each section requires a <title> element, and at least one <para>. There is a limit of five section levels in Docbook, but generally three should be sufficient for our purposes.
Some common elements that you likely will use:
| <para></para>, paragraph delimiter. Most text needs to be within paragraph elements (there are some exceptions). |
| <emphasis></emphasis>, the stylesheets make this italics. |
| <filename></filename>, files and directories. |
| <command></command>, command examples. |
<literallayou Forge.
Please refer to the chapters 6 and 7 in
SF's site
documentation for the technical access details for your
operating system. For historical reasons, the CVS server is
called cvs.ijbswa.sourceforge.net, the repository is
called ijbswa, and the source tree module is called
current.
2.2. BranchesWithin the CVS repository, there are modules and branches. As mentioned, the sources are in the current "module". Other modules are present for platform specific issues. There is a webview of the CVS hierarchy at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/, which might help with visualizing how these pieces fit together. Branches are used to fork a sub-development path from the main trunk. Within the current module where the sources are, there is always at least one "branch" from the main trunk devoted to a stable release series. The main trunk is where active development takes place for the next stable series (e.g. 3.2.x). So just prior to each stable series (e.g. 3.0.x), a branch is created just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable release of any stable branch has taken place, this branch is only used for bugfixes, which have had prior testing before being committed to CVS. (See Version Numbers below for details on versioning.) This will result in at least two active branches, which means there may be occasions that require the same (or similar) item to be checked into to two different places (assuming its a bugfix and needs fixing in both the stable and unstable trees). This also means that in order to have access to both trees, both will have to be checked out separately. Use the cvs -r flag to check out a branch, e.g: cvs co -r v_3_0_branch current. 2.3. CVS Commit GuidelinesThe 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. There are differing guidelines for the stable branch and the main development trunk, and we ask anyone with CVS access to strictly adhere to the following guidelines: Basic Guidelines, for all branches:
Stable branches are handled with more care, especially after the initial *.*.0 release, and we are just in bugfix mode. In addition to the above, the below applies only to the stable branch (currently the v_3_0_branch branch):
|