1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5 >Documentation Guidelines</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
13 TITLE="The CVS Repository"
16 TITLE="Coding Guidelines"
17 HREF="coding.html"><LINK
20 HREF="../p_doc.css"></HEAD
31 SUMMARY="Header navigation table"
40 >Privoxy Developer Manual</TH
77 >3. Documentation Guidelines</A
80 > All formal documents are maintained in Docbook SGML and located in the
82 CLASS="COMPUTEROUTPUT"
84 > directory. You will need
86 HREF="http://www.docbook.org"
90 DTD's and the Docbook modular stylesheets (or comparable alternatives),
98 > (recommended) installed in order to
99 build docs from source. Currently there is <A
100 HREF="../user-manual/index.html"
108 HREF="../faq/index.html"
133 > files are also now maintained as Docbook
134 SGML. These files, when built, in the top-level source directory are
135 generated files! Also, the <SPAN
142 variation on this file, <TT
144 >privoxy-index.html</TT
146 meant for inclusion with doc packages), are maintained as SGML as well.
151 >DO NOT edit these directly</I
153 >. Edit the SGML source, or
154 contact someone involved in the documentation (at present Hal).
160 > requires some special handling. The reason it
161 is maintained this way is so that the extensive comments in the file
165 >. But the conversion
166 process requires going from SGML to HTML to text to special formatting
167 required for the embedded comments. Some of this does not survive so
168 well. Especially some of the examples that are longer than 80 characters.
169 The build process for this file outputs to <TT
173 which should be reviewed for errors and mis-formatting. Once satisfied
174 that it is correct, then it should be hand copied to
181 > Other, less formal documents (e.g. <TT
188 >) are maintained as plain text files in the
189 top-level source directory. At least for the time being.
192 > Packagers are encouraged to include this documentation. For those without
193 the ability to build the docs locally, text versions of each are kept in
194 CVS. HTML versions are also now being kept in CVS under
201 > Formal documents are built with the Makefile targets of
203 CLASS="COMPUTEROUTPUT"
207 CLASS="COMPUTEROUTPUT"
208 >make redhat-dok</SAMP
209 >. If you have problems,
210 try both. The build process uses the document SGML sources in
212 CLASS="COMPUTEROUTPUT"
213 >doc/source/*/*</SAMP
214 > to update all text files in
216 CLASS="COMPUTEROUTPUT"
218 > and to update all HTML
220 CLASS="COMPUTEROUTPUT"
221 >doc/webserver/</SAMP
225 > Documentation writers should please make sure documents build
226 successfully before committing to CVS, if possible.
229 > How do you update the webserver (i.e. the pages on privoxy.org)?
237 > First, build the docs by running <SAMP
238 CLASS="COMPUTEROUTPUT"
241 > (or alternately <SAMP
242 CLASS="COMPUTEROUTPUT"
245 >). For PDF docs, do <SAMP
246 CLASS="COMPUTEROUTPUT"
255 CLASS="COMPUTEROUTPUT"
256 >make webserver</SAMP
259 CLASS="COMPUTEROUTPUT"
262 sourceforge webserver via scp.
269 > Finished docs should be occasionally submitted to CVS
272 >doc/webserver/*/*.html</TT
273 >) so that those without
274 the ability to build them locally, have access to them if needed.
275 This is especially important just prior to a new release! Please
286 other release specific data in <TT
290 updated (this is done just prior to a new release).
298 >3.1. Quickstart to Docbook and SGML</A
301 > If you are not familiar with SGML, it is a markup language similar to HTML.
302 Actually, not a mark up language per se, but a language used to define
303 markup languages. In fact, HTML is an SGML application. Both will use
307 > to format text and other content. SGML tags can be much
308 more varied, and flexible, but do much of the same kinds of things. The tags,
312 >, are definable in SGML. There is no set
316 >. Since we are using
320 >, our tags are those that are defined by
324 >. Much of how the finish document is
325 rendered is determined by the <SPAN
329 The stylesheets determine how each tag gets translated to HTML, or other
332 > Tags in Docbook SGML need to be always <SPAN
336 will likely generate errors. Example: <VAR
339 Title</title></VAR
340 >. They are also case-insensitive, but we
341 strongly suggest using all lower case. This keeps compatibility with
347 > Our documents use <SPAN
350 > for the most part. Sections
351 will be processed into HTML headers (e.g. <VAR
362 will use these to also generate the Table of Contents for each doc. Our
363 TOC's are set to a depth of three. Meaning <VAR
377 > will not. Each section requires
380 ><title></VAR
381 > element, and at least one
385 >. There is a limit of five section
386 levels in Docbook, but generally three should be sufficient for our
389 > Some common elements that you likely will use: </P
402 ><para></para></I
404 >, paragraph delimiter. Most
405 text needs to be within paragraph elements (there are some exceptions).
414 ><emphasis></emphasis></I
426 ><filename></filename></I
428 >, files and directories.
437 ><command></command></I
448 ><literallayout></literallayout></I
463 ><itemizedlist></itemizedlist></I
465 >, list with bullets.
474 ><listitem></listitem></I
476 >, member of the above.
485 ><screen></screen></I
487 >, screen output, implies
490 ><literallayout></VAR
500 ><ulink url="example.com"></ulink></I
515 ><quote></quote></I
517 >, for, doh, quoting text.
526 > Look at any of the existing docs for examples of all these and more.</P
528 > You might also find <SPAN
531 HREF="http://www.bureau-cornavin.com/opensource/crash-course/"
533 >Writing Documentation
534 Using DocBook - A Crash Course</A
547 > Documentation Style</A
550 > It will be easier if everyone follows a similar writing style. This
551 just makes it easier to read what someone else has written if it
552 is all done in a similar fashion.
563 > All tags should be lower case.
568 > Tags delimiting a <SPAN
574 > of text (even small
575 blocks) should be on their own line. Like:
577 CLASS="LITERALLAYOUT"
578 > <para><br>
579 Some text goes here.<br>
580 </para><br>
581 </P
583 Tags marking individual words, or few words, should be in-line:
585 CLASS="LITERALLAYOUT"
586 > Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
587 </P
593 > Tags should be nested and step indented for block text like: (except
596 CLASS="LITERALLAYOUT"
597 > <para><br>
598 <itemizedlist><br>
599 <para><br>
600 <listitem><br>
601 Some text goes here in our list example.<br>
602 </listitem><br>
603 </para><br>
604 </itemizedlist><br>
605 </para><br>
606 </P
608 This makes it easier to find the text amongst the tags ;-)
613 > Use white space to separate logical divisions within a document,
614 like between sections. Running everything together consistently
615 makes it harder to read and work on.
620 > Do not hesitate to make comments. Comments can either use the
621 <comment> element, or the <!-- --> style comment
622 familiar from HTML. (Note in Docbook v4.x <comment> is
623 replaced by <remark>.)
628 > We have an international audience. Refrain from slang, or English
629 idiosyncrasies (too many to list :). Humor also does not translate
635 > Try to keep overall line lengths in source files to 80 characters or less
636 for obvious reasons. This is not always possible, with lengthy URLs for
642 > Our documents are available in differing formats. Right now, they
643 are just plain text, TML, and PDF, but others are always a
644 future possibility. Be careful with URLs (<ulink>), and avoid
648 > My favorite site is <ulink url="http://example.com">here</ulink>.
651 > This will render as <SPAN
653 >"My favorite site is here"</SPAN
655 not real helpful in a text doc. Better like this:
658 > My favorite site is <ulink url="http://example.com">example.com</ulink>.
663 > All documents should be spell checked occasionally.
667 > can check SGML with the
688 >3.3. Privoxy Custom Entities</A
694 > documentation is using
695 a number of customized <SPAN
699 documentation maintenance.
702 > We are using a set of <SPAN
705 > files with generic text,
706 that is used by multiple docs. This way we can write something once, and use
707 it repeatedly without having to re-write the same content over and over again.
708 If editing such a file, keep in mind that it should be
715 >. That is the purpose; so it can be used in varying
716 contexts without additional modifications.
719 > We are also using what <SPAN
725 >"internal entities"</SPAN
726 >. These are like variables in
727 programming. Well, sort of. For instance, we have the
731 > entity that contains the current
735 > version string. You are strongly
736 encouraged to use these where possible. Some of these obviously
737 require re-setting with each release (done by the Makefile). A sampling of
738 custom entities are listed below. See any of the main docs for examples.
749 > text entities are defined like:
754 ><!entity supported SYSTEM "supported.sgml"></VAR
758 > In this example, the contents of the file,
762 > is available for inclusion anywhere
763 in the doc. To make this happen, just reference the now defined
766 >&supported;</VAR
767 > (starts with an ampersand
768 and ends with a semi-colon), and the contents will be dumped into
769 the finished doc at that point.
774 > Commonly used <SPAN
776 >"internal entities"</SPAN
796 version string, e.g. <SPAN
810 >: the project status, either
831 >: use to conditionally include
835 > releases (e.g. <SPAN
849 >: just the opposite.
860 >: this doc is only generated as text.
872 > There are others in various places that are defined for a specific
873 purpose. Read the source!
882 SUMMARY="Footer navigation table"
921 >The CVS Repository</TD
931 >Coding Guidelines</TD