Okay folks, I've got a VERY rough draft thrown together, with comments
interspersed to roughly describe what I'm thinking with this DTD. I'll
rough out a sample file also, but I've tried to give examples of possible
uses. I can go into a LOT more detail, but I figure this is at least a
start and I'm very interested in any comments anyone may have.
Is there anyone else I ought to be sending this to, btw?
I got a nice piece of mail back from Gregor Purdy, about some of the stuff
he's done moving towards stuff like this. He said he was thinking less
lately of writing a DTD and more of developing some tools to help
correlate with the DocBook DTD, so this probably isn't a duplication of
effort and it's really not a significant effort in any case.
Anyway, I'm itchin' for comments, so hit me with 'em if you've got 'em,
bearing in mind, I'm still not subbed to pod-people at the moment.
If we like this basic DTD I'll work on fleshing it out fully and making
the necessary package to support it, and then I'll beat on it with some
sample SGML, and then what I'd love to do is write a quick SGMLS-based
perl tool which would convert from this DTD to POD (that being something I
know I could do real quick).
This draft DTD doesn't include =pod or =cut. It als doesn't include =for,
=begin, or =end at the moment, as I'm still pondering ideal treatments
there.
Anyway, DTD follows.... and please bear in mind it's VERY rough, not even
fully proofed, and I'm sure there's stuff I've forgotten.
[begin POD DTD v0.1]
<!-- POD.DTD version 0.1
By Abby Franquemont <[EMAIL PROTECTED]>
DTD to represent POD in SGML
29 February 2000: started DTD, roughed in core elements
Typical invocation:
<!DOCTYPE doc PUBLIC "-//ES/DTD Plain Old Documentation DTD v0.1//EN" []>
-->
<!-- data entities -->
<!-- Data entities can contain all the ISO-standard character sets
along with specific things which can be reusable as if they
were "macros" almost
-->
<!-- content model entities -->
<!ENTITY % text "( p|section|head|i|b|s|c|l|f|x|z|e )+" >
<!-- attribute type entities -->
<!-- document elements -->
<!ELEMENT doc - - ( front?, body, back? )>
<!ATTLIST doc
version NMTOKEN #FIXED "0.1"
name CDATA #REQUIRED
author CDATA #IMPLIED
date CDATA #IMPLIED>
<!--
Examples:
<doc version="0.1" name="Example">
<doc version="0.1" name="Example" author="Abby Franquemont">
<doc version="0.1" name="Example" date="29 Feb 2000">
<doc version="0.1" name="Example" author="AMF" date="29 Feb 2000">
and, this element must be closed at the end, so the last thing in a
document in this DTD is </doc>.
-->
<!ELEMENT body - - ( head?, p?, %text; )>
<!--
<body> is the main core of where everything will go. I'm including
<front> and <back> in case anyone wants to use them for slightly greater
structure; <front> and <back> are identical to <body>. <body> at the least
is required, while <front> and <back> are optional.
-->
<!ELEMENT head - o ( %data; )>
<!ATTLIST head
type CDATA #REQUIRED
name CDATA #IMPLIED
id CDATA #IMPLIED>
<!--
Your basic =headn. Can take several forms:
<head type="head1">NAME</head>
<head type="head1" name="NAME">
<head type="head1" name="NAME" id="1A">
<head type="head1" id="1A">NAME</head>
Only the type attribute is required, and it shoudl be used to specify
head1, head2, head3, or, well, headn. The name, which is to say the text
to be used for the heading, can either be placed in the name attribute, or
in between the tags like would be the norm in HTML. The name attribute is
optional. Also optional, the ID attribute can be used to give your heading
an ID which can be used for the creation of indices or potential navigation
between headings.
-->
<!ELEMENT p - - ( %data; )>
<!ATTLIST p
headtype CDATA #IMPLIED
headname CDATA #IMPLIED>
<!--
The paragraph element, <p>, contains the %data entity as defined above,
which includes everything that should be in a paragraph, which is just
about everything that could be in a POD document.
Examples:
<p>One paragraph</p>
<p>Two paragraph</p>
Additionally, a paragraph can be given a heading of its own for the
specific paragraph. Examples:
<p headtype="head2" headname="Paragraph Heading">
Text of the paragraph.</p>
-->
<!ELEMENT i - - ( %text; )>
<!--
This should just look like <i>Text to be formatted</i>. A close tag
is required for this.
-->
<!ELEMENT b - - ( %text; )>
<!--
As with <i>, this must be closed, and should contain the text to be
formatted.
-->
<!ELEMENT s - - ( %text; )>
<!ELEMENT c - - ( %text; )>
<!ELEMENT l - o ( %text; )>
<!ATTLIST l
text CDATA #IMPLIED
name CDATA #IMPLIED
ident CDATA #IMPLIED>
<!--
For <l>, or link, the attributes are all optional from a structural
standpoint but you'd have to use at least one. The attribute names
were drawn from perldoc perlpod, and the examples therein. ;-) You'd
use it as follows:
<l text="text" name="name" ident="ident"> (L<text|name/ident>)
<l name="name"> (L<name>)
<l>name</l> (L<name>)
<l ident="ident">name</l> (L<name/ident>)
<l name="name" ident="ident"> (L<name/ident>)
<l name="name" ident="ident">Text</l> (L<text|name/ident>)
There are a variety more, if this isn't sufficient for starter examples
I'll do up a few more of 'em.
<l> can either be a standalone tag with all the data in its attributes,
or a tag requiring a close tag with the text to be displayed
within <l></l>, as <l>text</l>.
-->
<!ELEMENT f - o ( %text; )>
<!ATTLIST f
file CDATA #IMPLIED>
<!--
Again, this can either be a standalone element with no close tag and
all the data in the attribute, or an <f></f> construct. Examples:
<f file="/path/to/file">
<f>/path/to/file</f>
-->
<!ELEMENT x - - ( %text; )>
<!--
<x>index term</x> (X<index term>)
If desired, though not supported by this version of the DTD, I can make
this <x term="index term">
-->
<!ELEMENT z - o ( %text; )>
<!--
<z> for a simple zero-width character can be inserted. This could also
be a data entity we define early in the DTD and simply call as &z; if
we desire, but that may be less desirable as it could cause confusion
with other defined entities. Just stick <z> in and you get a zero-width
char, no need to close it.
-->
<!ELEMENT e - - ( %text; )>
<!--
This may prove superflous since we can just use — or é
or whichever ISO-standard entity we require. Of course, not having to
muck with externally-defined ISO-standard character sets makes a
smaller package to install, though likely most folks would have them
anyway.
-->
<!ELEMENT over - - ( item|%text; )>
<!ELEMENT item - - ( %text; )>
<!--
<over><item></item></over>; there's no <back> since </over> would do
what <back> does.
-->
