OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] Docbook Structure and DTD questions


Hi,
Regarding question #1 about updating fields in a document, there
are a couple of approaches. 
 
In one approach, you write a program using an XML library that can
load your XML document and access the various fields using the
DOM (document object model).  Such a program could replace
fields with current values and write out a new copy of the file.
 
Another approach is to write all variable data as entities such as
&DATE; and such.  Then you create a current entities file at runtime that
is loaded by the DOCTYPE declaration in the file.  That way you don't
have to touch the XML file itself.  You just have to update the entities file.
It is also obvious that entities are not to be edited by the authors.
 
Regarding the DTD customization, you seem to have some rules
based on the titles, and a DTD cannot enforce such rules.
You may need to write an external program to check for
such rules.
 
Regarding the numbering, you should be able to customize the
stylesheets to automatically generate sequential numbers.
If you have numbers that are fixed to paragraphs, regardless
of the sequence, then of course you would need to include such
numbers with the element.  But it sounds like you just need
enhanced automatic numbering, which XSLT can do nicely.
 
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
 
 
----- Original Message -----
From: Ray Cauchi
Sent: Wednesday, November 26, 2003 6:22 PM
Subject: [docbook-apps] Docbook Structure and DTD questions

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>
                <invpartnumber>000144</invpartnumber>
                <affiliation>
                        <orgname>Organisation Name</orgname>
                        <orgdiv>Division Name</orgdiv>
                </affiliation>
                <copyright>
                        <year>2003</year>
                        <holder>Organisation Name</holder>
                </copyright>
                <authorgroup>
                        <author>
                                <honorific>Mrs</honorific>
                                <firstname>Blah</firstname>
                                <surname>Blah</surname>
                                <affiliation>
                                        <jobtitle>CEO</jobtitle>
                                        <orgdiv>Management</orgdiv>
                                        <address><email>email@address.com</email></address>
                                </affiliation>
                        </author>
                        <editor>
                                <honorific>Professor</honorific>
                                <firstname>Blah</firstname>
                                <surname>Blah</surname>
                                <affiliation>
                                        <jobtitle>Director of Blah</jobtitle>
                                        <orgdiv>Blah</orgdiv>
                                        <address><email>email@address.com</email></address>
                                </affiliation>
                        </editor>
                        <editor>
                                <honorific>Dr.</honorific>
                                <firstname>Blah</firstname>
                                <surname>Blah</surname>
                                <affiliation>
                                        <jobtitle>Director of Blah</jobtitle>
                                        <orgdiv>Blah</orgdiv>
                                        <address><email>email@address.com</email></address>
                                </affiliation>
                        </editor>
                </authorgroup>
                <publisher>
                        <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>
                <revhistory>
                        <revision>
                                <revnumber>1.1b</revnumber>
                                <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>
                        <revision>
                                <revnumber>1.1a</revnumber>
                                <date>28 June 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>
                </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>
                                        <
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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]