{\rtf1\mac\ansicpg10000\cocoartf824\cocoasubrtf420
{\fonttbl\f0\froman\fcharset77 TimesNewRomanPS-BoldMT;\f1\froman\fcharset77 TimesNewRomanPSMT;\f2\froman\fcharset77 TimesNewRomanPS-ItalicMT;
\f3\froman\fcharset77 TimesNewRomanPS-BoldItalicMT;\f4\fmodern\fcharset77 Courier;\f5\fswiss\fcharset77 Helvetica;
}
{\colortbl;\red255\green255\blue255;}
{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc1\levelnfcn1\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{upper-roman\}.}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listlevel\levelnfc0\levelnfcn0\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid1\'02\'05.;}{\levelnumbers\'01;}}{\listlevel\levelnfc4\levelnfcn4\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{lower-alpha\}.}{\leveltext\leveltemplateid2\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid1}
{\list\listtemplateid2\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid2}
{\list\listtemplateid3\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid3}
{\list\listtemplateid4\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid4}
{\list\listtemplateid5\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid5}
{\list\listtemplateid6\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid6}
{\list\listtemplateid7\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid7}
{\list\listtemplateid8\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid8}
{\list\listtemplateid9\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid9}
{\list\listtemplateid10\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid10}
{\list\listtemplateid11\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid11}
{\list\listtemplateid12\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid12}
{\list\listtemplateid13\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid13}
{\list\listtemplateid14\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid14}
{\list\listtemplateid15\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid15}
{\list\listtemplateid16\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid16}
{\list\listtemplateid17\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid17}
{\list\listtemplateid18\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid18}
{\list\listtemplateid19\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid19}
{\list\listtemplateid20\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid20}
{\list\listtemplateid21\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid21}
{\list\listtemplateid22\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid22}
{\list\listtemplateid23\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid23}
{\list\listtemplateid24\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid24}
{\list\listtemplateid25\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid25}}
{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}{\listoverride\listid3\listoverridecount0\ls3}{\listoverride\listid4\listoverridecount0\ls4}{\listoverride\listid5\listoverridecount0\ls5}{\listoverride\listid6\listoverridecount0\ls6}{\listoverride\listid7\listoverridecount0\ls7}{\listoverride\listid8\listoverridecount0\ls8}{\listoverride\listid9\listoverridecount0\ls9}{\listoverride\listid10\listoverridecount0\ls10}{\listoverride\listid11\listoverridecount0\ls11}{\listoverride\listid12\listoverridecount0\ls12}{\listoverride\listid13\listoverridecount0\ls13}{\listoverride\listid14\listoverridecount0\ls14}{\listoverride\listid15\listoverridecount0\ls15}{\listoverride\listid16\listoverridecount0\ls16}{\listoverride\listid17\listoverridecount0\ls17}{\listoverride\listid18\listoverridecount0\ls18}{\listoverride\listid19\listoverridecount0\ls19}{\listoverride\listid20\listoverridecount0\ls20}{\listoverride\listid21\listoverridecount0\ls21}{\listoverride\listid22\listoverridecount0\ls22}{\listoverride\listid23\listoverridecount0\ls23}{\listoverride\listid24\listoverridecount0\ls24}{\listoverride\listid25\listoverridecount0\ls25}}
{\info
{\title PHP Documentation Build System Proposal}
{\author Gwynne Raskind}
{\keywords PHP, buildsystem, proposal}}\margl1440\margr1440\vieww12240\viewh13340\viewkind1\viewscale100
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 \ul \ulc0 PHP Documentation Build System
\f1\b0 \
\

\f2\i\fs28 \ulnone Copyright (c) 2007 by the Author(s) as set out on page 2. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at {\field{\*\fldinst{HYPERLINK "http://www.opencontent.org/openpub/"}}{\fldrslt http://www.opencontent.org/openpub/}}).
\f1\i0\fs32 \ul \
\

\f3\i\b\fs28 \ulnone Last updated: 4/6/2007
\f1\i0\b0\fs32 \ul \
\

\f0\b \ulnone Table of Contents\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls1\ilvl0
\f1\b0\fs28 \cf0 {\listtext	I.	}Introduction\
{\listtext	II.	}Requirements of a modular build system\
{\listtext	III.	}Advantages of a new system\
{\listtext	IV.	}Disadvantages of a new system\
{\listtext	V.	}Discussion on inclusion/replacement\
\pard\tx940\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li1440\fi-1440\ql\qnatural\pardirnatural
\ls1\ilvl1\cf0 {\listtext	1.	}Entities\
{\listtext	2.	}Processing instructions\
{\listtext	3.	}Custom namespace and elements\
{\listtext	4.	}Pure PHP preprocessing\
{\listtext	5.	}PHP + XInclude\
{\listtext	6.	}Final conclusion\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls1\ilvl0\cf0 {\listtext	VI.	}Discussion on publishing\
\pard\tx940\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li1440\fi-1440\ql\qnatural\pardirnatural
\ls1\ilvl1\cf0 {\listtext	1.	}DSSSL\
{\listtext	2.	}XSLT\
{\listtext	3.	}Pure PHP postprocessing\
\pard\tx1660\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li2160\fi-2160\ql\qnatural\pardirnatural
\ls1\ilvl2\cf0 {\listtext	a.	}Regular expression processing (string replacement)\
{\listtext	b.	}DOM/XMLReader walking\
{\listtext	c.	}Embedded XSLT\
{\listtext	d.	}External XSLT\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls1\ilvl0\cf0 {\listtext	VII.	}Discussion on themes\
{\listtext	VIII.	}Basic implementation\
{\listtext	IX.	}Checklist of functionality\
{\listtext	X.	}System naming proposals\
{\listtext	XI.	}System licensing proposals\
{\listtext	XII.	}Revision history\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 I. Introduction\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 	The current system for building the PHP documentation is old, clunky, and confusing. It contains endless ill-understood hacks and does not address the current needs of the documenters and translators. The intended replacement, currently called "livedocs," is even more problematic. It is the opinion of the author(s) of this proposal that it is time to admit the failings of the systems that exist and begin again.\
	This proposal covers 
\f0\b only
\f1\b0  the build system, which is to say the implementation intended to turn the completed XML files which make up a given set of documentation into a presentable format for users in real time. This proposal does not discuss, except as necessary, the format or content of the documentation itself; the system described herein is intended to be able to work with a range of documentation efforts.\
\
	In this proposal, the following common terms are used. Most of these conform roughly to the definitions presented by RFC 2119 (Key words for use in RFCs to Indicate Requirement Levels {\field{\*\fldinst{HYPERLINK "http://www.ietf.org/rfc/rfc2119.txt"}}{\fldrslt http://www.ietf.org/rfc/rfc2119.txt}}):\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls2\ilvl0\cf0 {\listtext	\'a5	}MUST - The topic under discussion is not optional in any way.\
{\listtext	\'a5	}MUST NOT - The topic under discussion MUST be omitted.\
{\listtext	\'a5	}SHOULD - The topic under discussion is optional, but strongly recommended.\
{\listtext	\'a5	}SHOULD NOT - The topic under discussion is optional, but strongly discouraged.\
{\listtext	\'a5	}MAY - The topic under discussion is optional.\
{\listtext	\'a5	}target system - The computer system upon which the topic is deployed, and the administrator of that system.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 Author(s):\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\i\b0\fs24 \cf0 This is a normative list of authors who have contributed to this document and how to contact them.
\f0\i0\b\fs28 \
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls3\ilvl0
\f1\b0 \cf0 {\listtext	\'a5	}Gwynne Raskind (gwynne at php dot net)
\fs32 \
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls3\ilvl0
\f2\i\fs28 \cf0 {\listtext	\'a5	}<add others here as necessary>
\f1\i0\fs32 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 II. Requirements of a modular build system\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 	\
	The build system proposed by this document has several requirements for successful implementation and acceptance. They are:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls4\ilvl0\cf0 {\listtext	\'a5	}The build system MUST be able to process a wide range of documentation efforts, including but not limited to, the PHP user documentation, the PHP internals documentation, the PEAR documentation, the PECL documentation, the Smarty documentation, the PHP-GTK documentation, and the meta-documentation (documentation regarding the writing of documentation).\
{\listtext	\'a5	}The build system MUST be able to dynamically select any available translation of a given set of documentation, with an effective fallback mechanism to handle the possibility of incomplete or missing translations.\
{\listtext	\'a5	}The build system MUST be able to successfully process the entire DocBook 5 content model by whatever means available to it, including if necessary a fallback mechanism to contend with unrecognized elements.\
{\listtext	\'a5	}The output model of the build system SHOULD be as flexible as possible, with the ability to select various presentation formats, including but not limited to, XML, HTML, WML, PDF, and plain text. For an initial implementation, HTML output only will suffice, but the system MUST be designed with this requirement in mind.\
{\listtext	\'a5	}The build system MUST present a simple usage paradigm to those not already familiar with its workings.\
{\listtext	\'a5	}The build system MUST NOT rely upon any tool or library present on the target system save PHP, unless another tool is deemed absolutely necessary in the fulfillment of the other requirements. It MAY depend on the presence of various PHP extensions, limited to those distributed with PHP 5.2 or later. The system MUST NOT rely upon PHP 6, but SHOULD be prepared for its presence, even if only by exiting with an error in that case. Exceptions to this rule will be determined on a case-by-case basis by the authors.\
{\listtext	\'a5	}The build system MUST be as Unicode-aware as is reasonably possible. This includes but is not limited to respecting the encoding parameter of <?xml?> prologs, providing a heuristic for guessing the encoding of an undeclared file, handling UTF-8 validation failures gracefully, and dynamically presenting all output in either UTF-8 or an encoding of the target system's choice.\
{\listtext	\'a5	}The build system MUST NOT attempt to fulfill roles outside its intended scope. Examples of this are management of the main PHP Web site, the presentation of small documents such as this proposal, and versioning of documentation.\
{\listtext	\'a5	}The build system SHOULD be aware of any version control system in use, such as CVS or Subversion, and SHOULD make reasonable efforts to require that documents it processes have been successfully submitted to that system. The build system MAY place this validation under control of the target system.\
{\listtext	\'a5	}The build system SHOULD make every effort, as the present system does, to ensure that any translated documentation used is up to date with respect to the original English documentation. This effort SHOULD be integrated with support for a version control system.\
{\listtext	\'a5	}If the build system presents the need for changes to the structure of the documentation files themselves, it MUST provide a tested and accurate converter method to update every existing file to the new format, including translations and the revision tracking therein.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 III. Advantages of a new system
\f1\b0\fs28 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs24 \cf0 \
	
\f1\b0\fs28 It is always a difficult thing to put aside work that currently exists on a project in favor of starting over from scratch. Here we discuss the reasons that a new system is preferred to attempting to repair the old efforts.\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls5\ilvl0\cf0 {\listtext	1.	}The old efforts are poorly designed. They do not take into account current issues of formatting and validation, nor are they extendable into the requirements of a useful build system.\
{\listtext	2.	}The old efforts are poorly implemented. They use (ironically) undocumented tricks and significant hardcoded data to accomplish a purpose, and are subject to breakage under the least pressure. In short, what we've got is a hack and it sucks.\
{\listtext	3.	}The old efforts were not written with current requirements in mind. They do not support multiple projects, are not portable, are difficult to configure at best, and rely heavily on a number of external tools with known bugs and strange characteristics.\
{\listtext	4.	}The old efforts are inefficient. The effort necessary to address this while also handling all the other problems is highly prohibitive.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	To summarize, the old systems would have to rewritten in place anyway in order to fulfill all the requirements of current development. This is much more difficult and error-prone than working from a clean slate.\
\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 IV. Disadvantages of a new system\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 \
	With the comments in section III in mind, there are some disadvantages to starting over:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls6\ilvl0\cf0 {\listtext	1.	}The old systems, phpdoc and livedocs, work as they are. A new system will go through significant development and testing before it can be considered usable.\
{\listtext	2.	}The development time to design and create a new system is non-negligible. The needs of the community might not be best addressed by this path.\
{\listtext	3.	}The effort of creating a new build system will remove documenters and coders from their efforts to improve the working documentation and code, and focus them on a new effort that some might consider unnecessary.\
{\listtext	4.	}A new system may present issues to translators, who are used to the old systems, if changes are necessary to the documentation files themselves.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	With all of these factors, and the previously mentioned ones, considered, it is the considered opinion of the authors of this proposal that it is better to accept the problems inherent in the creation of a new system than to live with the problems presented by the existing ones.\
\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 V. Discussion on inclusion/replacement\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 \
	By its very nature, a large documentation project which uses DocBook XML requires as a matter of practicality a means of embedding self-contained XML documents within others, as well as a means of representing repeating text without actual duplication. There are several possible mechanisms by which this can be accomplished.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 1. Entities\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 	\
	The use of SGML entity replacement is the method currently in use by the existing system. It involves generating a list of files which will be included by the documentation project, translating those into <!ENTITY name SYSTEM ""> declarations, and making use of those entities in the XML documents. For blocks of recurring text, an <!ENTITY name ""> declaration is used. Example:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 <?xml version="1.0" encoding="utf-8"?>\
<!DOCTYPE section [\
<!ENTITY install.index SYSTEM "@LANG@/install/index.xml">\
<!ENTITY return.true "returns &true;">\
<!ENTITY true "<constant>true</constant>">\
]>\
<section xml:id="install.wrapper" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">\
 &install.index;\
 <note>\
  <para>\
   The <function>install_me</function> function defined above &return.true;.\
  </para>\
 </note>\
</section>\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 \
Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls7\ilvl0\cf0 {\listtext	\'a5	}Entities are a time-tested and proven method of performing the tasks required. There is ample support for their use in any given tool.\
{\listtext	\'a5	}Entities are the current system in use and would not require any changes to the existing documentation files.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls8\ilvl0\cf0 {\listtext	\'a5	}Entities require the pre-generation of complex and complete lists of files before they can be used successfully.\
{\listtext	\'a5	}The semantics of escaping content within entities are poorly-defined and ill-equipped to the tasks set to them.\
{\listtext	\'a5	}Entity replacement is time-consuming and generates large amounts of "noise" content.\
{\listtext	\'a5	}Entity replacement has no well-defined fallback mechanism for undefined entities.\
{\listtext	\'a5	}Validating XML parsers can easily be fooled into missing misused entity references.\
{\listtext	\'a5	}External entity references are fragile; any change whatsoever in document structure will completely break all usage within that structure.\
{\listtext	\'a5	}Entities are not easily synchronized with ID declarations, leading to confusion.\
{\listtext	\'a5	}Per-file entities are problematic and impossible to implement properly due to limitations of tools.\
{\listtext	\'a5	}Requires extra processing to determine the language tree to include from.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	Entities, while an effective means for simple replacements, are not suited to the larger tasks required by the build system and are not a candidate for use in the author(s)' opinion.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 2. Processing instructions\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 \
	Another SGML-defined method for handling content modification is the concept of processing instructions, which is any content contained within a sequence such as '<?identifier 
\f2\i content here
\f1\i0  ?>'. The identifier is used to determine what part of the processing pipeline should handle the instructions. PHP itself uses this with the <?php?> paradigm, and the <?xml?> prolog declaration should be familiar to anyone reading this proposal. To use processing instructions to this purpose, a new identifier would be defined (a simple one such as 'docbuild' would suffice), and such instructions would be either pre-processed by a PHP script for the purpose, or handled inline during DOM traversal. An example:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 <?xml version="1.0" encoding="utf-8"?>\
<section xml:id="install.wrapper" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">\
<?docbuild\
	define true "<constant>true</constant>";\
	define return.true "returns %true";\
?>\
<?docbuild include install/index.xml ?>\
 <note>\
  <para>\
   The <function>install_me</function> function defined above <?docbuild "%return.true" ?>.\
  </para>\
 </note>\
</section>\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 \
Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls9\ilvl0\cf0 {\listtext	\'a5	}Processing instructions are legal SGML and XML, and will have no effect upon the document tree if skipped or processed incorrectly.\
{\listtext	\'a5	}The interior content of a processing instruction is SGML CDATA rather than PCDATA, making escaping unnecessary.\
{\listtext	\'a5	}Processing instructions are recognized by all XML APIs, allowing for both preprocessing and tree-traversal processing depending upon which is more effective.\
{\listtext	\'a5	}The syntax of the processing instruction content is infinitely malleable.\
{\listtext	\'a5	}Doesn't require any extra processing to determine the language tree to include from.\
{\listtext	\'a5	}Allows the parser to handle fallback conditions as it chooses.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls10\ilvl0\cf0 {\listtext	\'a5	}The syntax for processing instructions, while clean and explicit, is nonetheless bulky.\
{\listtext	\'a5	}Processing the content of a processing instruction requires a parser for the syntax chosen, which may be slow and is likely to be error-prone.\
{\listtext	\'a5	}if <?php?> instructions are used to simplify the processing, danger of malicious use by any with documentation karma, especially translators, is difficult to mitigate.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	While processing instructions are a powerful and flexible tool for embedding extra commands into XML, they are not suited to this purpose and are not considered a candidate for use by the author(s).\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 3. Custom namespace and elements\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 	\
	Similarly to processing instructions, it is possible to define an XML element namespace and a set of elements and attributes to handle the necessary substitutions. Such a namespace would look something like this:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 <?xml version="1.0" encoding="utf-8"?>\
<section xml:id="install.wrapper" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:db="http://doc.php.net/ns/docbuild">\
 <db:define name="true"><constant>true</constant></db:define>\
 <db:define name="return.true">returns <db:constant name="true"/></db:define>\
 <db:include xlink:href="install/index.xml"/>\
 <note>\
  <para>\
   The <function>install_me</function> function defined above <db:constant name="return.true"/>.\
  </para>\
 </note>\
</section>\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 \
	This defines a new namespace called "db", which provides three elements: define, include, and constant.\
\
Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls11\ilvl0\cf0 {\listtext	\'a5	}Extremely flexible.\
{\listtext	\'a5	}Allows for integrated validation of all content within the namespace.\
{\listtext	\'a5	}Intuitive syntax which integrates with DocBook content seamlessly.\
{\listtext	\'a5	}Able to take advantage of XLink and any other XML extensions.\
{\listtext	\'a5	}Integrates into DOM/SAX parsing seamlessly (see Section 6.3.3 for more)\
{\listtext	\'a5	}Allows the parser to decide how to handle fallback situations.\
{\listtext	\'a5	}Doesn't require any extra processing to determine the language tree to include from.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls12\ilvl0\cf0 {\listtext	\'a5	}As with all readable XML syntax, the usage of the namespace is bulky.\
{\listtext	\'a5	}The namespace would add even more data to the root element for every file, increasing the risks of difficult-to-diagnose errors.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	Namespaces are an extremely viable and flexible option for this type of use, and deserve serious consideration despite the drawbacks. The author(s) consider it the primary recommendation for use.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 4. Pure PHP preprocessing\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 	\
	Since the entire buildsystem is based on PHP as a prerequisite, it is of course possible to use PHP itself to do the needed processing. Here's an example of how that might be done:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 <?xml version="1.0" encoding="utf-8"?>\
<section xml:id="install.wrapper" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">\
#INCLUDE "install/index.xml"#\
#DEFINE "true" "<constant>true</constant>"#\
#DEFINE "return.true" "returns %true%"#\
 <note>\
  <para>\
   The <function>install_me</function> defined above %return.true%.\
  </para>\
 </note>\
</section>\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls13\ilvl0\cf0 {\listtext	\'a5	}Again, high flexibility of syntax.\
{\listtext	\'a5	}Preprocessing of this kind can be done in a single step using regular expression replacements rather than lexical parsing.\
{\listtext	\'a5	}Less bulky syntax.\
{\listtext	\'a5	}Provides a system-definable fallback mechanism.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls14\ilvl0\cf0 {\listtext	\'a5	}Again, complexity of parsing. The instructions, no matter how rigidly defined, are potentially prone to parsing errors.\
{\listtext	\'a5	}The use of any form of escaping to allow for literal interpretation of the instructions makes the parsing significantly harder, potentially eliminating any efficiency gain from single-step replacement.\
{\listtext	\'a5	}Necessity of careful review of all existing documents to ensure proper escaping is done by any conversion tool\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	The complexity and efficiency loss of this type of parsing tends to outweigh the benefits of the flexibility and single-step replacements, but those benefits are still worthy of consideration. The author(s) consider this a fallback possibility if other options are rejected.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 5. PHP + XInclude
\f1\b0 \
	\
	The final possibility is a combination of the XInclude XML extension ({\field{\*\fldinst{HYPERLINK "http://www.w3.org/TR/xinclude/"}}{\fldrslt http://www.w3.org/TR/xinclude/}}) and PHP processing, since XInclude provides a very powerful, considered, and standardized syntax for XML tree inclusion but lacks in text replacement facilities. An example of this usage would look like:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 <?xml version="1.0" encoding="utf-8"?>\
<section xml:id="install.wrapper" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http:///www.w3.org/2001/XInclude">\
\
<xi:include href="@LANG@/install/index.xml" parse="xml"><xi:fallback>Missing file install/index.xml!</xi:fallback></xi:include>\
#DEFINE "true" "<constant>true</constant>"#\
#DEFINE "return.true" "returns %true%"#\
 <note>\
  <para>\
   The <function>install_me</function> defined above %return.true%.\
  </para>\
 </note>\
</section>\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls15\ilvl0\cf0 {\listtext	\'a5	}Takes advantage of XInclude, which was especially designed for the purpose of embedding XML trees in others using file references and is supported as a W3C standard.\
{\listtext	\'a5	}Simplifies the necessary parsing for the PHP processing considerably by folding an entire subset of functionality into libxml's existing capabilities.\
{\listtext	\'a5	}Implements a powerful and effective fallback mechanism without any effort from the parser.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls16\ilvl0\cf0 {\listtext	\'a5	}All of the issues previously discussed in section 5.4 regarding pure PHP processing.\
{\listtext	\'a5	}All of the issues previously discussed in section 5.3 regarding custom namespaces.\
{\listtext	\'a5	}Requires extra processing to determine the language tree to include from.\
{\listtext	\'a5	}XInclude's fallback syntax is unwieldy and unsuitable with respect to this purpose; automatic fallback provisions provided by the parser are much more effective.\
{\listtext	\'a5	}XInclude does not integrate itself with XLink, instead choosing to use XPointer syntax, which has a steep learning curve similar to that of XPath and is unsuitable for casual developers working on documentation.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	While XInclude is a powerful syntax with the support of standards and the XML library, it simply is not suited to this task; the only way to make it work would be to implement two-stage parsing, transforming a custom form of include into XInclude directives and passing the resulting tree back through libxml recursively. This is highly inefficient and not worth the effort. The author(s) do not consider this a viable option for use.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 6. Final Conclusion\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 \
	All of the possibilities discussed have drawbacks. This is inevitable in a system that must integrate itself in a usable way with a strict and verbose format like XML. Because this must be accepted, it is best to go with a solution which presents the least problems to both the system developers and the end users (i.e. the documenters and translators).\
	The translators do not concern themselves with the markup of documentation and therefore need be considered only in terms of making what they do translate accessible to them. The documenters, in general, are experienced coders in their own right and thus can be expected to successfully handle a reasonable amount of complexity and/or any reasonable requirement of basic coding knowledge.\
	With these factors in mind, we believe the best option for a completely new buildsystem is the the custom namespace. It integrates the most completely with current syntax, provides the maximum flexibility, offers full expandability and extendability, and requires very little effort to convert the old format to the new one it would require. This option is also explicitly supported by DocBook 5.\
	The problems discussed with this option are:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls17\ilvl0\cf0 {\listtext	\'a5	}Bulky syntax. This is unavoidable with any truly useful option, and can be mitigated somewhat by providing shortcut element and attribute names. For example, "
\f4\fs24 <db:constant name="return.true"/>
\f1\fs28 " could be shortened as "
\f4\fs24 <d:c n="return.true"/>
\f1\fs28 ". It is still bulky, and a little less readable, but there is a great deal of middle ground to work with.\
{\listtext	\'a5	}More declarations in the root. This is another fact of life when dealing with extensible XML. Since most or all documenters use templates or examples when creating new documentation files, keeping those up to date and providing the declaration in all existing files should make this a small problem at worst.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	With all of this in mind, here is a proposed syntax for the long and short versions of the namespace:\
\
<include> element\
	Aliases:\
		None. This element does NOT require shorthand use.\
	Attributes:\
		xlink:href - The XLink URI of the target resource. This is intended to be modified by the parser as needed to support base URIs, language tree choices, and any other necessary factors. This URI is intended as an identifier far more than as a literal file reference. This attribute is EXCLUSIVE with respect to the target attribute, and one or the other is REQUIRED.\
		target - An IDREF identifying the ID of the file to include, as defined by the xml:id attribute on the file's root element. This is the PREFERRED way to identify an include target. This attribute is EXCLUSIVE with the xlink:href attribute, and one or the other is REQUIRED.\
	Content:\
		Empty\
\
<define> element\
	Aliases:\
		None. This element does NOT require shorthand use.\
	Attributes:\
		xml:id - The name of the constant being defined. This must be a valid XML ID. This attribute is REQUIRED.\
	Content:\
		PCDATA - The replacement text of the constant, processed by the PHP trim() function or equivalent. Markup found herein is passed through completely unmodified as a text node, but it is STRONGLY recommended to use <![CDATA[]]> for such cases.\
\
<constant> element\
	Aliases:\
		<c> - This element has extensive use in inline text and can be abbreviated. A document may use one or the other form, but MUST maintain consistency in usage within itself.\
		n - The "name" attribute MAY be shortened to "n". One or the other form MAY be used in any given element, but a document MUST maintain consistency in usage within itself.\
	Attributes:\
		name - An IDREF to the <define> element which represents the constant that should be replaced. This attribute is REQUIRED.\
	Content:\
		Empty\
\
<revision> element:\
	Aliases:\
		None. This element does NOT require shorthand use.\
	Attributes:\
		None.\
	Content:\
		Always contains a <my-rev> element.\
		May optionally contain an <en-rev> element after <my-rev>.\
\
<my-rev>, <en-rev> elements:\
	Aliases:\
		None. These elements do NOT require shorthand use.\
	Attributes:\
		None.\
	Content\
		A single CVS/SVN revision tag in the regular expression form "\\$Rev(ision)?: (\\d+)\\.(\\d+)(\\.(\\d+))+\\$".\
\
\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 VI. Discussion on publishing\
	\
	
\f1\b0\fs28 There are a number of available methods for the publishing of the DocBook XML documents we have just finished describing. We take a look at each of them here and discuss their relation to the build system requirements.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 1. DSSSL\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 	\
	The first option is the old tried and true DSSSL stylesheet transformations.\
	\
Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls18\ilvl0\cf0 {\listtext	\'a5	}None!\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls19\ilvl0\cf0 {\listtext	\'a5	}DSSSL is poorly understood.\
{\listtext	\'a5	}Jade (a DSSSL implementation) is not suited towards realtime transformations.\
{\listtext	\'a5	}No one wants to maintain a DSSSL setup.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	DSSSL isn't a real option.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 2. XSLT\
	\
	
\f1\b0 Another tried and true idea is XSLT transformations.\
\
Pros:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls20\ilvl0\cf0 {\listtext	\'a5	}Support of the DocBook community.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Cons:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls21\ilvl0\cf0 {\listtext	\'a5	}Complex customization layers are required for PHP documentation transformations.\
{\listtext	\'a5	}XSLT is difficult to maintain.\
{\listtext	\'a5	}XSLT is too slow for realtime transformations.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
Conclusion:\
	XSLT has served for awhile, but isn't a workable option anymore.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 3. Pure PHP postprocessing\
	\
	
\f1\b0 This is a PHP system, right? Let's use some PHP! Here we discuss some of the options for doing all this crud with a real language.
\f0\b \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 a. Regular expression processing (string replacement)\
\
	Extremely complicated and error-prone. No.\
\
b. DOM/XMLReader/XMLWriter walking\
	\
	This means using the XMLReader pull model, or a DOM tree traversal, to transform the source DocBook trees into the PHP/XHTML display form shown to the user, possibly using the XMLWriter API as well. This is flexible, extensible, and likely to be the most efficient option available. This, of course, is dependent upon the proper implementation of the idea, which includes content caching and pregeneration of indices.\
\
c. Embedded XSLT\
d. External XSLT\
\
	Embed some XSLT or XSL files and do spot transformations in PHP. Pointless, it's as bad as using pure XSLT.\
\
Comclusion:\
	\
	Looks like tree traversal is the way to go. There's really no complex analysis needed for this decision; XSLT is too slow and DSSSL doesn't do what we need. Tree traversal allows for realtime transformation, and themes can freely define header, footer, and style material for the walker code.\
\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 VII. Discussion on themes\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 \
	One of the core requirements of the new system is that it have flexible theming capability. This includes:\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls22\ilvl0\cf0 {\listtext	\'a5	}Allowing themes to define the entire set of style information used by whatever transformation turns the DocBook XML into XHTML.\
{\listtext	\'a5	}Allowing themes to flexibly define headers and footers which can include PHP commands.\
{\listtext	\'a5	}Allowing themes to specify various options, such as language restrictions, depth of page separation, depth of ToC generation, and reference material formatting.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	Since the entire system is implemented in PHP, and theme authors can be considered a "trusted" group, themes can be implemented as a PHP 
\f4\fs24 interface
\f1\fs28 . A theme would implement the interface, making the only necessary configuration to pick a theme the necessity of specifying the class name. This does presuppose that theme authors have at least some PHP experience, but that is a reasonable expectation.\
\
	The proposed means to implement full flexibility in output is to provide three options to the system which combine to produce a single form of output:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls23\ilvl0\cf0 {\listtext	1.	}Output format - The format defines the target application for the system. Examples of formats are XHTML, HTML4, XML, WML, PDF, CHM, and plaintext.\
{\listtext	2.	}Output theme - The theme defines site-specific overrides to the output format. Examples of themes are php, pecl, pear, phpgtk, smarty, phpinternals, and pdp-e. Themes provide header, footer, and style information based on the output format.\
{\listtext	3.	}Output encoding - The encoding is used by the format and theme to handle special characters.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	The existing phpweb would use the "XHTML" format, the "php" theme, and an output encoding of either "ISO-8859-1" or "UTF-8".\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 VIII. Basic implementation\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs26 \cf0 \
	
\fs28 This section describes some basic ideas of how the build system will be implemented. The live version of the tree can currently be found at <{\field{\*\fldinst{HYPERLINK "http://phpdoc.gwynne.dyndns.org/phd/"}}{\fldrslt http://phpdoc.gwynne.dyndns.org/phd/}}>.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 1. Files\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 	\
	The current build systems are a complex mass of files and directories. A new system should simplify this to a reasonable extent. The following structure is proposed:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f4\fs24 \cf0 docbuild/				# base directory\
 setup.php				# Script to setup options for the system.\
					#  Provides both CLI and HTML interfaces\
					#  to the config.php file which contains\
					#  configuration information for the\
					#  system.\
 config.php			# Created by setup.php, NOT present in a\
					#  clean distribution.\
 index.php				# Main display gateway. Receives\
					#  potential IDs for display and calls\
					#  into them.\
 convert.php			# Converter to translate current entity\
					#  references into custom namespace\
					#  elements.\
 build.php				# Cronjob to run to rebuild any index\
					#  data and required pregenerated files.\
 makestatic.php			# Cronjob to run to build a set of\
					#  pregenerated files for rsync.\
 include/				# Include directory\
  transform.inc.php		#  Include file containing the\
					#   implementation of transformations as\
					#   described in Section 6.3.2.\
					#   Preferably implemented as a class.\
  database.inc.php		#  Include file containing the\
					#   implementation of a class for\
					#   accessing the index database and\
					#   managing the index (low level).\
  output.inc.php		#  Include file containing a class to\
					#   manage any output transformations for\
					#   format and/or encoding. This is where\
					#   transform.inc.php should be used. All\
					#   attempts should be made at\
					#   optimization, while keeping in mind\
					#   the needs of makestatic.php.\
  config.in.php			# The template for config.php\
 themes/				# Themes directory. Remember that themes\
					#  MUST be the ONLY content which defines\
					#  site-specific text and options.\
  default/				#  Fallback theme. This should display\
					#   error messages for all cases!\
  *\
 formats/				# Formats directory.\
  xhtml.php\
  xml.php\
  html4.php\
  chm.php\
  wml.php\
  plaintext.php\
  *\
 i18n/				# Contains localized content for common\
					#  scripts which must interact with the\
					#  user.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs28 \cf0 2. ???\
\
	
\f1\b0 More to come?\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 \page IX. Checklist of functionality\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 	\
	For now, the commentary on various requirements of the system in all previous sections will suffice as a checklist. A complete one should be drawn up as the system enters the beginnings of testing. Testing is CRITICAL to the system and MUST be provided for.\
\page \pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 X. System naming proposals\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs30 \cf0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\fs28 \cf0 	Several names have been proposed for the new buildsystem. They are:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls24\ilvl0\cf0 {\listtext	\'a5	}PDP-E. Short for PHP DocBook Publishing Engine. It is intended as a pun upon the venerable PDP-11 minicomputer, and is pronounced "Pee Dee Pee Eee".\
{\listtext	\'a5	}docbuild. A simple name used throughout this proposal for example purposes.\
{\listtext	\'a5	}DocDoc or DrDoc. Short for "Doctor Documentation", a name suggested by Philip Olson.\
{\listtext	\'a5	}livedocs. It is possible to replace the existing "livedocs" system with the new one without changing the name. This suggestion has little support.\
{\listtext	\'a5	}PhD. Standing for "Php Docbook" or something similar, suggested by Hannes Magnusson. This name has the most widespread support so far.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	At the time of this writing, the most popular option for the system name is "PhD". It is considered likely that this will be the final name of the project.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 \page XI. System licensing proposals\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs28 \cf0 \
	There is always the question of how to license a given set of source code, even for opensource applications. At this time, the source code contains the MIT license, a permissive license. This is subject to change before distribution. Some of the suggestions so far have been:\
\
\pard\tx220\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li720\fi-720\ql\qnatural\pardirnatural
\ls25\ilvl0\cf0 {\listtext	\'a5	}The MIT license.\
{\listtext	\'a5	}The GPL license.\
{\listtext	\'a5	}The LGPL license.\
{\listtext	\'a5	}The PHP license.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
	The author(s) are not experienced in licensing issues and can not go into detail upon the pros and cons of the various proposals. Discussion is invited.\
\
	After discussion, it is suggested that the PHP license, suitably modified, suffices for the purposes of this project. A possible implementation is given here:\
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural

\f5\fs24 \cf0 \

\f4\fs20 -------------------------------------------------------------------- \
                  The PhD License, version 1.0\
             Based on the PHP license, version 3.01\
Copyright (c) 2007 The PHP Documentation Group. All Rights Reserved.\
-------------------------------------------------------------------- \
\
Redistribution and use in source and binary forms, with or without\
modification, is permitted provided that the following conditions\
are met:\
\
  1. Redistributions of source code must retain the above copyright\
     notice, this list of conditions and the following disclaimer.\
 \
  2. Redistributions in binary form must reproduce the above copyright\
     notice, this list of conditions and the following disclaimer in\
     the documentation and/or other materials provided with the\
     distribution.\
 \
  3. The name "PhD" must not be used to endorse or promote products\
     derived from this software without prior written permission. For\
     written permission, please contact docgroup@php.net.\
  \
  4. Products derived from this software may not be called "PhD", nor\
     may "PhD" appear in their name, without prior written permission\
     from group@php.net.  You may indicate that your software works in\
     conjunction with PhD by saying "Foo for PhD" instead of calling\
     it "PhD Foo" or "phdfoo"\
 \
  5. The PHP Documentation Group may publish revised and/or new\
     versions of the license from time to time. Each version will be\
     given a distinguishing version number.\
     Once covered code has been published under a particular version\
     of the license, you may always continue to use it under the terms\
     of that version. You may also choose to use such covered code\
     under the terms of any subsequent version of the license\
     published by the PHP Documentation Group. No one other than the\
     PHP Documentation Group has the right to modify the terms\
     applicable to covered code created under this License.\
\
  6. Redistributions of any form whatsoever must retain the following\
     acknowledgment:\
     "This product includes PhD software, freely available from\
     <http://phd.php.net/download/>".\
\
THIS SOFTWARE IS PROVIDED BY THE PHP DOCUMENTATION TEAM ``AS IS''\
AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED\
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A \
PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PHP\
DEVELOPMENT TEAM OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, \
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES \
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR \
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED\
OF THE POSSIBILITY OF SUCH DAMAGE.\
\
-------------------------------------------------------------------- \
\
This software consists of voluntary contributions made by many\
individuals on behalf of the PHP Documentation Group.\
\
The PHP Documentation Group can be contacted via Email at\
docgroup@php.net.\
\
For more information on the PHP Documentation Group and the PhD\
project, please see <http://phd.php.net>.\

\f5\fs24 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs28 \cf0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs32 \cf0 \page XII. Revision history
\f1\b0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\fs28 \cf0 7/15/2007 -\
 - Removed concern for XML validation (not a real issue)\
 - Fixed typo.\
\
7/13/2007 - Added another name proposal\
\
7/6/2007 - Updated for:\
 - <revision/> element information\
 - Project name proposals\
 - Information on output methods vs. themes\
 - Updated project file layout\
 - Internationalization support\
 - Link to current development tree\
 - Licensing proposals\
 - Remove proposed DTD/XSD schemas, ref. to dev tree\
 - Remove namespace from element descriptions\
\
6/30/2007 - First revision}