docbook-apps message

Subject: Docbook Structure and DTD questions

From: Ray Cauchi <ray@tweek.com.au>
To: docbook-apps@lists.oasis-open.org
Date: Thu, 27 Nov 2003 13:22:15 +1100

Hi all

New to Docbook, and XML for that matter, though reasonably well versed in PHP/MySQL development....

What I am doing is building an XML based CMS designed to manage and version an Organisations Policies and Procedures (around 150 unique documents at this stage...)

Docbook appears to be the best option for me to do this with, and both Client and I have agreed this is the way we will head. The question I have is regarding customising Docbook.

I am using <article> as the root element, as it seems the most suitable for this purpose.

Each Document will have the following format:

----------------------------------------------------------------------------------------------------------------------------------------

1> Meta Data. I have devised the following model for meta data:

<articleinfo>

<title>Name of Policy</title>

<orgname>Organisation Name</orgname>

<orgdiv>Division Name</orgdiv>

</affiliation>

<holder>Organisation Name</holder>

</copyright>

<orgdiv>Management</orgdiv>

<address><email>email@address.com</email></address>

</affiliation>

</author>

<honorific>Professor</honorific>

<jobtitle>Director of Blah</jobtitle>

<address><email>email@address.com</email></address>

</affiliation>

</editor>

<jobtitle>Director of Blah</jobtitle>

<address><email>email@address.com</email></address>

</affiliation>

</editor>

</authorgroup>

<publishername>Publisher Name from CMS</publishername>

<address><email>email@address.com</email></address>

</publisher>

<pubdate>31 October 2003</pubdate>

<date id="approved">21 October 2003</date>

<date id="effective">31 October 2003</date>

<date id="review">1 October 2004</date>

<date>28 September 2003</date>

<revremark>Summary overview of changes to document followed by a
             list of the clauses that have been altered. Eg: The policy has
                been amended to reflect the changes to Divisional Structure and
                Divisional Head Position Titles. Clauses: 1, 10, 14, 22, 49, 61</revremark>

</revision>

<revremark>Summary overview of changes to document followed by a
                list of the clauses that have been altered.Eg: The policy has
                been amended to reflect the changes to Divisional Structure and
                Divisional Head Position Titles. Clauses: 1, 10, 14, 22, 49, 61</revremark>

</revision>

</revhistory>

</articleinfo>

2>      Document Sections. Each Document will be broken up into Sections (1,2,3 etc) that contain Parts (A,B,C etc). Each Section or Part will contain Clauses which will need to be    numbered consecutively throughout an entire document (ie: the first clause is (1). Each clause is then numbered consecutively, regardless of whether it is in the same Part/.Section or not - so the numbering never restarts, it continues throughout the entire document).

        Within this, there are some required and some optional Sections. For Example, Section 1 will ALWAYS be "Section 1: Purpose and Context" and will have at least one required     clause. Also, there can only ever be ONE section with the title "Purpose and Context". Section 2 will be optional, but will more often than not be "Section 2: Definitions" - again,    only one section with this title. The next section will always be "Policy Statement" - it is required and will contain at least one clause.

        The remainder of the document will be the core policy definition, composed of any number of sections/parts and clauses within each. Finally, there will be an optional "References" section for document references and extra information.

        The basic Structure I have been working with to manifest these sections :

<sect1>

<title>Section - Title</title>

<sect2>

<title>Part - Title</title>

<para>Clause</para>

</sect2>

</sect1>

I am assuming here that upon transformation, I can create the numbered clauses sequentially as part of the output. I am tossing up whether to give each <para> and id attribute to store the numbering in the document explicitly, or whether to just make the numbering a function of the XSL output .... any ideas?

----------------------------------------------------------------------------------------------------------------------------------------

Given this, I have a few questions/concerns:

1> Given the Meta data will need to be updated with each revision of the document, what is the most efficient way to perform such an action? Coming from an SQL background, I am used to updating just the fields in a table/record that I need to - but XML does not appear to have the same flexibility - or maybe I am missing something? I am thinking I will need to import all of the meta data into an array in PHP, then update the required array element, then write it back out to the file - is this correct, or is there a simpler method?

2> To enforce the required rules in the Document Sections, I am thinking I will need to create my own DTD based on the Docbook or Simplified Docbook DTD - again, am I on the right track here? I am also using Ektrons Ewebeditpro ( www.ektron.com ) in the CMS interface to allow Content Editors to modify their documents in a WYSIWYG interface - this will need an XML Schema to perform validation of content prior to writing the file - I imagine I can just convert my DTD into a Schema using a conversion tool no?

3> Is there anything above that appears wrong or at least maybe strange to anyone???

Thanks you in advance for your assistance, and I hope I can return the favour sometime...

Best Regards

Ray Cauchi
Manager/Lead Developer

( T W E E K ! )
PO Box 468 Katoomba NSW Australia 2780 p: +61 2 4757 1600 f: +61 2 4757 3808 m: 0414 270 400 e: ray@tweek.com.au w: www.tweek.com.au