ConTeXt FAQ format, XML with DTD

ConTeXt FAQ format, XML with DTD

[Henning Hraban Ramm]

Hello again!

JM's proposal of FAQ format is only for one FAQ entry.
The following one may contain the whole thing: several "recipes" (FAQ
entries),
each in more than one language.

I tried to convert it with ConTeXt, but it doesn't like attributes
(I will make a minimal failing example later).

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE context_cookbook SYSTEM "context_cookbook.dtd">
<cookbook date="2002-10-28" label="jum-000">
	<recipe id="test" section="first" subsection="subfirst">
		<version xml:lang="de" original="yes">
			<question>
				Wie kann ich dies und jenes erreichen?
			</question>
			<keyword sort-as="tech">&TeX;</keyword>
			<keyword>Test</keyword>
			<answer>
				<p>So vielleicht. <code
type="tex">blabla</code></p>
				<p>Oder so. <code type="shell">cat &gt;
test.txt</code></p>
				<p>Oder anders.</p>
			</answer>
			<author id="hraban" date="2002-10-20" />
			<editor id="nobody" date="2003-10-11" />
		</version>
		<version xml:lang="en" original="no">
			<question>
				How can I achieve that or this?
			</question>
			<keyword sort-as="tech">&TeX;</keyword>
			<keyword>test</keyword>
			<answer>
				<p>Perhaps this way.
				<code type="xml">
					<macro>clip</macro>

<sqbracket>nx=3,ny=2,x=2,y=1</sqbracket>
					<braces>

<macro>externalfigure</macro>

<sqbracket>yourfigure</sqbracket>
					</braces>
				</code></p>
				<p>Or maybe that way.</p>
				<p>Or somehow else.</p>
			</answer>
			<author id="john" date="2002-10-20" />
			<editor id="hraban" date="2002-10-21" />
		</version>
	</recipe>
</cookbook>

----------------------------------------------------------------------------
context_cookbook.dtd:

<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY % sortas	"sort-as CDATA #IMPLIED">
<!ENTITY % date		"date	CDATA #REQUIRED">
<!ENTITY % person	"id		IDREF #REQUIRED
					%date;">

<!ELEMENT cookbook	(recipe+)>
	<!ATTLIST cookbook	%date;>
	<!ATTLIST cookbook	label CDATA #IMPLIED>
<!ELEMENT recipe	(version+)>
	<!ATTLIST recipe	id	ID #REQUIRED>
	<!ATTLIST recipe	section	IDREF #REQUIRED>
	<!ATTLIST recipe	subsection	IDREF "none">
	<!ATTLIST recipe	subsubsection	IDREF "none">
<!ELEMENT version	(question, keyword*, answer, author, editor*)>
	<!ATTLIST version	xml:lang IDREF "en">
	<!ATTLIST version	original (yes|no) "yes">
<!ELEMENT question	ANY>
<!ELEMENT keyword	ANY>
	<!ATTLIST keyword	%sortas;>
<!ELEMENT answer	ANY>
<!ELEMENT author	EMPTY>
	<!ATTLIST author	%person;>
<!ELEMENT editor	EMPTY>
	<!ATTLIST editor	%person;>

<!ELEMENT code	(#PCDATA)>
	<!ATTLIST code	type (tex|shell|dos|xml) "tex">
<!ELEMENT index	(#PCDATA)>
	<!ATTLIST index		%sortas;>
<!ELEMENT emph	(#PCDATA)>
<!ELEMENT p		ANY>

<!ENTITY TeX "tech">

----------------------------------------------------------------------------

Grüßlis vom Hraban!
--
http://www.fiee.net
http://www.ramm.ch
---

Re: ConTeXt FAQ format, XML with DTD

[Taco Hoekwater]

Hi Hraban!

Two notes from me, on xml:lang usage.

1st). 
xml:lang is not the best solution to language independance. It doesnt
take transliteration into account, and it's specification does not cover
the full ISO language/country spec. Also, it can be quite hard to
intersept xml:lang in a processor.

That's why I always use this parameter entity:

<!ENTITY % lang  "language       CDATA      #IMPLIED
                  country        CDATA                #IMPLIED
                  translit       CDATA                #IMPLIED">

2nd)
Your DTD is not 100% ok. Most of it is just a matter of
merging ATTLIST specs, but this one:

  <!ATTLIST version	xml:lang IDREF "en">

is definitely wrong. The IDREF here (and in some other locations)
should be CDATA. Generally speaking, ID and IDREF do more harm
than good in XML files. It's better to express the Id<->Ref relation
in a schema and use CDATA in your Dtds always.

Sorry, no positive input from me today (no time) ;-)

-- 
groeten,

Taco

Re: ConTeXt FAQ format, XML with DTD

[Henning Hraban Ramm]

Am Mittwoch, 6. November 2002 10:31 schrieb Taco Hoekwater:

> 1st).
> That's why I always use this parameter entity:
> <!ENTITY % lang  "language       CDATA      #IMPLIED
>                   country        CDATA                #IMPLIED
>                   translit       CDATA                #IMPLIED">

That means, one may use language="de" or country="de" or translit="de" at the 
same time? Why? I'd think one attrib would be enough.

> Your DTD is not 100% ok. Most of it is just a matter of
> merging ATTLIST specs, but this one:
>   <!ATTLIST version	xml:lang IDREF "en">
> is definitely wrong. The IDREF here (and in some other locations)
> should be CDATA. Generally speaking, ID and IDREF do more harm
> than good in XML files. It's better to express the Id<->Ref relation
> in a schema and use CDATA in your Dtds always.

Ok. I got no documentation on schema yet (the new XML book by O'Reilly comes 
in a month).

I just found the ID(REF) thing in my XML docs and thought it would be the 
right thing.

> Sorry, no positive input from me today (no time) ;-)

Thank you nevertheless.
I'd be glad that my first try with XML doesn't have more errors! ;-)

Grüßlis vom Hraban!
-- 
http://www.fiee.net
http://www.ramm.ch
---