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