Minor mod to doc section.
[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      toplevel 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.
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 ><DIV
228 CLASS="SECT2"
229 ><H2
230 CLASS="SECT2"
231 ><A
232 NAME="SGML"
233 >4.1. Quickstart to Docbook and SGML</A
234 ></H2
235 ><P
236 > If you are not familiar with SGML, it is a markup language similar to HTML. 
237  Actually, not a mark up language per se, but a language used to define 
238  markup languages. In fact, HTML is an SGML application. Both will use
239  <SPAN
240 CLASS="QUOTE"
241 >"tags"</SPAN
242 > to format text and other content. SGML tags can be much
243  more varied, and flexible, but do much of the same kinds of things. The tags,
244  or <SPAN
245 CLASS="QUOTE"
246 >"elements"</SPAN
247 >, are definable in SGML. There is no set
248  <SPAN
249 CLASS="QUOTE"
250 >"standards"</SPAN
251 >. Since we are using
252  <SPAN
253 CLASS="APPLICATION"
254 >Docbook</SPAN
255 >, our tags are those that are defined by 
256  <SPAN
257 CLASS="APPLICATION"
258 >Docbook</SPAN
259 >. Much of how the finish document is
260  rendered is determined by the <SPAN
261 CLASS="QUOTE"
262 >"stylesheets"</SPAN
263 >.
264  The stylesheets determine how each tag gets translated to HTML, or other
265  formats.</P
266 ><P
267 > Tags in Docbook SGML need to be always <SPAN
268 CLASS="QUOTE"
269 >"closed"</SPAN
270 >. If not, you
271  will likely generate errors. Example: <TT
272 CLASS="LITERAL"
273 >&#60;title&#62;My
274  Title&#60;/title&#62;</TT
275 >. They are also case-insensitive, but we
276  strongly suggest using all lower case. This keeps compatibility with
277  [Docbook] <SPAN
278 CLASS="APPLICATION"
279 >XML</SPAN
280 >.</P
281 ><P
282 > Our documents use <SPAN
283 CLASS="QUOTE"
284 >"sections"</SPAN
285 > for the most part. Sections
286  will be processed into HTML headers (e.g. <TT
287 CLASS="LITERAL"
288 >h1</TT
289 > for 
290  <TT
291 CLASS="LITERAL"
292 >sect1</TT
293 >). The <SPAN
294 CLASS="APPLICATION"
295 >Docbook</SPAN
296 > stylesheets
297  will use these to also generate the Table of Contents for each doc. Our 
298  TOC's are set to a depth of three. Meaning <TT
299 CLASS="LITERAL"
300 >sect1</TT
301 >, 
302  <TT
303 CLASS="LITERAL"
304 >sect2</TT
305 >, and <TT
306 CLASS="LITERAL"
307 >sect3</TT
308 > will have TOC 
309  entries, but <TT
310 CLASS="LITERAL"
311 >sect4</TT
312 > will not. Each section requires 
313  a <TT
314 CLASS="LITERAL"
315 >&#60;title&#62;</TT
316 > element, and at least one 
317  <TT
318 CLASS="LITERAL"
319 >&#60;para&#62;</TT
320 >. There is a limit of five section 
321  levels in Docbook, but generally three should be sufficient for our 
322  purposes.</P
323 ><P
324 > Some common elements that you likely will use: </P
325 ><P
326 ></P
327 ><TABLE
328 BORDER="0"
329 ><TBODY
330 ><TR
331 ><TD
332 >  <I
333 CLASS="EMPHASIS"
334 >&#60;para&#62;&#60;/para&#62;</I
335 >, paragraph delimiter. Most 
336   text needs to be within paragraph elements (there are some exceptions).
337  </TD
338 ></TR
339 ><TR
340 ><TD
341 >  <I
342 CLASS="EMPHASIS"
343 >&#60;emphasis&#62;&#60;/emphasis&#62;</I
344 >, the stylesheets make this
345  italics.
346  </TD
347 ></TR
348 ><TR
349 ><TD
350 >  <I
351 CLASS="EMPHASIS"
352 >&#60;filename&#62;&#60;/filename&#62;</I
353 >, files and directories.
354  </TD
355 ></TR
356 ><TR
357 ><TD
358 >  <I
359 CLASS="EMPHASIS"
360 >&#60;command&#62;&#60;/command&#62;</I
361 >, command examples.
362  </TD
363 ></TR
364 ><TR
365 ><TD
366 >  <I
367 CLASS="EMPHASIS"
368 >&#60;literallayout&#62;&#60;/literllayout&#62;</I
369 >, like 
370   <TT
371 CLASS="LITERAL"
372 >&#60;pre&#62;</TT
373 >, more or less.
374  </TD
375 ></TR
376 ><TR
377 ><TD
378 >  <I
379 CLASS="EMPHASIS"
380 >&#60;itemizedlist&#62;&#60;/itemizdelist&#62;</I
381 >, list with bullets.
382  </TD
383 ></TR
384 ><TR
385 ><TD
386 >  <I
387 CLASS="EMPHASIS"
388 >&#60;listitem&#62;&#60;/listitem&#62;</I
389 >, member of the above.
390  </TD
391 ></TR
392 ><TR
393 ><TD
394 >   <I
395 CLASS="EMPHASIS"
396 >&#60;screen&#62;&#60;/screen&#62;</I
397 >, screen output, implies 
398    <TT
399 CLASS="LITERAL"
400 >&#60;literallayout&#62;</TT
401 >.
402  </TD
403 ></TR
404 ><TR
405 ><TD
406 >  <I
407 CLASS="EMPHASIS"
408 >&#60;ulink url="example.com"&#62;&#60;/ulink&#62;</I
409 >, like 
410   HTML <TT
411 CLASS="LITERAL"
412 >&#60;a&#62;</TT
413 > tag.
414  </TD
415 ></TR
416 ><TR
417 ><TD
418 >   <I
419 CLASS="EMPHASIS"
420 >&#60;quote&#62;&#60;/quote&#62;</I
421 >, for, doh, quoting text. 
422  </TD
423 ></TR
424 ></TBODY
425 ></TABLE
426 ><P
427 ></P
428 ><P
429 > Look at any of the existing docs for examples of all these and more.</P
430 ></DIV
431 ><DIV
432 CLASS="SECT2"
433 ><H2
434 CLASS="SECT2"
435 ><A
436 NAME="DOCSTYLE"
437 >4.2. <SPAN
438 CLASS="APPLICATION"
439 >Privoxy</SPAN
440 > Documentation Style</A
441 ></H2
442 ><P
443 >    It will be easier if everyone follows a similar writing style. This 
444     just makes it easier to read what someone else has written if it 
445     is all done in a similar fashion.
446    </P
447 ><P
448 >    Here it is:
449    </P
450 ><P
451 >    <P
452 ></P
453 ><UL
454 ><LI
455 ><P
456 >       All tags should be lower case.
457       </P
458 ></LI
459 ><LI
460 ><P
461 >       Tags delimiting a <I
462 CLASS="EMPHASIS"
463 >block</I
464 > of text (even small
465        blocks) should be on their own line. Like:
466        <P
467 CLASS="LITERALLAYOUT"
468 >&nbsp;&#60;para&#62;<br>
469 &nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here.<br>
470 &nbsp;&#60;/para&#62;<br>
471 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
472 >
473        Tags marking individual words, or few words, should be in-line:
474        <P
475 CLASS="LITERALLAYOUT"
476 >&nbsp;&nbsp;Just&nbsp;to&nbsp;&#60;emphasis&#62;emphasize&#60;/emphasis&#62;,&nbsp;some&nbsp;text&nbsp;goes&nbsp;here.<br>
477 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
478 >
479      </P
480 ></LI
481 ><LI
482 ><P
483 >      Tags should be nested and step indented for block text like: (except
484       in-line tags) 
485      <P
486 CLASS="LITERALLAYOUT"
487 >&nbsp;&#60;para&#62;<br>
488 &nbsp;&nbsp;&#60;itemizedlist&#62;<br>
489 &nbsp;&nbsp;&nbsp;&#60;para&#62;<br>
490 &nbsp;&nbsp;&nbsp;&nbsp;&#60;listitem&#62;<br>
491 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here&nbsp;in&nbsp;our&nbsp;list&nbsp;example.<br>
492 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#60;/listitem&#62;<br>
493 &nbsp;&nbsp;&nbsp;&#60;/para&#62;<br>
494 &nbsp;&nbsp;&#60;/itemizedlist&#62;<br>
495 &nbsp;&#60;/para&#62;<br>
496 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
497 >
498       This makes it easier to find the text amongst the tags ;-)
499     </P
500 ></LI
501 ><LI
502 ><P
503 >     Use white space to separate logical divisions within a document, 
504      like between sections. Running everything together consistently 
505      makes it harder to read and work on.
506     </P
507 ></LI
508 ><LI
509 ><P
510 >     Do not hesitate to make comments. Comments can either use the 
511      &#60;comment&#62; element, or the &#60;!--  --&#62; style comment 
512      familiar from HTML. (Note in Docbook v4.x &#60;comment&#62; is 
513      replaced by &#60;remark&#62;.)
514     </P
515 ></LI
516 ><LI
517 ><P
518 >     We have an international audience. Refrain from slang, or English 
519      idiosyncrasies (too many to list :).
520    </P
521 ></LI
522 ><LI
523 ><P
524 >    Try to keep overall line lengths in source files to 80 characters or less
525     for obvious reasons. This is not always possible, with lenghty URLs for
526     instance.
527    </P
528 ></LI
529 ><LI
530 ><P
531 >    Our documents are available in differing formats. Right now, they 
532     are just plain text, and HTML, but PDF, and others is always a 
533     future possibility. Be careful with URLs (&#60;ulink&#62;), and avoid 
534     this mistake:
535    </P
536 ><P
537 >     My favorite site is &#60;ulink url="http://example.com"&#62;here&#60;/ulink&#62;.
538    </P
539 ><P
540 >     This will render as <SPAN
541 CLASS="QUOTE"
542 >"My favorite site is here"</SPAN
543 >, which is 
544      not real helpful in a text doc. Better like this:
545    </P
546 ><P
547 >     My favorite site is &#60;ulink url="http://example.com"&#62;example.com&#60;/ulink&#62;.
548    </P
549 ></LI
550 ><LI
551 ><P
552 >    All documents should be spell checked occasionally.
553     <SPAN
554 CLASS="APPLICATION"
555 >aspell</SPAN
556 > can check SGML with the
557     <TT
558 CLASS="LITERAL"
559 >-H</TT
560 > option. (<SPAN
561 CLASS="APPLICATION"
562 >ispell</SPAN
563 > I think
564     too.)
565    </P
566 ></LI
567 ></UL
568 >
569  </P
570 ></DIV
571 ><DIV
572 CLASS="SECT2"
573 ><H2
574 CLASS="SECT2"
575 ><A
576 NAME="AEN179"
577 >4.3. Privoxy Custom Entities</A
578 ></H2
579 ><P
580 >  <SPAN
581 CLASS="APPLICATION"
582 >Privoxy</SPAN
583 > documentation is using 
584   a number of customized <SPAN
585 CLASS="QUOTE"
586 >"entities"</SPAN
587 > to facilitate 
588   documentation maintenance. 
589  </P
590 ><P
591 >  We are using a set of <SPAN
592 CLASS="QUOTE"
593 >"boilerplate"</SPAN
594 > files with generic text,
595   that is used by multiple docs. This way we can write something once, and use
596   it repeatedly without having to re-write the same content over and over again.
597   If editing such a file, keep in mind that it should be
598   <I
599 CLASS="EMPHASIS"
600 >generic</I
601 >. That is the purpose; so it can be used in varying 
602   contexts without additional modifications.
603  </P
604 ><P
605 >  We are also using what <SPAN
606 CLASS="APPLICATION"
607 >Docbook</SPAN
608 > calls 
609   <SPAN
610 CLASS="QUOTE"
611 >"internal entities"</SPAN
612 >. These are like variables in 
613   programming. Well, sort of. For instance, we have the
614   <TT
615 CLASS="LITERAL"
616 >p-version</TT
617 > entity that contains the current 
618   <SPAN
619 CLASS="APPLICATION"
620 >Privoxy</SPAN
621 > version string. You are strongly 
622   encouraged to use these where possible. Some of these obviously 
623   require re-setting with each release (done by the Makefile). A sampling of
624   custom entities are listed below. See any of the main docs for examples.
625  </P
626 ><P
627 >  <P
628 ></P
629 ><UL
630 ><LI
631 ><P
632 >    Re-cyclable <SPAN
633 CLASS="QUOTE"
634 >"boilerplate"</SPAN
635 > text entities are defined like:
636    </P
637 ><P
638 >    <TT
639 CLASS="LITERAL"
640 >&#60;!entity supported SYSTEM "supported.sgml"&#62;</TT
641 >
642    </P
643 ><P
644 >     In this example, the contents of the file,
645      <TT
646 CLASS="FILENAME"
647 >supported.sgml</TT
648 > is available for inclusion anywhere 
649      in the doc. To make this happen, just reference the now defined 
650      entity: <TT
651 CLASS="LITERAL"
652 >&#38;supported;</TT
653 > (starts with an ampersand 
654      and ends with a semi-colon), and the contents will be dumped into 
655      the finished doc at that point.
656    </P
657 ></LI
658 ><LI
659 ><P
660 >    Commonly used <SPAN
661 CLASS="QUOTE"
662 >"internal entities"</SPAN
663 >:
664   </P
665 ><P
666 ></P
667 ><TABLE
668 BORDER="0"
669 ><TBODY
670 ><TR
671 ><TD
672 >    <I
673 CLASS="EMPHASIS"
674 >p-version</I
675 >: the <SPAN
676 CLASS="APPLICATION"
677 >Privoxy</SPAN
678
679     version string, e.g. <SPAN
680 CLASS="QUOTE"
681 >"2.9.13"</SPAN
682 >.
683    </TD
684 ></TR
685 ><TR
686 ><TD
687 >    <I
688 CLASS="EMPHASIS"
689 >p-status</I
690 >: the project status, either 
691     <SPAN
692 CLASS="QUOTE"
693 >"ALPHA"</SPAN
694 >, <SPAN
695 CLASS="QUOTE"
696 >"BETA"</SPAN
697 >, or <SPAN
698 CLASS="QUOTE"
699 >"STABLE"</SPAN
700 >.
701    </TD
702 ></TR
703 ><TR
704 ><TD
705 >    <I
706 CLASS="EMPHASIS"
707 >p-not-stable</I
708 >: use to conditionally include 
709     text in <SPAN
710 CLASS="QUOTE"
711 >"not stable"</SPAN
712 > releases (e.g. <SPAN
713 CLASS="QUOTE"
714 >"BETA"</SPAN
715 >).
716    </TD
717 ></TR
718 ><TR
719 ><TD
720 >    <I
721 CLASS="EMPHASIS"
722 >p-stable</I
723 >: just the opposite.
724    </TD
725 ></TR
726 ><TR
727 ><TD
728 >    <I
729 CLASS="EMPHASIS"
730 >p-text</I
731 >: this doc is only generated as text.
732    </TD
733 ></TR
734 ></TBODY
735 ></TABLE
736 ><P
737 ></P
738 ></LI
739 ></UL
740 >
741  </P
742 ><P
743 >  There are others in various places that are defined for a specific 
744   purpose. Read the source!
745  </P
746 ></DIV
747 ></DIV
748 ><DIV
749 CLASS="NAVFOOTER"
750 ><HR
751 ALIGN="LEFT"
752 WIDTH="100%"><TABLE
753 WIDTH="100%"
754 BORDER="0"
755 CELLPADDING="0"
756 CELLSPACING="0"
757 ><TR
758 ><TD
759 WIDTH="33%"
760 ALIGN="left"
761 VALIGN="top"
762 ><A
763 HREF="quickstart.html"
764 >Prev</A
765 ></TD
766 ><TD
767 WIDTH="34%"
768 ALIGN="center"
769 VALIGN="top"
770 ><A
771 HREF="index.html"
772 >Home</A
773 ></TD
774 ><TD
775 WIDTH="33%"
776 ALIGN="right"
777 VALIGN="top"
778 ><A
779 HREF="coding.html"
780 >Next</A
781 ></TD
782 ></TR
783 ><TR
784 ><TD
785 WIDTH="33%"
786 ALIGN="left"
787 VALIGN="top"
788 >Quickstart to Privoxy Development</TD
789 ><TD
790 WIDTH="34%"
791 ALIGN="center"
792 VALIGN="top"
793 >&nbsp;</TD
794 ><TD
795 WIDTH="33%"
796 ALIGN="right"
797 VALIGN="top"
798 >Coding Guidelines</TD
799 ></TR
800 ></TABLE
801 ></DIV
802 ></BODY
803 ></HTML
804 >