4 >Documentation Guidelines</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
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
39 >Privoxy Developer Manual</TH
74 >3. Documentation Guidelines</A
77 > All formal documents are maintained in Docbook SGML and located in the
79 CLASS="COMPUTEROUTPUT"
81 > directory. You will need
83 HREF="http://www.docbook.org"
87 DTD's and the Docbook modular stylesheets (or comparable alternatives),
95 > (recommended) installed in order to
96 build docs from source. Currently there is <A
97 HREF="../user-manual/index.html"
105 HREF="../faq/index.html"
126 > (man page) files are also now maintained
127 as Docbook SGML. The finished files are all in the top-level source
128 directory are generated files! Also, <TT
135 > home page, is maintained as SGML.
138 >DO NOT edit these directly</I
139 >. Edit the SGML source, or
140 contact someone involved in the documentation (at present Stefan and
144 > Other, less formal documents (e.g. <TT
151 >) are maintained as plain text files in the
152 top-level source directory. At least for the time being.
155 > Packagers are encouraged to include this documentation. For those without
156 the ability to build the docs locally, text versions of each are kept in
157 CVS. HTML versions are also now being kept in CVS under
164 > Formal documents are built with the Makefile targets of
166 CLASS="COMPUTEROUTPUT"
170 CLASS="COMPUTEROUTPUT"
172 >. If you have problems,
173 try both. The build process uses the document SGML sources in
175 CLASS="COMPUTEROUTPUT"
177 > to update all text files in
179 CLASS="COMPUTEROUTPUT"
181 > and to update all HTML
183 CLASS="COMPUTEROUTPUT"
188 > Documentation writers should please make sure documents build
189 successfully before committing to CVS, if possible.
192 > How do you update the webserver (i.e. the pages on privoxy.org)?
200 > First, build the docs by running <TT
201 CLASS="COMPUTEROUTPUT"
204 > (or alternately <TT
205 CLASS="COMPUTEROUTPUT"
214 CLASS="COMPUTEROUTPUT"
218 CLASS="COMPUTEROUTPUT"
221 sourceforge webserver via scp.
228 > Finished docs should be occasionally submitted to CVS
231 >doc/webserver/*/*.html</TT
232 >) so that those without
233 the ability to build them locally, have access to them if needed.
234 This is especially important just prior to a new release! Please
242 other release specific data in <TT
246 updated (this is done just prior to a new release).
254 >3.1. Quickstart to Docbook and SGML</A
257 > If you are not familiar with SGML, it is a markup language similar to HTML.
258 Actually, not a mark up language per se, but a language used to define
259 markup languages. In fact, HTML is an SGML application. Both will use
263 > to format text and other content. SGML tags can be much
264 more varied, and flexible, but do much of the same kinds of things. The tags,
268 >, are definable in SGML. There is no set
272 >. Since we are using
276 >, our tags are those that are defined by
280 >. Much of how the finish document is
281 rendered is determined by the <SPAN
285 The stylesheets determine how each tag gets translated to HTML, or other
288 > Tags in Docbook SGML need to be always <SPAN
292 will likely generate errors. Example: <TT
295 Title</title></TT
296 >. They are also case-insensitive, but we
297 strongly suggest using all lower case. This keeps compatibility with
303 > Our documents use <SPAN
306 > for the most part. Sections
307 will be processed into HTML headers (e.g. <TT
318 will use these to also generate the Table of Contents for each doc. Our
319 TOC's are set to a depth of three. Meaning <TT
333 > will not. Each section requires
337 > element, and at least one
341 >. There is a limit of five section
342 levels in Docbook, but generally three should be sufficient for our
345 > Some common elements that you likely will use: </P
356 ><para></para></I
357 >, paragraph delimiter. Most
358 text needs to be within paragraph elements (there are some exceptions).
365 ><emphasis></emphasis></I
374 ><filename></filename></I
375 >, files and directories.
382 ><command></command></I
390 ><literallayout></literallayout></I
402 ><itemizedlist></itemizedlist></I
403 >, list with bullets.
410 ><listitem></listitem></I
411 >, member of the above.
418 ><screen></screen></I
419 >, screen output, implies
422 ><literallayout></TT
430 ><ulink url="example.com"></ulink></I
442 ><quote></quote></I
443 >, for, doh, quoting text.
452 > Look at any of the existing docs for examples of all these and more.</P
454 > You might also find <SPAN
457 HREF="http://www.bureau-cornavin.com/opensource/crash-course/"
459 >Writing Documentation
460 Using DocBook - A Crash Course</A
473 > Documentation Style</A
476 > It will be easier if everyone follows a similar writing style. This
477 just makes it easier to read what someone else has written if it
478 is all done in a similar fashion.
489 > All tags should be lower case.
494 > Tags delimiting a <I
497 > of text (even small
498 blocks) should be on their own line. Like:
500 CLASS="LITERALLAYOUT"
501 > <para><br>
502 Some text goes here.<br>
503 </para><br>
504 </P
506 Tags marking individual words, or few words, should be in-line:
508 CLASS="LITERALLAYOUT"
509 > Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
510 </P
516 > Tags should be nested and step indented for block text like: (except
519 CLASS="LITERALLAYOUT"
520 > <para><br>
521 <itemizedlist><br>
522 <para><br>
523 <listitem><br>
524 Some text goes here in our list example.<br>
525 </listitem><br>
526 </para><br>
527 </itemizedlist><br>
528 </para><br>
529 </P
531 This makes it easier to find the text amongst the tags ;-)
536 > Use white space to separate logical divisions within a document,
537 like between sections. Running everything together consistently
538 makes it harder to read and work on.
543 > Do not hesitate to make comments. Comments can either use the
544 <comment> element, or the <!-- --> style comment
545 familiar from HTML. (Note in Docbook v4.x <comment> is
546 replaced by <remark>.)
551 > We have an international audience. Refrain from slang, or English
552 idiosyncrasies (too many to list :). Humor also does not translate
558 > Try to keep overall line lengths in source files to 80 characters or less
559 for obvious reasons. This is not always possible, with lengthy URLs for
565 > Our documents are available in differing formats. Right now, they
566 are just plain text, and HTML, but PDF, and others is always a
567 future possibility. Be careful with URLs (<ulink>), and avoid
571 > My favorite site is <ulink url="http://example.com">here</ulink>.
574 > This will render as <SPAN
576 >"My favorite site is here"</SPAN
578 not real helpful in a text doc. Better like this:
581 > My favorite site is <ulink url="http://example.com">example.com</ulink>.
586 > All documents should be spell checked occasionally.
590 > can check SGML with the
611 >3.3. Privoxy Custom Entities</A
617 > documentation is using
618 a number of customized <SPAN
622 documentation maintenance.
625 > We are using a set of <SPAN
628 > files with generic text,
629 that is used by multiple docs. This way we can write something once, and use
630 it repeatedly without having to re-write the same content over and over again.
631 If editing such a file, keep in mind that it should be
635 >. That is the purpose; so it can be used in varying
636 contexts without additional modifications.
639 > We are also using what <SPAN
645 >"internal entities"</SPAN
646 >. These are like variables in
647 programming. Well, sort of. For instance, we have the
651 > entity that contains the current
655 > version string. You are strongly
656 encouraged to use these where possible. Some of these obviously
657 require re-setting with each release (done by the Makefile). A sampling of
658 custom entities are listed below. See any of the main docs for examples.
669 > text entities are defined like:
674 ><!entity supported SYSTEM "supported.sgml"></TT
678 > In this example, the contents of the file,
682 > is available for inclusion anywhere
683 in the doc. To make this happen, just reference the now defined
687 > (starts with an ampersand
688 and ends with a semi-colon), and the contents will be dumped into
689 the finished doc at that point.
694 > Commonly used <SPAN
696 >"internal entities"</SPAN
713 version string, e.g. <SPAN
724 >: the project status, either
742 >: use to conditionally include
746 > releases (e.g. <SPAN
757 >: just the opposite.
765 >: this doc is only generated as text.
777 > There are others in various places that are defined for a specific
778 purpose. Read the source!
822 >The CVS Repository</TD
832 >Coding Guidelines</TD