From: hal9 Date: Mon, 8 Apr 2002 15:31:18 +0000 (+0000) Subject: Touch ups to documentation section. X-Git-Tag: v_2_9_14~153 X-Git-Url: http://www.privoxy.org/gitweb/@default-cgi@/faq/%22https:/@default-cgi@show-url-info?a=commitdiff_plain;h=f613287b6050bbb3f4d21d02cf7035966e10d6d5;p=privoxy.git Touch ups to documentation section. --- diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index a3b87800..23d47193 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -21,7 +21,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $ + $Id: developer-manual.sgml,v 1.26 2002/04/07 23:50:08 hal9 Exp $ Written by and Copyright (C) 2001 the SourceForge Privoxy team. http://www.privoxy.org/ @@ -44,7 +44,7 @@ Privoxy Developer Manual - $Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $ + $Id: developer-manual.sgml,v 1.26 2002/04/07 23:50:08 hal9 Exp $ @@ -157,28 +157,27 @@ following guidelines for changing stuff in the code. If it is All formal documents are maintained in docbook SGML and located in the doc/source/* directory. You will need - docbook and the docbook - stylesheets (or comparable alternatives), and either - jade or openjade - (recommended) installed in order to build docs from source. Currently - there is Docbook, the Docbook + DTD's and the Docbook modular stylesheets (or comparable alternatives), + and either jade or + openjade (recommended) installed in order to + build docs from source. Currently there is user-manual, - FAQ, and, - of course this, the developer-manual in this - format. The README, AUTHORS - privoxy.1 (man page) - files are also now maintained - as SGML. The finished files are all in the top-level source - directory are generated files! Also, index.html, - the Privoxy home page, is maintained - as sgml. DO NOT edit these - directly. Edit the SGML source, or contact someone - involved in the documentation (at present Stefan and Hal). + FAQ, and, of + course this, the developer-manual in this format. + The README, AUTHORS + privoxy.1 (man page) files are also now maintained + as Docbook SGML. The finished files are all in the top-level source + directory are generated files! Also, index.html, the + Privoxy home page, is maintained as SGML. + DO NOT edit these directly. Edit the SGML source, or + contact someone involved in the documentation (at present Stefan and + Hal). - Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as - plain text files in the toplevel source directory. At least for the - time being. + Other, less formal documents (e.g. LICENSE, + INSTALL) are maintained as plain text files in the + toplevel source directory. At least for the time being. Packagers are encouraged to include this documentation. For those without @@ -191,7 +190,7 @@ following guidelines for changing stuff in the code. If it is make dok, or alternately make redhat-dok. If you have problems, try both. The build process uses the document SGML sources in - doc/source/* to update all text files in + doc/source/*/* to update all text files in doc/text/ and to update all HTML documents in doc/webserver/. @@ -222,24 +221,25 @@ following guidelines for changing stuff in the code. If it is Quickstart to Docbook and SGML If you are not familiar with SGML, it is a markup language similar to HTML. - In fact, HTML is an SGML application. Both use tags - to format text and other content. SGML tags are much more varied, - and flexible, but do much of the same kinds of things. The tags, - or elements, are definable in SGML. There is no - set standards. Since we are using - Docbook, our tags are those that are - defined by Docbook. Much of how the - finish document is rendered is determined by the stylesheets. - The stylesheets determine how each tag gets translated to HTML, or - other formats. + Actually, not a mark up language per se, but a language used to define + markup languages. In fact, HTML is an SGML application. Both will use + tags to format text and other content. SGML tags can be much + more varied, and flexible, but do much of the same kinds of things. The tags, + or elements, are definable in SGML. There is no set + standards. Since we are using + Docbook, our tags are those that are defined by + Docbook. Much of how the finish document is + rendered is determined by the stylesheets. + The stylesheets determine how each tag gets translated to HTML, or other + formats. - Tags in SGML need to be always closed. If not, you - will likely generate errors. Example: - <title>My Title</title>. They are - also case-insensitive, but we strongly suggest using all lower - case. This keeps compatibility with [Docbook] XML. + Tags in Docbook SGML need to be always closed. If not, you + will likely generate errors. Example: <title>My + Title</title>. They are also case-insensitive, but we + strongly suggest using all lower case. This keeps compatibility with + [Docbook] XML. @@ -263,10 +263,10 @@ following guidelines for changing stuff in the code. If it is <para></para>, paragraph delimiter. Most - text needs to be within paragraph elements. + text needs to be within paragraph elements (there are some exceptions). - <emphasis></emphasis>, stylesheets make this + <emphasis></emphasis>, the stylesheets make this italics. @@ -325,8 +325,8 @@ following guidelines for changing stuff in the code. If it is - Tags delimiting a block of text should be on their - own line. Like: + Tags delimiting a block of text (even small + blocks) should be on their own line. Like: <para> Some text goes here. @@ -340,8 +340,9 @@ following guidelines for changing stuff in the code. If it is - Tags should be nested and step indented like (except in-line tags): - + Tags should be nested and step indented for block text like: (except + in-line tags) + <para> <itemizedlist> <para> @@ -439,8 +440,8 @@ following guidelines for changing stuff in the code. If it is p-version entity that contains the current Privoxy version string. You are strongly encouraged to use these where possible. Some of these obviously - require re-setting with each release. A sampling of custom entities are - listed below. See any of the main docs for examples. + require re-setting with each release (done by the Makefile). A sampling of + custom entities are listed below. See any of the main docs for examples. @@ -1627,7 +1628,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.26 2002/04/07 23:50:08 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -1687,7 +1688,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.26 2002/04/07 23:50:08 hal9 Exp $" /********************************************************************* * * File : $Source$ @@ -2413,6 +2414,10 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 1.26 2002/04/07 23:50:08 hal9 + Documentation changes to reflect HTML docs now in CVS, and new generated files + list. + Revision 1.25 2002/04/06 05:07:28 hal9 -Add privoxy-man-page.sgml, for man page. -Add authors.sgml for AUTHORS (and p-authors.sgml)