X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=a3b878006cfb606459d55383dac989152f2fdf3d;hb=e6e4fa04a6d7c852f266e65313f7a7d09318b846;hp=562a3dfc4d3d0e777953174a7157eb6294eb69a1;hpb=3186134c92fc0a088001a89d17abd5b3486baf2f;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 562a3dfc..a3b87800 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -3,6 +3,16 @@ + + + + + + + + + + ]>
Privoxy Developer Manual - $Id: developer-manual.sgml,v 1.19 2002/04/03 15:09:42 david__schmidt Exp $ + $Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $ @@ -50,17 +69,17 @@ team. It provides guidance on coding, testing, documentation and other issues. - -&p-intro; + + + + &p-intro; + + You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/. - Please see the Contact section of the User Manual on how to contact the - developers. + Please see the Contact section on how to contact the developers. @@ -70,8 +89,18 @@ - - Introduction + + + + + + + + + + + + Introduction - Documentation Guidelines +Documentation Guidelines + + All formal documents are maintained in docbook SGML and located in the + doc/source/* directory. You will need + docbook and the docbook + 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) + files are also now maintained + as SGML. The finished files are all in the top-level source + directory are generated files! Also, index.html, + the Privoxy home page, is maintained + as sgml. DO NOT edit these + directly. Edit the SGML source, or contact someone + involved in the documentation (at present Stefan and Hal). + - All formal documents are maintained in docbook SGML and located - in the doc/source directory. You will - need docbook and the - docbook stylesheets (or comparable alternatives), and either - jade or openjade - installed in order to build docs from source. Currently there is - user-manual, - FAQ, - and, of course this, the developer-manual in - this format. - - - Other, less formal documents (e.g. README, LICENSE) are - maintained as plain text files in the toplevel source - directory. - - - 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. Or HTML versions can be downloaded from the www.privoxy.org website, which - should be fairly current. - - - 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. - - - How do you update the webserver (i.e. the pages on privoxy.org)? - - + Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as + plain text files in the toplevel 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. + + + 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). - - - Run make webserver which copies all files from -doc/webserver to the sourceforge webserver -via scp. - - + + + Run make webserver which copies all + files from doc/webserver to the + sourceforge webserver via scp. + + + + + + +Quickstart to Docbook and SGML + + If you are not familiar with SGML, it is a markup language similar to HTML. + In fact, HTML is an SGML application. Both use tags + to format text and other content. SGML tags are 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 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. + + + <emphasis></emphasis>, stylesheets make this + italics. + + + <filename></filename>, files and directories. + + + <command></command>, command examples. + + + <literallayout></literllayout>, like + <pre>, more or less. + + + <itemizedlist></itemizdelist>, list with bullets. + + + <listitem></listitem>, member of the above. + + + <screen></screen>, screen output, implies + <literallayout>. + + + <ulink url="example.com"></ulink>, like + HTML <a> tag. + + + <quote></quote>, for, doh, quoting text. + + + + + Look at any of the existing docs for examples of all these and more. + + + + + + + + <application>Privoxy</application> Documentation Style + + 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. + + + Here it is: + + + + + + All tags should be lower case. + + + + + Tags delimiting a block of text should be on their + own line. Like: + + <para> + Some text goes here. + </para> + + Tags marking individual words, or few words, should be in-line: + + Just to <emphasis>emphasize</emphasis>, some text goes here. + + + + + + Tags should be nested and step indented like (except in-line tags): + + <para> + <itemizedlist> + <para> + <listitem> + Some text goes here in our list example. + </listitem> + </para> + </itemizedlist> + </para> + + This makes it easier to find the text amongst the tags ;-) + + + + + 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. + + + + + 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>.) + + + + + We have an international audience. Refrain from slang, or English + idiosyncrasies (too many to list :). + + + + + Try to keep overall line lengths in source files to 80 characters or less + for obvious reasons. This is not always possible, with lenghty URLs for + instance. + + + + + 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: + + + My favorite site is <ulink url="http://example.com">here</ulink>. + + + This will render as My favorite site is here, which is + not real helpful in a text doc. Better like this: + + + My favorite site is <ulink url="http://example.com">example.com</ulink>. + + + + + All documents should be spell checked occasionally. + aspell can check SGML with the + -H option. (ispell I think + too.) + + + + + + + + + + + + Privoxy Custom Entities + + Privoxy documentation is using + a number of customized entities to facilitate + documentation maintenance. + + + We are using a set of boilerplate 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 + generic. That is the purpose; so it can be used in varying + contexts without additional modifications. + + + We are also using what Docbook calls + internal entities. These are like variables in + programming. Well, sort of. For instance, we have the + p-version entity that contains the current + Privoxy version string. You are strongly + encouraged to use these where possible. Some of these obviously + require re-setting with each release. A sampling of custom entities are + listed below. See any of the main docs for examples. + + + + + + + Re-cyclable boilerplate text entities are defined like: + + + <!entity supported SYSTEM "supported.sgml"> + + + In this example, the contents of the file, + supported.sgml is available for inclusion anywhere + in the doc. To make this happen, just reference the now defined + entity: &supported; (starts with an ampersand + and ends with a semi-colon), and the contents will be dumped into + the finished doc at that point. + + + + + Commonly used internal entities: + + + + p-version: the Privoxy + version string, e.g. 2.9.13. + + + p-status: the project status, either + ALPHA, BETA, or STABLE. + + + p-not-stable: use to conditionally include + text in not stable releases (e.g. BETA). + + + p-stable: just the opposite. + + + p-text: this doc is only generated as text. + + + + + + + There are others in various places that are defined for a specific + purpose. Read the source! + + + + @@ -1312,7 +1627,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.19 2002/04/03 15:09:42 david__schmidt Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -1372,7 +1687,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.19 2002/04/03 15:09:42 david__schmidt Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $" /********************************************************************* * * File : $Source$ @@ -1713,9 +2028,11 @@ at sourceforge. Three simple steps: os2build - And in the ./files directory you will have the WarpIN-installable executable. - Upload this anonymously to uploads.sourceforge.net/incoming, - create a release for it, and you're done. + And in the ./files directory you will have the + WarpIN-installable executable. + Upload this anonymously to + uploads.sourceforge.net/incoming, create a release + for it, and you're done. @@ -2044,29 +2361,35 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg - Contact the developers - - Please see the contact page in the user-manual for details. - + Contacting the developers, Bug Reporting and Feature Requests + + &contacting; + Copyright and History - - Please see the user-manual for - information on Copyright and History. - + +Copyright + + ©right; + + + +History + + &history; + + + See also - - Please see the user-manual for others - references. - + + &seealso; + +