4 >Documentation Guidelines</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.60"><LINK
9 TITLE="Privoxy Developer Manual"
10 HREF="index.html"><LINK
12 TITLE="Quickstart to Privoxy Development"
13 HREF="quickstart.html"><LINK
15 TITLE="Coding Guidelines"
16 HREF="coding.html"><LINK
19 HREF="../p_doc.css"></HEAD
38 >Privoxy Developer Manual</TH
46 HREF="quickstart.html"
73 >4. Documentation Guidelines</A
76 > All formal documents are maintained in docbook SGML and located in the
78 CLASS="COMPUTEROUTPUT"
80 > directory. You will need
82 HREF="http://www.docbook.org"
86 stylesheets (or comparable alternatives), and either
94 (recommended) installed in order to build docs from source. Currently
96 HREF="../user-manual/index.html"
104 HREF="../faq/index.html"
111 of course this, the <I
118 >, is also now maintained
122 > in the top-level source
123 directory is a generated file. <I
127 >. Edit the SGML source!
130 > Other, less formal documents (e.g. AUTHORS, LICENSE) are maintained as
131 plain text files in the toplevel source directory. At least for the
135 > Packagers are encouraged to include this documentation. For those without
136 the ability to build the docs locally, text versions of each are kept in
137 CVS. Or HTML versions can be downloaded from the <A
138 HREF="http://www.privoxy.org"
142 should be fairly current. (This is only a temporary solution.)
145 > Formal documents are built with the Makefile targets of
147 CLASS="COMPUTEROUTPUT"
151 CLASS="COMPUTEROUTPUT"
153 >. If you have problems,
154 try both. The build process uses the document SGML sources in
156 CLASS="COMPUTEROUTPUT"
158 > to update all text files in
160 CLASS="COMPUTEROUTPUT"
162 > and to update all HTML
164 CLASS="COMPUTEROUTPUT"
169 > Documentation writers should please make sure documents build
170 successfully before committing to CVS.
173 > How do you update the webserver (i.e. the pages on privoxy.org)?
181 > First, build the docs by running <TT
182 CLASS="COMPUTEROUTPUT"
185 > (or alternately <TT
186 CLASS="COMPUTEROUTPUT"
195 CLASS="COMPUTEROUTPUT"
199 CLASS="COMPUTEROUTPUT"
202 sourceforge webserver via scp.
214 >4.1. Quickstart to Docbook and SGML</A
217 > If you are not familiar with SGML, it is a markup language similar to HTML.
218 In fact, HTML is an SGML application. Both use <SPAN
222 to format text and other content. SGML tags are much more varied,
223 and flexible, but do much of the same kinds of things. The tags,
227 >, are definable in SGML. There is no
231 >. Since we are using
235 >, our tags are those that are
240 finish document is rendered is determined by the <SPAN
244 The stylesheets determine how each tag gets translated to HTML, or
247 > Tags in SGML need to be always <SPAN
251 will likely generate errors. Example:
254 ><title>My Title</title></TT
256 also case-insensitive, but we strongly suggest using all lower
257 case. This keeps compatibility with [Docbook] <SPAN
262 > Our documents use <SPAN
265 > for the most part. Sections
266 will be processed into HTML headers (e.g. <TT
277 will use these to also generate the Table of Contents for each doc. Our
278 TOC's are set to a depth of three. Meaning <TT
292 > will not. Each section requires
296 > element, and at least one
300 >. There is a limit of five section
301 levels in Docbook, but generally three should be sufficient for our
304 > Some common elements that you likely will use: </P
314 ><para></para></I
315 >, paragraph delimiter. Most
316 text needs to be within paragraph elements.
323 ><emphasis></emphasis></I
324 >, stylesheets make this
332 ><filename></filename></I
333 >, files and directories.
340 ><command></command></I
348 ><literallayout></literllayout></I
360 ><itemizedlist></itemizdelist></I
361 >, list with bullets.
368 ><listitem></listitem></I
369 >, member of the above.
376 ><screen></screen></I
377 >, screen output, implies
380 ><literallayout></TT
388 ><ulink url="example.com"></ulink></I
400 ><quote></quote></I
401 >, for, doh, quoting text.
409 > Look at any of the existing docs for examples of all these and more.</P
420 > Documentation Style</A
423 > It will be easier if everyone follows a similar writing style. This
424 just makes it easier to read what someone else has written if it
425 is all done in a similar fashion.
436 > All tags should be lower case.
441 > Tags delimiting a block of text should be on their own line.
444 CLASS="LITERALLAYOUT"
445 > <para><br>
446 Some text goes here.<br>
447 </para><br>
448 </P
450 Tags marking individual words, or few words, should be in-line:
452 CLASS="LITERALLAYOUT"
453 > Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
454 </P
460 > Tags should be nested and step indented like:
462 CLASS="LITERALLAYOUT"
463 > <para><br>
464 <itemizedlist><br>
465 <para><br>
466 <listitem><br>
467 Some text goes here in our list example.<br>
468 </listitem><br>
469 </para><br>
470 </itemizedlist><br>
471 </para><br>
472 </P
474 This makes it easier to find the text amongst the tags ;-)
479 > Use white space to separate logical divisions within a document,
480 like between sections. Running everything together consistently
481 makes it harder to read and work on.
486 > Do not hesitate to make comments. Comments can either use the
487 <comment> element, or the <!-- --> style comment
493 > We have an international audience. Refrain from slang, or English
494 idiosyncrasies (too many to list :).
499 > Try to keep overall line lengths in source files to 80 characters or less
500 for obvious reasons. This is not always possible, with lenghty URLs for
506 > Our documents are available in differing formats. Right now, they
507 are just plain text, and HTML, but PDF, and others is always a
508 future possibility. Be careful with URLs (<ulink>), and avoid
512 > My favorite site is <ulink url="http://example.com">here</ulink>.
515 > This will render as <SPAN
517 >"My favorite site is here"</SPAN
519 not real helpful in a text doc. Better like this:
522 > My favorite site is <ulink url="http://example.com">example.com</ulink>.
527 > All documents should be spell checked occasionally.
531 > can check SGML with the
552 >4.3. Privoxy Custom Entities</A
558 > documentation is using
559 a number of customized <SPAN
563 documentation maintenance.
566 > We are using a set of <SPAN
569 > files with generic text,
570 that is used by multiple docs. This way we can write something once, and use
571 it repeatedly without having to re-write the same content over and over again.
572 If editing such a file, keep in mind that it should be
576 >. That is the purpose; so it can be used in varying
577 contexts without additional modifications.
580 > We are also using what <SPAN
586 >"internal entities"</SPAN
587 >. These are like variables in
588 programming. Well, sort of. For instance, we have the
592 > entity that contains the current
596 > version string. You are strongly
597 encouraged to use these where possible. Some of these obviously
598 require re-setting with each release. A sampling of custom entities are
599 listed below. See any of the main docs for examples.
610 > text entities are defined like:
615 ><!entity supported SYSTEM "supported.sgml"></TT
619 > In this example, the contents of the file,
623 > is available for inclusion anywhere
624 in the doc. To make this happen, just reference the now defined
628 > (starts with an ampersand
629 and ends with a semi-colon), and the contents will be dumped into
630 the finished doc at that point.
635 > Commonly used <SPAN
637 >"internal entities"</SPAN
654 version string, e.g. <SPAN
665 >: the project status, either
683 >: use to conditionally include
687 > releases (e.g. <SPAN
698 >: just the opposite.
706 >: this doc is only generated as text.
718 > There are others in various places that are defined for a specific
719 purpose. Read the source!
738 HREF="quickstart.html"
763 >Quickstart to Privoxy Development</TD
773 >Coding Guidelines</TD