1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5 >Documentation Guidelines</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
13 TITLE="The Git Repository"
16 TITLE="Coding Guidelines"
17 HREF="coding.html"><LINK
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
23 charset=ISO-8859-1"></HEAD
34 SUMMARY="Header navigation table"
43 >Privoxy Developer Manual</TH
80 >3. Documentation Guidelines</A
83 > All formal documents are maintained in Docbook SGML and located in the
85 CLASS="COMPUTEROUTPUT"
87 > directory. You will need
89 HREF="https://www.docbook.org/"
93 DTD's and the Docbook modular stylesheets (or comparable alternatives),
101 > (recommended) installed in order to
102 build docs from source. Currently there is <A
103 HREF="../user-manual/index.html"
111 HREF="../faq/index.html"
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
149 variation on this file, <TT
151 >privoxy-index.html</TT
153 meant for inclusion with doc packages), are maintained as SGML as well.
158 >DO NOT edit these directly</I
160 >. Edit the SGML source, or
161 contact someone involved in the documentation.
167 > requires some special handling. The reason it
168 is maintained this way is so that the extensive comments in the file
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.
178 > Other, less formal documents (e.g. <TT
182 maintained as plain text files in the top-level source directory.
185 > Packagers are encouraged to include this documentation. For those without
186 the ability to build the docs locally, text versions of each are kept in
187 Git. HTML versions are also being kept in Git under
194 > Formal documents are built with the Makefile targets of
196 CLASS="COMPUTEROUTPUT"
199 The build process uses the document SGML sources in
201 CLASS="COMPUTEROUTPUT"
202 >doc/source/*/*</SAMP
203 > to update all text files in
205 CLASS="COMPUTEROUTPUT"
207 > and to update all HTML
209 CLASS="COMPUTEROUTPUT"
210 >doc/webserver/</SAMP
214 > Documentation writers should please make sure documents build
215 successfully before committing to Git, if possible.
218 > How do you update the webserver (i.e. the pages on privoxy.org)?
226 > First, build the docs by running <SAMP
227 CLASS="COMPUTEROUTPUT"
236 CLASS="COMPUTEROUTPUT"
237 >make webserver</SAMP
240 CLASS="COMPUTEROUTPUT"
243 sourceforge webserver via ssh.
248 > Finished docs should be occasionally submitted to Git
251 >doc/webserver/*/*.html</TT
252 >) so that those without
253 the ability to build them locally, have access to them if needed.
254 This is especially important just prior to a new release! Please
265 other release specific data in <TT
269 updated (this is done just prior to a new release).
277 >3.1. Quickstart to Docbook and SGML</A
280 > If you are not familiar with SGML, it is a markup language similar to HTML.
281 Actually, not a mark up language per se, but a language used to define
282 markup languages. In fact, HTML is an SGML application. Both will use
286 > to format text and other content. SGML tags can be much
287 more varied, and flexible, but do much of the same kinds of things. The tags,
291 >, are definable in SGML. There is no set
295 >. Since we are using
299 >, our tags are those that are defined by
303 >. Much of how the finish document is
304 rendered is determined by the <SPAN
308 The stylesheets determine how each tag gets translated to HTML, or other
311 > Tags in Docbook SGML need to be always <SPAN
315 will likely generate errors. Example: <TT
318 Title</title></TT
319 >. They are also case-insensitive, but we
320 strongly suggest using all lower case. This keeps compatibility with
326 > Our documents use <SPAN
329 > for the most part. Sections
330 will be processed into HTML headers (e.g. <TT
341 will use these to also generate the Table of Contents for each doc. Our
342 TOC's are set to a depth of three. Meaning <TT
356 > will not. Each section requires
360 > element, and at least one
364 >. There is a limit of five section
365 levels in Docbook, but generally three should be sufficient for our
368 > Some common elements that you likely will use:</P
380 ><para></para></I
382 >, paragraph delimiter. Most
383 text needs to be within paragraph elements (there are some exceptions).
392 ><emphasis></emphasis></I
404 ><filename></filename></I
406 >, files and directories.
415 ><command></command></I
426 ><literallayout></literallayout></I
441 ><itemizedlist></itemizedlist></I
443 >, list with bullets.
452 ><listitem></listitem></I
454 >, member of the above.
463 ><screen></screen></I
465 >, screen output, implies
468 ><literallayout></TT
478 ><ulink url="example.com"></ulink></I
493 ><quote></quote></I
495 >, for, doh, quoting text.
503 > Look at any of the existing docs for examples of all these and more.</P
505 > You might also find
510 HREF="https://web.archive.org/web/20160315230758/http://opensource.bureau-cornavin.com/crash-course/index.html"
512 > Writing Documentation Using DocBook - A Crash Course</A
525 > Documentation Style</A
528 > It will be easier if everyone follows a similar writing style. This
529 just makes it easier to read what someone else has written if it
530 is all done in a similar fashion.
540 > All tags should be lower case.
545 > Tags delimiting a <SPAN
551 > of text (even small
552 blocks) should be on their own line. Like:
555 CLASS="LITERALLAYOUT"
556 > <para><br>
557 Some text goes here.<br>
558 </para></P
560 > Tags marking individual words, or few words, should be in-line:
563 CLASS="LITERALLAYOUT"
564 > Just to <emphasis>emphasize</emphasis>, some text goes here.</P
568 > Tags should be nested and step indented for block text like: (except
572 CLASS="LITERALLAYOUT"
573 > <para><br>
574 <itemizedlist><br>
575 <para><br>
576 <listitem><br>
577 Some text goes here in our list example.<br>
578 </listitem><br>
579 </para><br>
580 </itemizedlist><br>
581 </para></P
583 > This makes it easier to find the text amongst the tags ;-)
588 > Use white space to separate logical divisions within a document,
589 like between sections. Running everything together consistently
590 makes it harder to read and work on.
595 > Do not hesitate to make comments. Comments can either use the
596 <comment> element, or the <!-- --> style comment
597 familiar from HTML. (Note in Docbook v4.x <comment> is
598 replaced by <remark>.)
603 > We have an international audience. Refrain from slang, or English
604 idiosyncrasies (too many to list :). Humor also does not translate
610 > Try to keep overall line lengths in source files to 80 characters or less
611 for obvious reasons. This is not always possible, with lengthy URLs for
617 > Our documents are available in differing formats. Right now, they
618 are just plain text and/or HTML, but others are always a
619 future possibility. Be careful with URLs (<ulink>), and avoid
623 > My favorite site is <ulink url="http://example.com">here</ulink>.
626 > This will render as <SPAN
628 >"My favorite site is here"</SPAN
630 not real helpful in a text doc. Better like this:
633 > My favorite site is <ulink url="http://example.com">example.com</ulink>.
638 > All documents should be spell checked occasionally.
642 > can check SGML with the
660 NAME="CUSTOM-ENTITIES"
661 >3.3. Privoxy Custom Entities</A
667 > documentation is using
668 a number of customized <SPAN
672 documentation maintenance.
675 > We are using a set of <SPAN
678 > files with generic text,
679 that is used by multiple docs. This way we can write something once, and use
680 it repeatedly without having to re-write the same content over and over again.
681 If editing such a file, keep in mind that it should be
688 >. That is the purpose; so it can be used in varying
689 contexts without additional modifications.
692 > We are also using what <SPAN
698 >"internal entities"</SPAN
699 >. These are like variables in
700 programming. Well, sort of. For instance, we have the
704 > entity that contains the current
708 > version string. You are strongly
709 encouraged to use these where possible. Some of these obviously
710 require re-setting with each release (done by the Makefile). A sampling of
711 custom entities are listed below. See any of the main docs for examples.
721 > text entities are defined like:
726 ><!entity supported SYSTEM "supported.sgml"></TT
730 > In this example, the contents of the file,
734 > is available for inclusion anywhere
735 in the doc. To make this happen, just reference the now defined
739 > (starts with an ampersand
740 and ends with a semi-colon), and the contents will be dumped into
741 the finished doc at that point.
746 > Commonly used <SPAN
748 >"internal entities"</SPAN
768 version string, e.g. <SPAN
782 >: the project status, either
803 >: use to conditionally include
807 > releases (e.g. <SPAN
821 >: just the opposite.
832 >: this doc is only generated as text.
842 > There are others in various places that are defined for a specific
843 purpose. Read the source!
852 SUMMARY="Footer navigation table"
891 >The Git Repository</TD
901 >Coding Guidelines</TD