doc/webserver/developer-manual/documentation.html

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