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


 

 

  
----- Original Message ----- 

  
From: 
  Ray Cauchi 

  
To:  
  

  
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>
                                </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>
                                </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>
                                </affiliation>
                        </editor>
                </authorgroup>
                <publisher>
                        <publishername>Publisher Name from CMS</publishername>
                        <address><email></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: 
  
w: www.tweek.com.au