|
From: Brian W. <bw...@st...> - 2002-10-22 07:38:54
|
Ok. I have the first cut of the defaults.xml patch.
It is all in the attached file - it is patched against
htdig-3.2.0b4-20021013.
The remainder of this email is the README file from the
tar file.
Regs
Brian White
===============================================================
Documentation attached to initial version of defaults.xml patch
===============================================================
1. Overview of what it does
====================================
* Adds defaults.xml and defaults.dtd
plus manage_attributes.pl for managing access
to them
* Addition of make_defaults_cc.pl for creating
defaults.cc
* Complete rewrite of the cf_generate.pl that
creates attrs.html, cf_byprog.html and
cf_byname.html
* Reducing the size of the ConfigDefaults
structure to just have "name" and "value"
The version of defaults.xml as it exists in
this patch is valid against defaults.dtd.
The patch is done against htdig-3.2.0b4-20021013
2. Affected Files
====================================
New Files:
* htcommon/defaults.dtd
* htcommon/manage_attributes.pl
* htcommon/make_defaults_cc.pl
Replaced Files:
* htcommon/defaults.xml
* htdoc/cf_generate.pl
(Note that most of the patches are only 1 or 2 lines
- the biggest is probably about 10 )
Patched Files:
* htcommon/Makefile.am.patch
* htdoc/Makefile.am.patch
* htdoc/attrs_head.html.patch
* htdoc/attrs_tail.html.patch
* htdoc/cf_byname_head.html.patch
* htdoc/cf_byprog_head.html.patch
* htlib/Configuration.h.patch
* htdb/htdb_dump.cc.patch
* htdb/htdb_load.cc.patch
* htdb/htdb_stat.cc.patch
Files to removed from CVS
* defaults.cc
3. Creating Descriptions
====================================
The description is essentially a html
snippet, with the following differences
* It is limited to p,br,ol,ul,table,em,
strong,code and a elements, with
two additions:
1) <!ELEMENT codeblock (%paratext;)* >
This is used to provide block code or html
snippets. An example of this would be
<codeblock>
<SELECT NAME="search_algorithm">
<OPTION VALUE="exact:1 prefix:0.6 synonyms:0.5 endings:0.1"
SELECTED>fuzzy
<OPTION VALUE="exact:1">exact
</SELECT>
</codeblock>
2) <!ELEMENT ref (#PCDATA) >
<!ATTLIST ref type (program|attr|faq) #REQUIRED >
This is used to link to programs, faqs and other attributes.
Some examples are:
<ref type="attr">build_select_lists</ref>
<ref type="program">htdig</ref>
<ref type="faq">4.1</ref>
The purpose of doing this is to allow the info
to be reused, and remove the dependency
on html files in a particular place.
* The only allowed attributes in the description
are:
table : border, width
td,th : align, valign, rowspan, colspan
dl : compact="true"
4. A Discussion of XML Validation
====================================
Ideally the code should validate the XML
against the DTD, and should check for
well formedness. Unfortunately that requires
an XML parser, and I did not want to add
an extra dependency at this stage!
What I did as a compromise was to create
an API that is used to load and then
query the XML data - this API is
documented and implemented in
htcommon/manage_attributes.pl.
At the moment the internal data structures
are populated using standard perl pattern
matching - it *assumes* that defaults.xml
is valid against defaults.dtd, but is does
not test it.
The aim is that when an XML parser is
readily available, that can be used
to populate the internal data structures -
and everything else should just work!
5. The Current state of defaults.xml
====================================
The version of defaults.xml that is
presented in this patch is valid
against defaults.dtd, but is
desperately in need of a cleanup.
However:
a) I don't have time to clean it up at the moment
b) It is currently completely generated from the old
defaults.cc, which makes it easier to adjust
until it's form becomes stable
What I would like to do is get the patch
in place and once it has stablized
embark on a bit of a cleanup
6. Possible Issues
====================================
* Examples are just entered as values
- the "name : " before are now
automatically generated. This may seem
limiting, but it is exactly what is in
the docs at the moment.
* There are a few remaining links to
other parts of the documentation that
I have left a <a> elements, simply
because I couldn't see an obvious way
to include them
|