Geoff,
I am still working on, but it has gone on the
backburner a bit recently.
I must confess, I ended up generating my own
initial version, which I did using some a C
for loop - I decided the C parser was the
best way to parse a C data structure!
I was thinking that
* defaults.xml and defaults.dtd
should go in htcommon
* the perl script for generating
defaults.cc should also go in
htcommon. This should be very
small and should assume that
defaults.xml is valid. This
then obviates the need for an
XML parser to be present when
rebuilding the code
* the code for generating the
HTML documentation pages should
include proper XML validation
The biggest issue I have at the moment is
- how to cope with the structure descriptions,
which are currently HTML snippets.
There are three options:
1) Store as HTML snippets, but translate <,> and &
to <,> and & - this will work, but I can
tell you it is horrible to maintain by hand!
2) Store as HTML snippets, but escaped by CDATA sections
3) Include some capacity for markup in the
XML.
What I would like to do is include some abstraction
for links to other htdig elements such as attributes,
eg:
<ref type="attr">valid_extensions</ref>
instead of
<a href="#valid_extensions">valid_extensions</a>
which makes the data much more useful, but if I do that
it prevents option (2). This would make the obvious choice
option (3) - but then what markup do you allow?
Anyway - here is my proposed DTD, which uses a very
cut down HTML for markup. Any thoughts would be
appreciated.
<!DOCTYPE HtdigAttributes [
<!ELEMENT HtdigAttributes ( attribute+ ) >
<!-- ConfigVar element is data set for each configuration variable.
Attributes:
name : Variable Name
type : Type of Variable
programs : Whitespace separated list of programs/modules
using this attribute
block : Configuration block this can be used in ( optional )
version : Version that introduced the attribute
category : Attribute category (to split documentation)
-->
<!ELEMENT attribute( default, ( nodocs | (example, description ) ) >
<!ATTLIST attribute name CDATA #REQUIRED
type string|integer|boolean) "string"
programs CDATA #REQUIRED
block CDATA #IMPLIED
version CDATA #REQUIRED
category CDATA #REQUIRED
>
<!ELEMENT default (#PCDATA) >
<!ATTLIST default configmacro (true|false) "false" >
<!-- Basically a flag that suppresses documentation -->
<!ELEMENT nodocs EMPTY>
<!ELEMENT example (#PCDATA) >
<!ENTITY % paratext "#PCDATA|em|strong|a|ref" >
<!ENTITY % text "%paratext;|table|p|br|ol|ul|dl|codeblock" >
<!ELEMENT description (%paratext;) >
<!ELEMENT p (%paratext;)* >
<!ELEMENT br EMPTY >
<!ELEMENT ol (li+) >
<!ELEMENT ul (li+) >
<!ELEMENT li (%text;)* >
<!ELEMENT table (tr+) >
<!ELEMENT tr (td|th)+ >
<!ELEMENT td (%text;)* >
<!ELEMENT th (%text;)* >
<!ATTLIST table border CDATA #IMPLIED
width CDATA #IMPLIED >
<!ATTLIST td align (
<!ELEMENT dl (dt|dd)+ >
<!ELEMENT dt (%paratext;)* >
<!ELEMENT dd (%text;)* >
<!ELEMENT strong (%text;)* >
<!ELEMENT em (%text;)* >
<!ELEMENT a (%text;)* >
<!ATTLIST a href CDATA #REQUIRED >
<!ELEMENT ref (#PCDATA)* >
]>
What I was going to suggest was that the
int main()
{
for (int i = 0; defaults[i].name; i++)
{
printf( "<ConfigVar name=\"%s\" type=\"%s\"
sinceversion=\"%s\" programs=\"%s\" \n"
" configblock=\"%s\" \n"
" category=\"%s\" >\n"
" <default>%s</default>\n"
" <example>%s</example>\n"
" <description>%s </description>\n"
"</ConfigVar>\n\n",
defaults[i].name,
defaults[i].type,
defaults[i].version,
defaults[i].programs,
defaults[i].block,
defaults[i].category,
defaults[i].value,
defaults[i].example,
defaults[i].description );
}
return 0;
}
It has gone a bit on the backburner recently, however
it is still in the pipeline. I would certainly not halt changes
to defaults.cc - we just come up with a final one at
some point.
There are several issues I have come across so far
1) Is there an XML parser available?
This is not something that should be assumed - what I
was going to suggest is a very basic script that generates
defaults.cc that assumes that defaults.xml is valid, with a
more full validating version that generates the
HTML pages.
2) Where do we put it in the hierachy - it is used in both
the
2) How do we include structured documnetation sninppets?
There are kind of three ways to do
a) HTML snippets escaped by entities - ie, have
the documentation as a snippet of HTML, but
with every "<", ">" and "&" translated to
"<" , ">" and "&".
This will work, but is as ugly as sin to
try and maintain.
b) HTML snippets escaped by CDATA marked sections
c)
One issue I realised is that attempting to use
At 08:06 5/10/2002, Geoff Hutchison wrote:
>A long time ago, in a thread far away...
>http://www.geocrawler.com/archives/3/8825/2002/9/0/9520602/
>
>Brian said:
> > I was looking at defaults.cc and I was wondering if
> > it might be better managing the info as an XML file
> > and then using that as a basis for generating
> > defaults.cc and the HTML docs.
>
>And I said:
> > Formatting defaults.cc into defaults.xml isn't hard and I'd be glad to
> > do that with some emacs macros.
>
>OK, I saw that on my TODO list today and added a defaults.xml to the
>mainline CVS. It's also gzip'ed and attached to this e-mail. It's a first
>draft, so to speak and I'm not entirely sure it's all well-formed XML or
>that the DTD is set. So please make suggestions.
>
>However, I thought I'd pass this back to Brian--are you still willing to
>write a script that'll generate a minimal defaults.cc? If so, I'll work on
>the XML file a bit more--I need to make sure nothing was deleted by my
>emacs slicing.
>-Geoff
-------------------------
Brian White
Step Two Designs Pty Ltd
Knowledge Management Consultancy, SGML & XML
Phone: +612-93197901
Web: http://www.steptwo.com.au/
Email: bwhite@...
Content Management Requirements Toolkit
112 CMS requirements, ready to cut-and-paste
|