doc/webserver/developer-manual/documentation.html

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