Hi,
I am tackling the task of converting the current documentation of the
Spirit parser framework to an XML document, which can be used to
generate various representations such as HTML, PDF, etc. Obviously,
I'd like to make something that's based on your efforts, to further
the vision of one true boost documentation format. :-)
In order to get started, I'd like to contribute a DTD for the
to-be-defined format and started by commiting the
libs/documentation/dtd directory to the boost-sandbox, which as of now
contains a file boostbook.dtd.
For the moment, the DTD does nothing but include the original DocBook
4.2 DTD. My plan is to add the necessary element definitions to that,
effectively extending DocBook by the tags that we need. There are at
least two ways to achieve this, but before I can decide, which way to
go, I need some input from you guys.
For starters, it would be good if the current documentation would be
declared as a BoostBook document. The identifiers are:
PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
SYSTEM "http://cryp.to/boost-sandbox/libs/documentation/dtd/boostbook.dtd";
Thus, you can declare the documents like this:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC
"-//Boost//DTD BoostBook XML V1.0//EN"
"http://cryp.to/boost-sandbox/libs/documentation/dtd/boostbook.dtd";>
After adding the identifier to your system's catalog file, you can
then validate the XML documents using, for example, xmllint(1) (part
of libxml2). What will report quite a few errors at the moment, but
this is what this posting is all about, right? :-)
So, let me describe the two approaches I can think of to get the DTD
done:
(1) DocBook provides "hooks", which you can use to extend the DTD.
There are _numerous_ parameter entities that you can override.
For example, the element <section> is defined in DocBook like
this:
<!ENTITY % section.content.module "INCLUDE">
<![ %section.content.module; [
<!ENTITY % section.module "INCLUDE">
<![ %section.module; [
<!ENTITY % local.section.attrib "">
<!ENTITY % section.role.attrib "%role.attrib;">
<!ENTITY % section.element "INCLUDE">
<![ %section.element; [
<!ELEMENT section %ho; (sectioninfo?,
(%sect.title.content;),
(%nav.class;)*,
(((%divcomponent.mix;)+,
((%refentry.class;)*|(%section.class;)*|simplesect*))
| (%refentry.class;)+|(%section.class;)+|simplesect+),
(%nav.class;)*)
%ubiq.inclusion;>
The interesting part is the parameter entity
%local.section.attrib;, which is empty by default. One could
re-define this in the BoostBook DTD, thereby adding any attribute
we'd need to the DocBook DTD. Similar hooks for extensions are
spread throughout the DocBook DTD.
(2) In the BoostBook DTD, we're free to define _any_ elements we want.
Since the DTD includes the DocBook DTD, those elements can in turn
contain or refer to any of the DocBook elements.
The first approach is IMHO very aesthetic, because we do use the
machanisms for extensions that were added for exactly this purpose.
It also makes it very easy for the DocBook guys to eventually import
our additions to the original DTD -- to the benefit of all users.
The second approach gives us much more power to extend the DTD,
though. It also means, though, that the resulting documents have to
use _our_ tags in most places. So you wouldn't write
<book><sect1>...
anymore, but
<boostbook><boostsect1>...
because otherwise the extensions are not available.
Of course, both approaches can be combined.
There is a third option, which I do not really like, though: We could
use the DocBook DTD as basis for our own stuff and modify it to
contain what we want. This would mean that we'd have to manually
import changes to the DocBook DTD into ours, while the other two
options do not require us to touch the DocBook DTD at all.
So what do you think? What's the way to go?
-peter
P. S.: I see that "boost.xml" uses the XInclude module to refer to
sub-parts of the document via <xi:include .../>. Can I convince you to
use the "XML way" instead? This would be that you define a parameter
entity refering to the document:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC
"-//Boost//DTD BoostBook XML V1.0//EN"
"http://cryp.to/boost-sandbox/libs/documentation/dtd/boostbook.dtd"; [
<!ENTITY % functiondoc SYSTEM "function/function.xml">
]>
...
%functiondoc;
The advantage of this approach is that it is true SGML, while XInclude
is an XML extension most SGML parsers cannot handle. Thus, the
referred documents would not be validated by the parser.
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
