HREF="http://www.docbook.org"
TARGET="_top"
>Docbook</A
->, the Docbook
+>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
and either <SPAN
CLASS="APPLICATION"
> <TT
CLASS="FILENAME"
>index.html</TT
-> (and a
+> (and a
variation on this file, <TT
CLASS="FILENAME"
>privoxy-index.html</TT
->,
+>,
meant for inclusion with doc packages), are maintained as SGML as well.
<SPAN
CLASS="emphasis"
mirror those in <I
CLASS="CITETITLE"
>user-manual</I
->. 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 <TT
CLASS="FILENAME"
>config.new</TT
->,
+>,
which should be reviewed for errors and mis-formatting. Once satisfied
that it is correct, then it should be hand copied to
<TT
><P
> 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
<TT
CLASS="FILENAME"
>doc/webserver/*</TT
->. And PDF version are kept in
- <TT
-CLASS="FILENAME"
->doc/pdf/*</TT
>.
</P
><P
<SAMP
CLASS="COMPUTEROUTPUT"
>make dok</SAMP
->, or alternately
- <SAMP
-CLASS="COMPUTEROUTPUT"
->make redhat-dok</SAMP
->. If you have problems,
- try both. The build process uses the document SGML sources in
+>.
+ The build process uses the document SGML sources in
<SAMP
CLASS="COMPUTEROUTPUT"
>doc/source/*/*</SAMP
</P
><P
> How do you update the webserver (i.e. the pages on privoxy.org)?
-
+ </P
></P
><OL
TYPE="1"
CLASS="COMPUTEROUTPUT"
>make
dok</SAMP
-> (or alternately <SAMP
-CLASS="COMPUTEROUTPUT"
->make
- redhat-dok</SAMP
->). For PDF docs, do <SAMP
-CLASS="COMPUTEROUTPUT"
->make
- dok-pdf</SAMP
>.
</P
></LI
</P
></LI
></OL
->
- </P
><P
> Finished docs should be occasionally submitted to CVS
(<TT
CLASS="FILENAME"
>doc/webserver/*/*.html</TT
->) 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 <SPAN
>3.1. Quickstart to Docbook and SGML</A
></H2
><P
-> 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
<SPAN
CLASS="QUOTE"
<SPAN
CLASS="APPLICATION"
>Docbook</SPAN
->, our tags are those that are defined by
+>, our tags are those that are defined by
<SPAN
CLASS="APPLICATION"
>Docbook</SPAN
will be processed into HTML headers (e.g. <TT
CLASS="LITERAL"
>h1</TT
-> for
+> for
<TT
CLASS="LITERAL"
>sect1</TT
CLASS="APPLICATION"
>Docbook</SPAN
> 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 <TT
CLASS="LITERAL"
>sect1</TT
->,
+>,
<TT
CLASS="LITERAL"
>sect2</TT
>, and <TT
CLASS="LITERAL"
>sect3</TT
-> will have TOC
+> will have TOC
entries, but <TT
CLASS="LITERAL"
>sect4</TT
-> will not. Each section requires
+> will not. Each section requires
a <TT
CLASS="LITERAL"
><title></TT
-> element, and at least one
+> element, and at least one
<TT
CLASS="LITERAL"
><para></TT
->. 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.</P
><P
-> Some common elements that you likely will use: </P
+> Some common elements that you likely will use:</P
><P
-> <P
></P
><TABLE
BORDER="0"
CLASS="EMPHASIS"
><para></para></I
></SPAN
->, paragraph delimiter. Most
+>, paragraph delimiter. Most
text needs to be within paragraph elements (there are some exceptions).
</TD
></TR
CLASS="EMPHASIS"
><literallayout></literallayout></I
></SPAN
->, like
+>, like
<TT
CLASS="LITERAL"
><pre></TT
CLASS="EMPHASIS"
><screen></screen></I
></SPAN
->, screen output, implies
+>, screen output, implies
<TT
CLASS="LITERAL"
><literallayout></TT
CLASS="EMPHASIS"
><ulink url="example.com"></ulink></I
></SPAN
->, like
+>, like
HTML <TT
CLASS="LITERAL"
><a></TT
CLASS="EMPHASIS"
><quote></quote></I
></SPAN
->, for, doh, quoting text.
+>, for, doh, quoting text.
</TD
></TR
></TBODY
></TABLE
><P
></P
-></P
><P
> Look at any of the existing docs for examples of all these and more.</P
><P
-> You might also find <SPAN
+> You might also find
+
+ <SPAN
CLASS="QUOTE"
>"<A
-HREF="http://opensource.bureau-cornavin.com/crash-course/index.html"
+HREF="https://web.archive.org/web/20160315230758/http://opensource.bureau-cornavin.com/crash-course/index.html"
TARGET="_top"
->Writing Documentation
- Using DocBook - A Crash Course</A
+> Writing Documentation Using DocBook - A Crash Course</A
>"</SPAN
> useful.</P
></DIV
> Documentation Style</A
></H2
><P
-> 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.
</P
><P
> Here it is:
</P
><P
-> <P
></P
><UL
><LI
></SPAN
> of text (even small
blocks) should be on their own line. Like:
- <P
+ </P
+><P
CLASS="LITERALLAYOUT"
> <para><br>
Some text goes here.<br>
</para><br>
</P
->
- Tags marking individual words, or few words, should be in-line:
- <P
+><P
+> Tags marking individual words, or few words, should be in-line:
+ </P
+><P
CLASS="LITERALLAYOUT"
> Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
</P
->
- </P
></LI
><LI
><P
> Tags should be nested and step indented for block text like: (except
- in-line tags)
- <P
+ in-line tags)
+ </P
+><P
CLASS="LITERALLAYOUT"
> <para><br>
<itemizedlist><br>
</itemizedlist><br>
</para><br>
</P
->
- This makes it easier to find the text amongst the tags ;-)
+><P
+> This makes it easier to find the text amongst the tags ;-)
</P
></LI
><LI
><P
-> Use white space to separate logical divisions within a document,
- like between sections. Running everything together consistently
+> 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.
</P
></LI
><LI
><P
-> 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
+> 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>.)
</P
></LI
><LI
><P
-> We have an international audience. Refrain from slang, or English
- idiosyncrasies (too many to list :). Humor also does not translate
+> We have an international audience. Refrain from slang, or English
+ idiosyncrasies (too many to list :). Humor also does not translate
well sometimes.
</P
></LI
></LI
><LI
><P
-> Our documents are available in differing formats. Right now, they
- are just plain text, HTML, and PDF, but others are always a
- future possibility. Be careful with URLs (<ulink>), and avoid
+> 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:
</P
><P
> This will render as <SPAN
CLASS="QUOTE"
>"My favorite site is here"</SPAN
->, which is
+>, which is
not real helpful in a text doc. Better like this:
</P
><P
</P
></LI
></UL
->
- </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
-NAME="AEN217"
+NAME="AEN205"
>3.3. Privoxy Custom Entities</A
></H2
><P
> <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> documentation is using
+> documentation is using
a number of customized <SPAN
CLASS="QUOTE"
>"entities"</SPAN
-> to facilitate
- documentation maintenance.
+> to facilitate
+ documentation maintenance.
</P
><P
> We are using a set of <SPAN
CLASS="EMPHASIS"
>generic</I
></SPAN
->. 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.
</P
><P
> We are also using what <SPAN
CLASS="APPLICATION"
>Docbook</SPAN
-> calls
+> calls
<SPAN
CLASS="QUOTE"
>"internal entities"</SPAN
->. These are like variables in
+>. These are like variables in
programming. Well, sort of. For instance, we have the
<TT
CLASS="LITERAL"
>p-version</TT
-> entity that contains the current
+> entity that contains the current
<SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> 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.
</P
><P
-> <P
></P
><UL
><LI
<TT
CLASS="FILENAME"
>supported.sgml</TT
-> 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: <TT
CLASS="LITERAL"
>&supported;</TT
-> (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.
</P
></LI
>: the <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
->
+>
version string, e.g. <SPAN
CLASS="QUOTE"
->"3.0.8"</SPAN
+>"3.0.27"</SPAN
>.
</TD
></TR
CLASS="EMPHASIS"
>p-status</I
></SPAN
->: the project status, either
+>: the project status, either
<SPAN
CLASS="QUOTE"
>"alpha"</SPAN
CLASS="EMPHASIS"
>p-not-stable</I
></SPAN
->: use to conditionally include
+>: use to conditionally include
text in <SPAN
CLASS="QUOTE"
>"not stable"</SPAN
></P
></LI
></UL
->
- </P
><P
-> 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!
</P
></DIV
projects / privoxy.git / blobdiff