X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fdocumentation.html;h=bf25e6c2ccd2c955f29fb7eb5414c46811f4c04d;hp=f1bfe610969b1b7ac9f4b2ae1e81e9850b84f62a;hb=7ecdaff4e6e989eaa70d1ffec88c0e5dfbeb19bb;hpb=5700aead3098beb0cc5a02bc0034a0d4194774a6 diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html index f1bfe610..bf25e6c2 100644 --- a/doc/webserver/developer-manual/documentation.html +++ b/doc/webserver/developer-manual/documentation.html @@ -89,7 +89,7 @@ CLASS="COMPUTEROUTPUT" HREF="http://www.docbook.org" TARGET="_top" >Docbook, the Docbook +>, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), and either index.html (and a +> (and a variation on this file, privoxy-index.html, +>, meant for inclusion with doc packages), are maintained as SGML as well. user-manual. But the conversion - process requires going from SGML to HTML to text to special formatting +>. 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

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 being kept in CVS under + CVS. HTML versions are also being kept in CVS under doc/webserver/*. And PDF version are kept in - doc/pdf/*.

make dok, or alternately - make redhat-dok. If you have problems, - try both. The build process uses the document SGML sources in +>. + The build process uses the document SGML sources in doc/source/*/*

How do you update the webserver (i.e. the pages on privoxy.org)? - -

    make dok (or alternately make - redhat-dok). For PDF docs, do make - dok-pdf.

-

Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html) so that those without +>) 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 3.1. Quickstart to Docbook and SGML

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 +> 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 Docbook, our tags are those that are defined by +>, our tags are those that are defined by Docbookh1 for +> for sect1Docbook stylesheets - will use these to also generate the Table of Contents for each doc. Our + 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 +> will have TOC entries, but sect4 will not. Each section requires +> will not. Each section requires a <title> element, and at least one +> element, and at least one <para>. There is a limit of five section - levels in Docbook, but generally three should be sufficient for our +>. 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:

Some common elements that you likely will use:

<para></para>, paragraph delimiter. Most +>, paragraph delimiter. Most text needs to be within paragraph elements (there are some exceptions). <literallayout></literallayout>, like +>, like <pre><screen></screen>, screen output, implies +>, screen output, implies <literallayout><ulink url="example.com"></ulink>, like +>, like HTML <a><quote></quote>, for, doh, quoting text. +>, for, doh, quoting text.

Look at any of the existing docs for examples of all these and more.

You might also find You might also find + + "Writing Documentation - Using DocBook - A Crash Course Writing Documentation Using DocBook - A Crash Course" useful.

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 +> 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:

-

3.3. Privoxy Custom Entities

Privoxy documentation is using +> documentation is using a number of customized "entities" to facilitate - documentation maintenance. +> to facilitate + documentation maintenance.

We are using a set of generic. That is the purpose; so it can be used in varying +>. That is the purpose; so it can be used in varying contexts without additional modifications.

We are also using what Docbook calls +> calls "internal entities". These are like variables in +>. These are like variables in programming. Well, sort of. For instance, we have the p-version entity that contains the current +> entity that contains the current Privoxy version string. You are strongly - encouraged to use these where possible. Some of these obviously +> 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.

  • supported.sgml is available for inclusion anywhere - in the doc. To make this happen, just reference the now defined +> 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 +> (starts with an ampersand + and ends with a semi-colon), and the contents will be dumped into the finished doc at that point.

    • : the Privoxy +> version string, e.g. "3.0.18""3.0.27". p-status: the project status, either +>: the project status, either "alpha"p-not-stable: use to conditionally include +>: use to conditionally include text in "not stable"

-

There are others in various places that are defined for a specific +> There are others in various places that are defined for a specific purpose. Read the source!

+> \ No newline at end of file