bebd35a2e53513bc4d8718f7e333a632c73c3601
[privoxy.git] / doc / webserver / developer-manual / documentation.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >Documentation Guidelines</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
8 "><LINK
9 REL="HOME"
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Quickstart to Privoxy Development"
14 HREF="quickstart.html"><LINK
15 REL="NEXT"
16 TITLE="Coding Guidelines"
17 HREF="coding.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"></HEAD
21 ><BODY
22 CLASS="SECT1"
23 BGCOLOR="#EEEEEE"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 WIDTH="100%"
32 BORDER="0"
33 CELLPADDING="0"
34 CELLSPACING="0"
35 ><TR
36 ><TH
37 COLSPAN="3"
38 ALIGN="center"
39 >Privoxy Developer Manual</TH
40 ></TR
41 ><TR
42 ><TD
43 WIDTH="10%"
44 ALIGN="left"
45 VALIGN="bottom"
46 ><A
47 HREF="quickstart.html"
48 >Prev</A
49 ></TD
50 ><TD
51 WIDTH="80%"
52 ALIGN="center"
53 VALIGN="bottom"
54 ></TD
55 ><TD
56 WIDTH="10%"
57 ALIGN="right"
58 VALIGN="bottom"
59 ><A
60 HREF="coding.html"
61 >Next</A
62 ></TD
63 ></TR
64 ></TABLE
65 ><HR
66 ALIGN="LEFT"
67 WIDTH="100%"></DIV
68 ><DIV
69 CLASS="SECT1"
70 ><H1
71 CLASS="SECT1"
72 ><A
73 NAME="DOCUMENTATION"
74 >4. Documentation Guidelines</A
75 ></H1
76 ><P
77 >    All formal documents are maintained in Docbook SGML and located in the
78     <TT
79 CLASS="COMPUTEROUTPUT"
80 >doc/source/*</TT
81 > directory. You will need
82     <A
83 HREF="http://www.docbook.org"
84 TARGET="_top"
85 >Docbook</A
86 >, the Docbook 
87     DTD's and the Docbook modular stylesheets (or comparable alternatives),
88     and either <SPAN
89 CLASS="APPLICATION"
90 >jade</SPAN
91 > or
92     <SPAN
93 CLASS="APPLICATION"
94 >openjade</SPAN
95 > (recommended) installed in order to
96     build docs from source. Currently there is <A
97 HREF="../user-manual/index.html"
98 TARGET="_top"
99 ><I
100 CLASS="CITETITLE"
101 >user-manual</I
102 ></A
103 >,
104     <A
105 HREF="../faq/index.html"
106 TARGET="_top"
107 ><I
108 CLASS="CITETITLE"
109 >FAQ</I
110 ></A
111 >, and, of
112     course this, the <I
113 CLASS="CITETITLE"
114 >developer-manual</I
115 > in this format.
116     The <I
117 CLASS="CITETITLE"
118 >README</I
119 >, <I
120 CLASS="CITETITLE"
121 >AUTHORS</I
122 >
123     <I
124 CLASS="CITETITLE"
125 >privoxy.1</I
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
129 CLASS="FILENAME"
130 >index.html</TT
131 >, the
132     <SPAN
133 CLASS="APPLICATION"
134 >Privoxy</SPAN
135 > home page, is maintained as SGML.
136     <I
137 CLASS="EMPHASIS"
138 >DO NOT edit these directly</I
139 >. Edit the SGML source, or
140     contact someone involved in the documentation (at present Stefan and
141     Hal).
142     </P
143 ><P
144 >     Other, less formal documents (e.g. <TT
145 CLASS="FILENAME"
146 >LICENSE</TT
147 >,
148      <TT
149 CLASS="FILENAME"
150 >INSTALL</TT
151 >) are maintained as plain text files in the
152      top-level source directory. At least for the time being.
153     </P
154 ><P
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 
158      <TT
159 CLASS="FILENAME"
160 >doc/webserver/*</TT
161 >.
162     </P
163 ><P
164 >     Formal documents are built with the Makefile targets of
165      <TT
166 CLASS="COMPUTEROUTPUT"
167 >make dok</TT
168 >, or alternately
169      <TT
170 CLASS="COMPUTEROUTPUT"
171 >make redhat-dok</TT
172 >. If you have problems,
173      try both. The build process uses the document SGML sources in
174      <TT
175 CLASS="COMPUTEROUTPUT"
176 >doc/source/*/*</TT
177 > to update all text files in
178      <TT
179 CLASS="COMPUTEROUTPUT"
180 >doc/text/</TT
181 > and to update all HTML
182      documents in <TT
183 CLASS="COMPUTEROUTPUT"
184 >doc/webserver/</TT
185 >.
186     </P
187 ><P
188 >     Documentation writers should please make sure documents build
189      successfully before committing to CVS, if possible.
190     </P
191 ><P
192 >     How do you update the webserver (i.e. the pages on privoxy.org)?
193      
194      <P
195 ></P
196 ><OL
197 TYPE="1"
198 ><LI
199 ><P
200 >        First, build the docs by running <TT
201 CLASS="COMPUTEROUTPUT"
202 >make
203         dok</TT
204 > (or alternately <TT
205 CLASS="COMPUTEROUTPUT"
206 >make
207         redhat-dok</TT
208 >).                 
209       </P
210 ></LI
211 ><LI
212 ><P
213 >        Run <TT
214 CLASS="COMPUTEROUTPUT"
215 >make webserver</TT
216 > which copies all
217         files from <TT
218 CLASS="COMPUTEROUTPUT"
219 >doc/webserver</TT
220 > to the
221         sourceforge webserver via scp.
222       </P
223 ></LI
224 ></OL
225 >
226   </P
227 ><P
228 >   Finished docs should be occasionally submitted to CVS
229    (<TT
230 CLASS="FILENAME"
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
235    do this <I
236 CLASS="EMPHASIS"
237 >after</I
238 > the <TT
239 CLASS="LITERAL"
240 >$VERSION</TT
241 > and
242    other release specific data in <TT
243 CLASS="FILENAME"
244 >configure.in</TT
245 > has been
246    updated (this is done just prior to a new release).
247   </P
248 ><DIV
249 CLASS="SECT2"
250 ><H2
251 CLASS="SECT2"
252 ><A
253 NAME="SGML"
254 >4.1. Quickstart to Docbook and SGML</A
255 ></H2
256 ><P
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
260  <SPAN
261 CLASS="QUOTE"
262 >"tags"</SPAN
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,
265  or <SPAN
266 CLASS="QUOTE"
267 >"elements"</SPAN
268 >, are definable in SGML. There is no set
269  <SPAN
270 CLASS="QUOTE"
271 >"standards"</SPAN
272 >. Since we are using
273  <SPAN
274 CLASS="APPLICATION"
275 >Docbook</SPAN
276 >, our tags are those that are defined by 
277  <SPAN
278 CLASS="APPLICATION"
279 >Docbook</SPAN
280 >. Much of how the finish document is
281  rendered is determined by the <SPAN
282 CLASS="QUOTE"
283 >"stylesheets"</SPAN
284 >.
285  The stylesheets determine how each tag gets translated to HTML, or other
286  formats.</P
287 ><P
288 > Tags in Docbook SGML need to be always <SPAN
289 CLASS="QUOTE"
290 >"closed"</SPAN
291 >. If not, you
292  will likely generate errors. Example: <TT
293 CLASS="LITERAL"
294 >&#60;title&#62;My
295  Title&#60;/title&#62;</TT
296 >. They are also case-insensitive, but we
297  strongly suggest using all lower case. This keeps compatibility with
298  [Docbook] <SPAN
299 CLASS="APPLICATION"
300 >XML</SPAN
301 >.</P
302 ><P
303 > Our documents use <SPAN
304 CLASS="QUOTE"
305 >"sections"</SPAN
306 > for the most part. Sections
307  will be processed into HTML headers (e.g. <TT
308 CLASS="LITERAL"
309 >h1</TT
310 > for 
311  <TT
312 CLASS="LITERAL"
313 >sect1</TT
314 >). The <SPAN
315 CLASS="APPLICATION"
316 >Docbook</SPAN
317 > stylesheets
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
320 CLASS="LITERAL"
321 >sect1</TT
322 >, 
323  <TT
324 CLASS="LITERAL"
325 >sect2</TT
326 >, and <TT
327 CLASS="LITERAL"
328 >sect3</TT
329 > will have TOC 
330  entries, but <TT
331 CLASS="LITERAL"
332 >sect4</TT
333 > will not. Each section requires 
334  a <TT
335 CLASS="LITERAL"
336 >&#60;title&#62;</TT
337 > element, and at least one 
338  <TT
339 CLASS="LITERAL"
340 >&#60;para&#62;</TT
341 >. There is a limit of five section 
342  levels in Docbook, but generally three should be sufficient for our 
343  purposes.</P
344 ><P
345 > Some common elements that you likely will use: </P
346 ><P
347 ></P
348 ><TABLE
349 BORDER="0"
350 ><TBODY
351 ><TR
352 ><TD
353 >  <I
354 CLASS="EMPHASIS"
355 >&#60;para&#62;&#60;/para&#62;</I
356 >, paragraph delimiter. Most 
357   text needs to be within paragraph elements (there are some exceptions).
358  </TD
359 ></TR
360 ><TR
361 ><TD
362 >  <I
363 CLASS="EMPHASIS"
364 >&#60;emphasis&#62;&#60;/emphasis&#62;</I
365 >, the stylesheets make this
366  italics.
367  </TD
368 ></TR
369 ><TR
370 ><TD
371 >  <I
372 CLASS="EMPHASIS"
373 >&#60;filename&#62;&#60;/filename&#62;</I
374 >, files and directories.
375  </TD
376 ></TR
377 ><TR
378 ><TD
379 >  <I
380 CLASS="EMPHASIS"
381 >&#60;command&#62;&#60;/command&#62;</I
382 >, command examples.
383  </TD
384 ></TR
385 ><TR
386 ><TD
387 >  <I
388 CLASS="EMPHASIS"
389 >&#60;literallayout&#62;&#60;/literallayout&#62;</I
390 >, like 
391   <TT
392 CLASS="LITERAL"
393 >&#60;pre&#62;</TT
394 >, more or less.
395  </TD
396 ></TR
397 ><TR
398 ><TD
399 >  <I
400 CLASS="EMPHASIS"
401 >&#60;itemizedlist&#62;&#60;/itemizedlist&#62;</I
402 >, list with bullets.
403  </TD
404 ></TR
405 ><TR
406 ><TD
407 >  <I
408 CLASS="EMPHASIS"
409 >&#60;listitem&#62;&#60;/listitem&#62;</I
410 >, member of the above.
411  </TD
412 ></TR
413 ><TR
414 ><TD
415 >   <I
416 CLASS="EMPHASIS"
417 >&#60;screen&#62;&#60;/screen&#62;</I
418 >, screen output, implies 
419    <TT
420 CLASS="LITERAL"
421 >&#60;literallayout&#62;</TT
422 >.
423  </TD
424 ></TR
425 ><TR
426 ><TD
427 >  <I
428 CLASS="EMPHASIS"
429 >&#60;ulink url="example.com"&#62;&#60;/ulink&#62;</I
430 >, like 
431   HTML <TT
432 CLASS="LITERAL"
433 >&#60;a&#62;</TT
434 > tag.
435  </TD
436 ></TR
437 ><TR
438 ><TD
439 >   <I
440 CLASS="EMPHASIS"
441 >&#60;quote&#62;&#60;/quote&#62;</I
442 >, for, doh, quoting text. 
443  </TD
444 ></TR
445 ></TBODY
446 ></TABLE
447 ><P
448 ></P
449 ><P
450 > Look at any of the existing docs for examples of all these and more.</P
451 ></DIV
452 ><DIV
453 CLASS="SECT2"
454 ><H2
455 CLASS="SECT2"
456 ><A
457 NAME="DOCSTYLE"
458 >4.2. <SPAN
459 CLASS="APPLICATION"
460 >Privoxy</SPAN
461 > Documentation Style</A
462 ></H2
463 ><P
464 >    It will be easier if everyone follows a similar writing style. This 
465     just makes it easier to read what someone else has written if it 
466     is all done in a similar fashion.
467    </P
468 ><P
469 >    Here it is:
470    </P
471 ><P
472 >    <P
473 ></P
474 ><UL
475 ><LI
476 ><P
477 >       All tags should be lower case.
478       </P
479 ></LI
480 ><LI
481 ><P
482 >       Tags delimiting a <I
483 CLASS="EMPHASIS"
484 >block</I
485 > of text (even small
486        blocks) should be on their own line. Like:
487        <P
488 CLASS="LITERALLAYOUT"
489 >&nbsp;&#60;para&#62;<br>
490 &nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here.<br>
491 &nbsp;&#60;/para&#62;<br>
492 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
493 >
494        Tags marking individual words, or few words, should be in-line:
495        <P
496 CLASS="LITERALLAYOUT"
497 >&nbsp;&nbsp;Just&nbsp;to&nbsp;&#60;emphasis&#62;emphasize&#60;/emphasis&#62;,&nbsp;some&nbsp;text&nbsp;goes&nbsp;here.<br>
498 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
499 >
500      </P
501 ></LI
502 ><LI
503 ><P
504 >      Tags should be nested and step indented for block text like: (except
505       in-line tags) 
506      <P
507 CLASS="LITERALLAYOUT"
508 >&nbsp;&#60;para&#62;<br>
509 &nbsp;&nbsp;&#60;itemizedlist&#62;<br>
510 &nbsp;&nbsp;&nbsp;&#60;para&#62;<br>
511 &nbsp;&nbsp;&nbsp;&nbsp;&#60;listitem&#62;<br>
512 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here&nbsp;in&nbsp;our&nbsp;list&nbsp;example.<br>
513 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#60;/listitem&#62;<br>
514 &nbsp;&nbsp;&nbsp;&#60;/para&#62;<br>
515 &nbsp;&nbsp;&#60;/itemizedlist&#62;<br>
516 &nbsp;&#60;/para&#62;<br>
517 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
518 >
519       This makes it easier to find the text amongst the tags ;-)
520     </P
521 ></LI
522 ><LI
523 ><P
524 >     Use white space to separate logical divisions within a document, 
525      like between sections. Running everything together consistently 
526      makes it harder to read and work on.
527     </P
528 ></LI
529 ><LI
530 ><P
531 >     Do not hesitate to make comments. Comments can either use the 
532      &#60;comment&#62; element, or the &#60;!--  --&#62; style comment 
533      familiar from HTML. (Note in Docbook v4.x &#60;comment&#62; is 
534      replaced by &#60;remark&#62;.)
535     </P
536 ></LI
537 ><LI
538 ><P
539 >     We have an international audience. Refrain from slang, or English 
540      idiosyncrasies (too many to list :). Humor also does not translate 
541      well sometimes.
542    </P
543 ></LI
544 ><LI
545 ><P
546 >    Try to keep overall line lengths in source files to 80 characters or less
547     for obvious reasons. This is not always possible, with lengthy URLs for
548     instance.
549    </P
550 ></LI
551 ><LI
552 ><P
553 >    Our documents are available in differing formats. Right now, they 
554     are just plain text, and HTML, but PDF, and others is always a 
555     future possibility. Be careful with URLs (&#60;ulink&#62;), and avoid 
556     this mistake:
557    </P
558 ><P
559 >     My favorite site is &#60;ulink url="http://example.com"&#62;here&#60;/ulink&#62;.
560    </P
561 ><P
562 >     This will render as <SPAN
563 CLASS="QUOTE"
564 >"My favorite site is here"</SPAN
565 >, which is 
566      not real helpful in a text doc. Better like this:
567    </P
568 ><P
569 >     My favorite site is &#60;ulink url="http://example.com"&#62;example.com&#60;/ulink&#62;.
570    </P
571 ></LI
572 ><LI
573 ><P
574 >    All documents should be spell checked occasionally.
575     <SPAN
576 CLASS="APPLICATION"
577 >aspell</SPAN
578 > can check SGML with the
579     <TT
580 CLASS="LITERAL"
581 >-H</TT
582 > option. (<SPAN
583 CLASS="APPLICATION"
584 >ispell</SPAN
585 > I think
586     too.)
587    </P
588 ></LI
589 ></UL
590 >
591  </P
592 ></DIV
593 ><DIV
594 CLASS="SECT2"
595 ><H2
596 CLASS="SECT2"
597 ><A
598 NAME="AEN186"
599 >4.3. Privoxy Custom Entities</A
600 ></H2
601 ><P
602 >  <SPAN
603 CLASS="APPLICATION"
604 >Privoxy</SPAN
605 > documentation is using 
606   a number of customized <SPAN
607 CLASS="QUOTE"
608 >"entities"</SPAN
609 > to facilitate 
610   documentation maintenance. 
611  </P
612 ><P
613 >  We are using a set of <SPAN
614 CLASS="QUOTE"
615 >"boilerplate"</SPAN
616 > files with generic text,
617   that is used by multiple docs. This way we can write something once, and use
618   it repeatedly without having to re-write the same content over and over again.
619   If editing such a file, keep in mind that it should be
620   <I
621 CLASS="EMPHASIS"
622 >generic</I
623 >. That is the purpose; so it can be used in varying 
624   contexts without additional modifications.
625  </P
626 ><P
627 >  We are also using what <SPAN
628 CLASS="APPLICATION"
629 >Docbook</SPAN
630 > calls 
631   <SPAN
632 CLASS="QUOTE"
633 >"internal entities"</SPAN
634 >. These are like variables in 
635   programming. Well, sort of. For instance, we have the
636   <TT
637 CLASS="LITERAL"
638 >p-version</TT
639 > entity that contains the current 
640   <SPAN
641 CLASS="APPLICATION"
642 >Privoxy</SPAN
643 > version string. You are strongly 
644   encouraged to use these where possible. Some of these obviously 
645   require re-setting with each release (done by the Makefile). A sampling of
646   custom entities are listed below. See any of the main docs for examples.
647  </P
648 ><P
649 >  <P
650 ></P
651 ><UL
652 ><LI
653 ><P
654 >    Re- <SPAN
655 CLASS="QUOTE"
656 >"boilerplate"</SPAN
657 > text entities are defined like:
658    </P
659 ><P
660 >    <TT
661 CLASS="LITERAL"
662 >&#60;!entity supported SYSTEM "supported.sgml"&#62;</TT
663 >
664    </P
665 ><P
666 >     In this example, the contents of the file,
667      <TT
668 CLASS="FILENAME"
669 >supported.sgml</TT
670 > is available for inclusion anywhere 
671      in the doc. To make this happen, just reference the now defined 
672      entity: <TT
673 CLASS="LITERAL"
674 >&#38;supported;</TT
675 > (starts with an ampersand 
676      and ends with a semi-colon), and the contents will be dumped into 
677      the finished doc at that point.
678    </P
679 ></LI
680 ><LI
681 ><P
682 >    Commonly used <SPAN
683 CLASS="QUOTE"
684 >"internal entities"</SPAN
685 >:
686   </P
687 ><P
688 ></P
689 ><TABLE
690 BORDER="0"
691 ><TBODY
692 ><TR
693 ><TD
694 >    <I
695 CLASS="EMPHASIS"
696 >p-version</I
697 >: the <SPAN
698 CLASS="APPLICATION"
699 >Privoxy</SPAN
700
701     version string, e.g. <SPAN
702 CLASS="QUOTE"
703 >"2.9.14"</SPAN
704 >.
705    </TD
706 ></TR
707 ><TR
708 ><TD
709 >    <I
710 CLASS="EMPHASIS"
711 >p-status</I
712 >: the project status, either 
713     <SPAN
714 CLASS="QUOTE"
715 >"alpha"</SPAN
716 >, <SPAN
717 CLASS="QUOTE"
718 >"beta"</SPAN
719 >, or <SPAN
720 CLASS="QUOTE"
721 >"stable"</SPAN
722 >.
723    </TD
724 ></TR
725 ><TR
726 ><TD
727 >    <I
728 CLASS="EMPHASIS"
729 >p-not-stable</I
730 >: use to conditionally include 
731     text in <SPAN
732 CLASS="QUOTE"
733 >"not stable"</SPAN
734 > releases (e.g. <SPAN
735 CLASS="QUOTE"
736 >"beta"</SPAN
737 >).
738    </TD
739 ></TR
740 ><TR
741 ><TD
742 >    <I
743 CLASS="EMPHASIS"
744 >p-stable</I
745 >: just the opposite.
746    </TD
747 ></TR
748 ><TR
749 ><TD
750 >    <I
751 CLASS="EMPHASIS"
752 >p-text</I
753 >: this doc is only generated as text.
754    </TD
755 ></TR
756 ></TBODY
757 ></TABLE
758 ><P
759 ></P
760 ></LI
761 ></UL
762 >
763  </P
764 ><P
765 >  There are others in various places that are defined for a specific 
766   purpose. Read the source!
767  </P
768 ></DIV
769 ></DIV
770 ><DIV
771 CLASS="NAVFOOTER"
772 ><HR
773 ALIGN="LEFT"
774 WIDTH="100%"><TABLE
775 WIDTH="100%"
776 BORDER="0"
777 CELLPADDING="0"
778 CELLSPACING="0"
779 ><TR
780 ><TD
781 WIDTH="33%"
782 ALIGN="left"
783 VALIGN="top"
784 ><A
785 HREF="quickstart.html"
786 >Prev</A
787 ></TD
788 ><TD
789 WIDTH="34%"
790 ALIGN="center"
791 VALIGN="top"
792 ><A
793 HREF="index.html"
794 >Home</A
795 ></TD
796 ><TD
797 WIDTH="33%"
798 ALIGN="right"
799 VALIGN="top"
800 ><A
801 HREF="coding.html"
802 >Next</A
803 ></TD
804 ></TR
805 ><TR
806 ><TD
807 WIDTH="33%"
808 ALIGN="left"
809 VALIGN="top"
810 >Quickstart to Privoxy Development</TD
811 ><TD
812 WIDTH="34%"
813 ALIGN="center"
814 VALIGN="top"
815 >&nbsp;</TD
816 ><TD
817 WIDTH="33%"
818 ALIGN="right"
819 VALIGN="top"
820 >Coding Guidelines</TD
821 ></TR
822 ></TABLE
823 ></DIV
824 ></BODY
825 ></HTML
826 >