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="The CVS Repository"
15 TITLE="Coding Guidelines"
16 HREF="coding.html"><LINK
19 HREF="../p_doc.css"></HEAD
38 >Privoxy Developer Manual</TH
73 >3. 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 DTD's and the Docbook modular stylesheets (or comparable alternatives),
94 > (recommended) installed in order to
95 build docs from source. Currently there is <A
96 HREF="../user-manual/index.html"
104 HREF="../faq/index.html"
129 > files are also now maintained as Docbook
130 SGML. These files, when built, in the top-level source directory are
131 generated files! Also, the <SPAN
138 variation on this file, <TT
140 >privoxy-index.html</TT
142 meant for inclusion with doc packages), are maintained as SGML as well.
145 >DO NOT edit these directly</I
146 >. Edit the SGML source, or
147 contact someone involved in the documentation (at present Stefan and
154 > requires some special handling. The reason it
155 is maintained this way is so that the extensive comments in the file
159 >. But the conversion
160 process requires going from SGML to HTML to text to special formatting
161 required for the embedded comments. Some of this does not survive so
162 well. Especially some of the examples that are longer than 80 characters.
163 The build process for this file outputs to <TT
167 which should be reviewed for errors and mis-formatting. Once satisfied
168 that it is correct, then it should be hand copied to
176 > Other, less formal documents (e.g. <TT
183 >) are maintained as plain text files in the
184 top-level source directory. At least for the time being.
187 > Packagers are encouraged to include this documentation. For those without
188 the ability to build the docs locally, text versions of each are kept in
189 CVS. HTML versions are also now being kept in CVS under
196 > Formal documents are built with the Makefile targets of
198 CLASS="COMPUTEROUTPUT"
202 CLASS="COMPUTEROUTPUT"
204 >. If you have problems,
205 try both. The build process uses the document SGML sources in
207 CLASS="COMPUTEROUTPUT"
209 > to update all text files in
211 CLASS="COMPUTEROUTPUT"
213 > and to update all HTML
215 CLASS="COMPUTEROUTPUT"
220 > Documentation writers should please make sure documents build
221 successfully before committing to CVS, if possible.
224 > How do you update the webserver (i.e. the pages on privoxy.org)?
232 > First, build the docs by running <TT
233 CLASS="COMPUTEROUTPUT"
236 > (or alternately <TT
237 CLASS="COMPUTEROUTPUT"
246 CLASS="COMPUTEROUTPUT"
250 CLASS="COMPUTEROUTPUT"
253 sourceforge webserver via scp.
260 > Finished docs should be occasionally submitted to CVS
263 >doc/webserver/*/*.html</TT
264 >) so that those without
265 the ability to build them locally, have access to them if needed.
266 This is especially important just prior to a new release! Please
274 other release specific data in <TT
278 updated (this is done just prior to a new release).
286 >3.1. Quickstart to Docbook and SGML</A
289 > If you are not familiar with SGML, it is a markup language similar to HTML.
290 Actually, not a mark up language per se, but a language used to define
291 markup languages. In fact, HTML is an SGML application. Both will use
295 > to format text and other content. SGML tags can be much
296 more varied, and flexible, but do much of the same kinds of things. The tags,
300 >, are definable in SGML. There is no set
304 >. Since we are using
308 >, our tags are those that are defined by
312 >. Much of how the finish document is
313 rendered is determined by the <SPAN
317 The stylesheets determine how each tag gets translated to HTML, or other
320 > Tags in Docbook SGML need to be always <SPAN
324 will likely generate errors. Example: <TT
327 Title</title></TT
328 >. They are also case-insensitive, but we
329 strongly suggest using all lower case. This keeps compatibility with
335 > Our documents use <SPAN
338 > for the most part. Sections
339 will be processed into HTML headers (e.g. <TT
350 will use these to also generate the Table of Contents for each doc. Our
351 TOC's are set to a depth of three. Meaning <TT
365 > will not. Each section requires
369 > element, and at least one
373 >. There is a limit of five section
374 levels in Docbook, but generally three should be sufficient for our
377 > Some common elements that you likely will use: </P
388 ><para></para></I
389 >, paragraph delimiter. Most
390 text needs to be within paragraph elements (there are some exceptions).
397 ><emphasis></emphasis></I
406 ><filename></filename></I
407 >, files and directories.
414 ><command></command></I
422 ><literallayout></literallayout></I
434 ><itemizedlist></itemizedlist></I
435 >, list with bullets.
442 ><listitem></listitem></I
443 >, member of the above.
450 ><screen></screen></I
451 >, screen output, implies
454 ><literallayout></TT
462 ><ulink url="example.com"></ulink></I
474 ><quote></quote></I
475 >, for, doh, quoting text.
484 > Look at any of the existing docs for examples of all these and more.</P
486 > You might also find <SPAN
489 HREF="http://www.bureau-cornavin.com/opensource/crash-course/"
491 >Writing Documentation
492 Using DocBook - A Crash Course</A
505 > Documentation Style</A
508 > It will be easier if everyone follows a similar writing style. This
509 just makes it easier to read what someone else has written if it
510 is all done in a similar fashion.
521 > All tags should be lower case.
526 > Tags delimiting a <I
529 > of text (even small
530 blocks) should be on their own line. Like:
532 CLASS="LITERALLAYOUT"
533 > <para><br>
534 Some text goes here.<br>
535 </para><br>
536 </P
538 Tags marking individual words, or few words, should be in-line:
540 CLASS="LITERALLAYOUT"
541 > Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
542 </P
548 > Tags should be nested and step indented for block text like: (except
551 CLASS="LITERALLAYOUT"
552 > <para><br>
553 <itemizedlist><br>
554 <para><br>
555 <listitem><br>
556 Some text goes here in our list example.<br>
557 </listitem><br>
558 </para><br>
559 </itemizedlist><br>
560 </para><br>
561 </P
563 This makes it easier to find the text amongst the tags ;-)
568 > Use white space to separate logical divisions within a document,
569 like between sections. Running everything together consistently
570 makes it harder to read and work on.
575 > Do not hesitate to make comments. Comments can either use the
576 <comment> element, or the <!-- --> style comment
577 familiar from HTML. (Note in Docbook v4.x <comment> is
578 replaced by <remark>.)
583 > We have an international audience. Refrain from slang, or English
584 idiosyncrasies (too many to list :). Humor also does not translate
590 > Try to keep overall line lengths in source files to 80 characters or less
591 for obvious reasons. This is not always possible, with lengthy URLs for
597 > Our documents are available in differing formats. Right now, they
598 are just plain text, and HTML, but PDF, and others is always a
599 future possibility. Be careful with URLs (<ulink>), and avoid
603 > My favorite site is <ulink url="http://example.com">here</ulink>.
606 > This will render as <SPAN
608 >"My favorite site is here"</SPAN
610 not real helpful in a text doc. Better like this:
613 > My favorite site is <ulink url="http://example.com">example.com</ulink>.
618 > All documents should be spell checked occasionally.
622 > can check SGML with the
643 >3.3. Privoxy Custom Entities</A
649 > documentation is using
650 a number of customized <SPAN
654 documentation maintenance.
657 > We are using a set of <SPAN
660 > files with generic text,
661 that is used by multiple docs. This way we can write something once, and use
662 it repeatedly without having to re-write the same content over and over again.
663 If editing such a file, keep in mind that it should be
667 >. That is the purpose; so it can be used in varying
668 contexts without additional modifications.
671 > We are also using what <SPAN
677 >"internal entities"</SPAN
678 >. These are like variables in
679 programming. Well, sort of. For instance, we have the
683 > entity that contains the current
687 > version string. You are strongly
688 encouraged to use these where possible. Some of these obviously
689 require re-setting with each release (done by the Makefile). A sampling of
690 custom entities are listed below. See any of the main docs for examples.
701 > text entities are defined like:
706 ><!entity supported SYSTEM "supported.sgml"></TT
710 > In this example, the contents of the file,
714 > is available for inclusion anywhere
715 in the doc. To make this happen, just reference the now defined
719 > (starts with an ampersand
720 and ends with a semi-colon), and the contents will be dumped into
721 the finished doc at that point.
726 > Commonly used <SPAN
728 >"internal entities"</SPAN
745 version string, e.g. <SPAN
756 >: the project status, either
774 >: use to conditionally include
778 > releases (e.g. <SPAN
789 >: just the opposite.
797 >: this doc is only generated as text.
809 > There are others in various places that are defined for a specific
810 purpose. Read the source!
854 >The CVS Repository</TD
864 >Coding Guidelines</TD