X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;ds=inline;f=doc%2Fwebserver%2Fdeveloper-manual%2Fdocumentation.html;h=6346be4e0d38e526bc27a50186351af4fd98d420;hb=2d4220ee5eb5a555f4d9f93fcb4ceac3a0ea379b;hp=1112292b014025f8f5a3ecc896988c2c19c82433;hpb=281c503f6d2799387e2dfac7fccdd3d885c6312e;p=privoxy.git diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html index 1112292b..6346be4e 100644 --- a/doc/webserver/developer-manual/documentation.html +++ b/doc/webserver/developer-manual/documentation.html @@ -1,23 +1,26 @@ + Documentation Guidelines
Prev4. Documentation Guidelines3. Documentation Guidelines

All formal documents are maintained in docbook SGML and located in the - All formal documents are maintained in Docbook SGML and located in the + doc/source/*doc/source/* directory. You will need , AUTHORS +>, + INSTALL, privoxy.1 (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, (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, the +> (and a + variation on this file, privoxy-index.html, + meant for inclusion with doc packages), are maintained as SGML as well. 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). + contact someone involved in the documentation.

Other, less formal documents (e.g. LICENSE, +>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 INSTALL) are maintained as plain text files in the - toplevel source directory. At least for the time being. +>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 now 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/*.

Formal documents are built with the Makefile targets of - make dokmake dok, or alternately - make redhat-dokmake redhat-dok. If you have problems, try both. The build process uses the document SGML sources in - doc/source/*/*doc/source/*/* to update all text files in - doc/text/doc/text/ and to update all HTML - documents in doc/webserver/doc/webserver/.

Documentation writers should please make sure documents build - successfully before committing to CVS. + successfully before committing to CVS, if possible.

How do you update the webserver (i.e. the pages on privoxy.org)? @@ -197,26 +241,30 @@ CLASS="COMPUTEROUTPUT" TYPE="1" >

  • First, build the docs by running First, build the docs by running make - dok (or alternately (or alternately make - redhat-dok). + redhat-dok). For PDF docs, do make + dok-pdf.

  • Run Run make webservermake webserver which copies all - files from doc/webserverdoc/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). +

    4.1. Quickstart to Docbook and SGML3.1. Quickstart to Docbook and SGML

    If you are not familiar with SGML, it is a markup language similar to HTML. @@ -323,110 +395,152 @@ CLASS="LITERAL" >

    Some common elements that you likely will use:

    • Next
    , the stylesheets + make this italics. +
    <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></literllayout><literallayout></literallayout>, like - <pre>, more or less. -
    <itemizedlist></itemizdelist><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.

    4.2. 3.2. Privoxy Documentation Style

  • Tags delimiting a Tags delimiting a block of text (even small blocks) should be on their own line. Like:

  • We have an international audience. Refrain from slang, or English - idiosyncrasies (too many to list :). + 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 lenghty URLs for + 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 HTML, but PDF, and others is always a + are just plain text, HTML, and PDF, but others are always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake:

    4.3. Privoxy Custom Entities3.3. Privoxy Custom Entities

    generic. That is the purpose; so it can be used in varying contexts without additional modifications.

    • Re-cyclable Re- "boilerplate" text entities are defined like: @@ -669,65 +790,80 @@ BORDER="0" > p-version: the Privoxy version string, e.g. "2.9.13""3.0.17". p-status: the project status, either "ALPHA""alpha", "BETA""beta", or "STABLE""stable". p-not-stable: use to conditionally include text in "not stable" releases (e.g. "BETA""beta"). p-stable: just the opposite. p-text: this doc is only generated as text.

      PrevQuickstart to Privoxy DevelopmentThe CVS Repository
      HomeNext