X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fdocumentation.html;h=9471cf6cff76fbbebc4134e2fa3349f4e33f5e42;hp=0ab7ad12b3a0d23104b0a283c451db04dfce824c;hb=b47cbf4db0d9e96ddba749f3b44e714f7288443b;hpb=16e9ef297b4cf15a61876abcc794e5a058500e4b diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html index 0ab7ad12..9471cf6c 100644 --- a/doc/webserver/developer-manual/documentation.html +++ b/doc/webserver/developer-manual/documentation.html @@ -1,779 +1,451 @@ -
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, is also now maintained - as SGML. The README in the top-level source - directory is a generated file. DO NOT edit this - directly. Edit the SGML source! -
Other, less formal documents (e.g. AUTHORS, LICENSE) 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. Or HTML versions can be downloaded from the www.privoxy.org website, which - should be fairly current. (This is only a temporary solution.) -
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. -
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.
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>
-
Just to <emphasis>emphasize</emphasis>, some text goes here.
-
Tags should be nested and step indented like: -
<para>
- <itemizedlist>
- <para>
- <listitem>
- Some text goes here in our list example.
- </listitem>
- </para>
- </itemizedlist>
- </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. -
Do not hesitate to make comments. Comments can either use the - <comment> element, or the <!-- --> style comment - familiar from HTML. -
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 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! -
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, INSTALL, 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.
+ +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) + are maintained as plain text files in the top-level 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. HTML versions are also being kept in CVS under doc/webserver/*.
+ +Formal documents are built with the Makefile targets of make dok. 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.
+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. | +
<literallayout></literallayout>, + like <pre>, more or less. | +
<itemizedlist></itemizedlist>, + 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.
+ +You might also find "Writing Documentation Using DocBook - A Crash Course" + useful.
+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 (even small blocks) should be + on their own line. Like:
+ + <para>
+ Some text goes here.
+ </para>
+
+ Just to <emphasis>emphasize</emphasis>, some text goes here.
+
+
Tags should be nested and step indented for block text like: + (except in-line tags)
+ + <para>
+ <itemizedlist>
+ <para>
+ <listitem>
+ Some text goes here in our list example.
+
+ </listitem>
+ </para>
+ </itemizedlist>
+ </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.
+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 :). Humor also does not + translate well sometimes.
+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.
+Our documents are available in differing formats. Right now, + they are just plain text and/or HTML, but others are 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 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 (done by the Makefile). + A sampling of custom entities are listed below. See any of the main + docs for examples.
+ +Re- "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. + "3.0.20". | +
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!
+