Re: Fwd: ConTeXt FAQ format, XML with DTD

Re: Fwd: ConTeXt FAQ format, XML with DTD

[Simon Pepping]

On Fri, Nov 08, 2002 at 10:22:56AM +0000, Henning Hraban Ramm wrote:
> 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.

Your DTD has a number of problems.  I have skipped most of this
discussion, so I do not know what you want. But the content models are
very vague: ANY for question and answer, and it seems you assume ANY
for code as well. If you do not specify this more precisely, too much
will be possible and nobody knows what to expect. A content model like
%text;, declared as (#PCDATA|p|code)+, would be better. Schemas have
some extra facilities here, but otherwise I am not sure why they would
be preferable.

The id in %person should be CDATA, as already remarked. Note that this
assumes a tightly organized set of documents. You say nothing about
the author or editor, so you assume that the id resolves into an entry
in another document, and that the renderer knows which document so
that it can generate a hyperlink. You might also use XLink language:
xlink:href="author#hraban", which already indicates that the author
can be found in the document author in the same directory, with the ID
hraban. OTOH, this is less flexible w.r.t. the organization of the
document set.

Note that Docbook has provisions for QandA: qandaset, question,
answer. I think docbook is a prime example of too wide a DTD. But it
is useful to try and devise a DTD that is a subset of Docbook. It
would make your documents processable with generic Docbook tools.

Regards, Simon

-- 
Simon Pepping
email: spepping@scaprea.hobby.nl

Re: Fwd: ConTeXt FAQ format, XML with DTD

[Henning Hraban Ramm]

Am Freitag, 8. November 2002 12:34 schrieb Simon Pepping:
> will be possible and nobody knows what to expect. A content model like
> %text;, declared as (#PCDATA|p|code)+, would be better. Schemas have

Thank you, I didn't know that was valid. Ok, it's only logically...
(I'm a XML beginner, you know...)

> that it can generate a hyperlink. You might also use XLink language:
> xlink:href="author#hraban", which already indicates that the author

Ahja, another specs to read...
Would 'xlink:href="authors.xml#hraban" be right?
Is it possible to define "authors.xml" (in DTD?) als target for all authors 
links?

> Note that Docbook has provisions for QandA: qandaset, question,
> answer. I think docbook is a prime example of too wide a DTD. But it
> is useful to try and devise a DTD that is a subset of Docbook. It
> would make your documents processable with generic Docbook tools.

My approach was to discuss first the needed structure and then
look how my needed structure can be "translated" to DocBook.
I didn't got time to read the DocBook docs yet.
And I don't know if I will understand them... ;-)

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

Re: Fwd: ConTeXt FAQ format, XML with DTD

[Simon Pepping]

On Sat, Nov 09, 2002 at 11:17:48AM +0100, Henning Hraban Ramm wrote:
> Am Freitag, 8. November 2002 12:34 schrieb Simon Pepping:
> > that it can generate a hyperlink. You might also use XLink language:
> > xlink:href="author#hraban", which already indicates that the author
> 
> Ahja, another specs to read...

Yeah, the XML world produces quite a few specs, and it takes a while
before you get a grip on the most important of them.

> Would 'xlink:href="authors.xml#hraban" be right?
> Is it possible to define "authors.xml" (in DTD?) als target for all authors 
> links?

Yes, that is possible. As I said, when you use 'id="hraban"', you
specify nothing. It is then possible to write a XSL or other
stylesheet that 'knows' that the authors are in authors.xml. OTOH,
when you use 'xlink:href="authors.xml#hraban"', then XLink aware
software knows it is in authors.xml. And it in XSL stylesheets there
are functions that also can find it easily.

Regards, Simon

-- 
Simon Pepping
email: spepping@scaprea.hobby.nl

Fwd: 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
---