| Re: [AD] Re: [AL] allegro DTD |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On Thu, 2 Dec 2004, Matthew Leverton wrote:
Anyway, what I wanted to propose is this... Remove all the dashes from
the tag names. I've never seen an XML document make such liberal use
of dashes. (In fact, this is the only XML doc I've seen with any
dashes in tag names.) They are generally a nuisance for parsing.
Elements with dashes are more human-readable.
For example, in PHP, one can do this to loop through the XML file:
foreach ($doc->chapter as $chapter)
{
print '<h2>'.$chapter->title.'</h2>';
foreach ($chapter->section as $section)
{
print '<h3>'.$section->title.'</h3>';
// process api-section
}
}
Now, when one tries to do something like $section->api-section, the -
obviously gets parsed as a minus sign, and bad things happen. Yes, PHP
has work-arounds (ie, using the more unfriendly DOM objects or xPath),
but other languages may not.
You can't do $section->"api-section" or $section->{api-section} or
something like that? That's bad. It's valid XML (what if there is
namespace like in 'xml:lang'?). But I have nothing against dropping
dashes.
I propose to use more conventional names, as opposed to trying to make
the file look pretty.
examples:
api-section => api
Too ambiguous.
cross-ref => xref
Nice.
Patch attached.
Have a nice day.
Stepan Roh
? patch
Index: allegdoc.dtd
===================================================================
RCS file: /cvsroot/alleg/makedoc/src/allegdoc.dtd,v
retrieving revision 1.4
diff -u -r1.4 allegdoc.dtd
--- allegdoc.dtd 29 Nov 2004 20:53:22 -0000 1.4
+++ allegdoc.dtd 3 Dec 2004 17:27:53 -0000
@@ -81,7 +81,7 @@
Block-level content.
-->
<!ENTITY % block.content
- "para | text-block | code-block | list | definition-list | block-quote | image">
+ "para | textblock | codeblock | list | definitionlist | blockquote | image">
@@ -90,7 +90,7 @@
-->
<!ENTITY % document.nested "chapter">
<!ELEMENT document
- (title, front-page?, (%document.nested;)*)>
+ (title, frontpage?, (%document.nested;)*)>
<!ENTITY % document.attrib "">
<!ATTLIST document
%common.attrib;
@@ -100,12 +100,12 @@
<!--
- Chapter. Front-page override that specified in parent document.
+ Chapter. Frontpage overrides that specified in parent document.
-->
<!ENTITY % chapter.nested
- "text-section | api-section | changes | people-list | faq-list">
+ "textsection | apisection | changes | peoplelist | faqlist">
<!ELEMENT chapter
- (title, front-page?, (%chapter.nested;)*)>
+ (title, frontpage?, (%chapter.nested;)*)>
<!ENTITY % chapter.attrib "">
<!ATTLIST chapter
%common.attrib;
@@ -130,12 +130,12 @@
<!--
Special first page (or bigger page header).
-->
-<!ENTITY % front-page.nested "%block.content;">
-<!ELEMENT front-page (%front-page.nested;)*>
-<!ENTITY % front-page.attrib "">
-<!ATTLIST front-page
+<!ENTITY % frontpage.nested "%block.content;">
+<!ELEMENT frontpage (%frontpage.nested;)*>
+<!ENTITY % frontpage.attrib "">
+<!ATTLIST frontpage
%common.attrib;
- %front-page.attrib;
+ %frontpage.attrib;
>
@@ -156,12 +156,12 @@
<!--
Text section. Section-like element.
-->
-<!ENTITY % text-section.nested "%block.content;">
-<!ELEMENT text-section (title?, (%text-section.nested;)*)>
-<!ENTITY % text-section.attrib "">
-<!ATTLIST text-section
+<!ENTITY % textsection.nested "%block.content;">
+<!ELEMENT textsection (title?, (%textsection.nested;)*)>
+<!ENTITY % textsection.attrib "">
+<!ATTLIST textsection
%common.attrib;
- %text-section.attrib;
+ %textsection.attrib;
>
@@ -195,12 +195,12 @@
<!--
Text block which preserves text layout.
-->
-<!ENTITY % text-block.nested "%linked.content;">
-<!ELEMENT text-block (%text-block.nested;)*>
-<!ENTITY % text-block.attrib "">
-<!ATTLIST text-block
+<!ENTITY % textblock.nested "%linked.content;">
+<!ELEMENT textblock (%textblock.nested;)*>
+<!ENTITY % textblock.attrib "">
+<!ATTLIST textblock
%common.attrib;
- %text-block.attrib;
+ %textblock.attrib;
>
@@ -208,12 +208,12 @@
<!--
Code block which preserves text layout.
-->
-<!ENTITY % code-block.nested "%linked.content;">
-<!ELEMENT code-block (%code-block.nested;)*>
-<!ENTITY % code-block.attrib "">
-<!ATTLIST code-block
+<!ENTITY % codeblock.nested "%linked.content;">
+<!ELEMENT codeblock (%codeblock.nested;)*>
+<!ENTITY % codeblock.attrib "">
+<!ATTLIST codeblock
%common.attrib;
- %code-block.attrib;
+ %codeblock.attrib;
>
@@ -238,12 +238,12 @@
<!--
Frequently Asked Questions list. Section-like element.
-->
-<!ENTITY % faq-list.nested "faq-question, faq-answer">
-<!ELEMENT faq-list (title?, (%faq-list.nested;)*)>
-<!ENTITY % faq-list.attrib "">
-<!ATTLIST faq-list
+<!ENTITY % faqlist.nested "faqquestion, faqanswer">
+<!ELEMENT faqlist (title?, (%faqlist.nested;)*)>
+<!ENTITY % faqlist.attrib "">
+<!ATTLIST faqlist
%common.attrib;
- %faq-list.attrib;
+ %faqlist.attrib;
>
@@ -251,12 +251,12 @@
<!--
FAQ question.
-->
-<!ENTITY % faq-question.nested "%block.content;">
-<!ELEMENT faq-question (%faq-question.nested;)*>
-<!ENTITY % faq-question.attrib "">
-<!ATTLIST faq-question
+<!ENTITY % faqquestion.nested "%block.content;">
+<!ELEMENT faqquestion (%faqquestion.nested;)*>
+<!ENTITY % faqquestion.attrib "">
+<!ATTLIST faqquestion
%common.attrib;
- %faq-question.attrib;
+ %faqquestion.attrib;
>
@@ -264,12 +264,12 @@
<!--
FAQ answer.
-->
-<!ENTITY % faq-answer.nested "%block.content;">
-<!ELEMENT faq-answer (%faq-answer.nested;)*>
-<!ENTITY % faq-answer.attrib "">
-<!ATTLIST faq-answer
+<!ENTITY % faqanswer.nested "%block.content;">
+<!ELEMENT faqanswer (%faqanswer.nested;)*>
+<!ENTITY % faqanswer.attrib "">
+<!ATTLIST faqanswer
%common.attrib;
- %faq-answer.attrib;
+ %faqanswer.attrib;
>
@@ -316,7 +316,7 @@
<!--
Ordered or unordered list.
-->
-<!ENTITY % list.nested "list-item">
+<!ENTITY % list.nested "listitem">
<!ELEMENT list (%list.nested;)*>
<!ENTITY % list.attrib "ordered (true | false) 'false'">
<!ATTLIST list
@@ -329,12 +329,12 @@
<!--
List item.
-->
-<!ENTITY % list-item.nested "%active.content;">
-<!ELEMENT list-item (%list-item.nested;)*>
-<!ENTITY % list-item.attrib "">
-<!ATTLIST list-item
+<!ENTITY % listitem.nested "%active.content;">
+<!ELEMENT listitem (%listitem.nested;)*>
+<!ENTITY % listitem.attrib "">
+<!ATTLIST listitem
%common.attrib;
- %list-item.attrib;
+ %listitem.attrib;
>
@@ -342,12 +342,12 @@
<!--
Definition list. Section-like element.
-->
-<!ENTITY % definition-list.nested "term, description">
-<!ELEMENT definition-list (%definition-list.nested;)*>
-<!ENTITY % definition-list.attrib "">
-<!ATTLIST definition-list
+<!ENTITY % definitionlist.nested "term, description">
+<!ELEMENT definitionlist (%definitionlist.nested;)*>
+<!ENTITY % definitionlist.attrib "">
+<!ATTLIST definitionlist
%common.attrib;
- %definition-list.attrib;
+ %definitionlist.attrib;
>
@@ -368,12 +368,12 @@
<!--
Block quote.
-->
-<!ENTITY % block-quote.nested "%active.content;">
-<!ELEMENT block-quote (%block-quote.nested;)*>
-<!ENTITY % block-quote.attrib "">
-<!ATTLIST block-quote
+<!ENTITY % blockquote.nested "%active.content;">
+<!ELEMENT blockquote (%blockquote.nested;)*>
+<!ENTITY % blockquote.attrib "">
+<!ATTLIST blockquote
%common.attrib;
- %block-quote.attrib;
+ %blockquote.attrib;
>
@@ -381,12 +381,12 @@
<!--
List of people. Section-like element.
-->
-<!ENTITY % people-list.nested "person, description">
-<!ELEMENT people-list (title?, (%people-list.nested;)*)>
-<!ENTITY % people-list.attrib "">
-<!ATTLIST people-list
+<!ENTITY % peoplelist.nested "person, description">
+<!ELEMENT peoplelist (title?, (%peoplelist.nested;)*)>
+<!ENTITY % peoplelist.attrib "">
+<!ATTLIST peoplelist
%common.attrib;
- %people-list.attrib;
+ %peoplelist.attrib;
>
@@ -420,7 +420,7 @@
<!--
Changes. Section-like element.
-->
-<!ENTITY % changes.nested "change-list">
+<!ENTITY % changes.nested "changelist">
<!ELEMENT changes (title?, (%changes.nested;)*)>
<!ENTITY % changes.attrib "">
<!ATTLIST changes
@@ -433,28 +433,28 @@
<!--
List of changes for one version.
-->
-<!ENTITY % change-list.nested "change-item">
-<!ELEMENT change-list (%change-list.nested;)*>
-<!ENTITY % change-list.attrib
- "original-version CDATA #REQUIRED
- final-version CDATA #REQUIRED">
-<!ATTLIST change-list
+<!ENTITY % changelist.nested "changeitem">
+<!ELEMENT changelist (%changelist.nested;)*>
+<!ENTITY % changelist.attrib
+ "originalversion CDATA #REQUIRED
+ finalversion CDATA #REQUIRED">
+<!ATTLIST changelist
%common.attrib;
- %change-list.attrib;
+ %changelist.attrib;
>
<!--
- One change in change-list.
+ One change in changelist.
-->
-<!ENTITY % change-item.nested "%block.content;">
-<!ELEMENT change-item (%change-item.nested;)*>
-<!ENTITY % change-item.attrib
+<!ENTITY % changeitem.nested "%block.content;">
+<!ELEMENT changeitem (%changeitem.nested;)*>
+<!ENTITY % changeitem.attrib
"author CDATA #REQUIRED">
-<!ATTLIST change-item
+<!ATTLIST changeitem
%common.attrib;
- %change-item.attrib;
+ %changeitem.attrib;
>
@@ -462,12 +462,12 @@
<!--
API section. Section-like element.
-->
-<!ENTITY % api-section.nested "function | variable | typedef">
-<!ELEMENT api-section (title?, (%api-section.nested;)*)>
-<!ENTITY % api-section.attrib "">
-<!ATTLIST api-section
+<!ENTITY % apisection.nested "function | variable | typedef">
+<!ELEMENT apisection (title?, (%apisection.nested;)*)>
+<!ENTITY % apisection.attrib "">
+<!ATTLIST apisection
%common.attrib;
- %api-section.attrib;
+ %apisection.attrib;
>
@@ -478,7 +478,7 @@
-->
<!ENTITY % function.nested "EMPTY">
<!ELEMENT function
- (name, return-value, argument-list, cross-refs?, description,
+ (name, returnvalue, argumentlist, xrefs?, description,
(%function.nested;)*)>
<!ENTITY % function.attrib
"macro (true | false) 'false'
@@ -493,12 +493,12 @@
<!--
Return value of function.
-->
-<!ENTITY % return-value.nested "EMPTY">
-<!ELEMENT return-value (type, (%return-value.nested;)*)>
-<!ENTITY % return-value.attrib "">
-<!ATTLIST return-value
+<!ENTITY % returnvalue.nested "EMPTY">
+<!ELEMENT returnvalue (type, (%returnvalue.nested;)*)>
+<!ENTITY % returnvalue.attrib "">
+<!ATTLIST returnvalue
%common.attrib;
- %return-value.attrib;
+ %returnvalue.attrib;
>
@@ -519,12 +519,12 @@
<!--
List of function arguments.
-->
-<!ENTITY % argument-list.nested "argument">
-<!ELEMENT argument-list (%argument-list.nested;)*>
-<!ENTITY % argument-list.attrib "">
-<!ATTLIST argument-list
+<!ENTITY % argumentlist.nested "argument">
+<!ELEMENT argumentlist (%argumentlist.nested;)*>
+<!ENTITY % argumentlist.attrib "">
+<!ATTLIST argumentlist
%common.attrib;
- %argument-list.attrib;
+ %argumentlist.attrib;
>
@@ -548,7 +548,7 @@
Constant or variable.
-->
<!ENTITY % variable.nested "EMPTY">
-<!ELEMENT variable (name, type, cross-refs?, description, (%variable.nested;)*)>
+<!ELEMENT variable (name, type, xrefs?, description, (%variable.nested;)*)>
<!ENTITY % variable.attrib
"const (true | false) 'false'">
<!ATTLIST variable
@@ -561,7 +561,7 @@
<!--
Return type of function or type of variable.
-->
-<!ELEMENT typedef (name, (struct | union)?, cross-refs?, description)>
+<!ELEMENT typedef (name, (struct | union)?, xrefs?, description)>
<!ENTITY % typedef.attrib "">
<!ATTLIST typedef
%common.attrib;
@@ -612,12 +612,12 @@
<!--
Cross-references.
-->
-<!ENTITY % cross-refs.nested "cross-ref">
-<!ELEMENT cross-refs (%cross-refs.nested;)*>
-<!ENTITY % cross-refs.attrib "">
-<!ATTLIST cross-refs
+<!ENTITY % xrefs.nested "xref">
+<!ELEMENT xrefs (%xrefs.nested;)*>
+<!ENTITY % xrefs.attrib "">
+<!ATTLIST xrefs
%common.attrib;
- %cross-refs.attrib;
+ %xrefs.attrib;
>
@@ -625,12 +625,12 @@
<!--
Cross-reference to function or description.
-->
-<!ENTITY % cross-ref.nested "#PCDATA">
-<!ELEMENT cross-ref (%cross-ref.nested;)*>
-<!ENTITY % cross-ref.attrib "ref IDREF #REQUIRED">
-<!ATTLIST cross-ref
+<!ENTITY % xref.nested "#PCDATA">
+<!ELEMENT xref (%xref.nested;)*>
+<!ENTITY % xref.attrib "ref IDREF #REQUIRED">
+<!ATTLIST xref
%common.attrib;
- %cross-ref.attrib;
+ %xref.attrib;
>
@@ -664,8 +664,8 @@
<!--
Local document reference.
-->
-<!ELEMENT document-ref EMPTY>
-<!ATTLIST document-ref
+<!ELEMENT documentref EMPTY>
+<!ATTLIST documentref
%common.attrib;
source CDATA #REQUIRED
>