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