X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org
Received: from localhost (unknown [200.46.204.2])
	by svr1.postgresql.org (Postfix) with ESMTP id B7D35D1B4E1
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Fri, 14 Nov 2003 19:17:01 +0000 (GMT)
Received: from svr1.postgresql.org ([200.46.204.71])
	by localhost (neptune.hub.org [200.46.204.2]) (amavisd-new, port 10024)
	with ESMTP id 51296-03
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Fri, 14 Nov 2003 15:16:31 -0400 (AST)
Received: from mail.gmx.net (pop.gmx.net [213.165.64.20])
	by svr1.postgresql.org (Postfix) with SMTP id C10F7D1B4ED
	for <pgsql-docs@postgresql.org>; Fri, 14 Nov 2003 15:16:28 -0400 (AST)
Received: (qmail 4260 invoked by uid 65534); 14 Nov 2003 19:16:29 -0000
Received: from dsl-082-082-166-031.arcor-ip.net (EHLO
	dsl-082-082-166-031.arcor-ip.net) (82.82.166.31)
	by mail.gmx.net (mp026) with SMTP; 14 Nov 2003 20:16:29 +0100
X-Authenticated: #495269
Date: Fri, 14 Nov 2003 20:16:30 +0100 (CET)
From: Peter Eisentraut <peter_e@gmx.net>
X-X-Sender: peter@peter.localdomain
To: Karel Zak <zakkr@zf.jcu.cz>
Cc: pgsql-docs@postgresql.org
Subject: Re: [HACKERS] XML Docbook
In-Reply-To: <20031114094548.GE25147@zf.jcu.cz>
Message-ID: <Pine.LNX.4.44.0311142008210.5327-100000@peter.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
X-Virus-Scanned: by amavisd-new at postgresql.org
X-Archive-Number: 200311/30
X-Sequence-Number: 2107

Karel Zak writes:

> On Fri, Nov 14, 2003 at 10:32:10AM +0100, Peter Eisentraut wrote:
> > XML disadvantage:
> >
> > - no arbitrary parameter entities
>
>  I unsure if I understand, can you show some example of this problem?

SGML and XML allow you to disable certain parts of your document, by
writing

<![IGNORE[
<stuff>...</stuff>
]]>

The opposite of IGNORE is INCLUDE.  Think of this as a preprocessing
stage.  You can also make the IGNORE/INCLUDE variable, by declaring a
"parameter entity", think of it as a variable.  This is declared like
this:

<!entity % myvar "IGNORE">

Then you can write

<![%myvar;[
<stuff>...</stuff>
]]>

and toggle the myvar somewhere.  For example, OpenJade allows you to do
this on the command line.

We use this feature to generate files like INSTALL and HISTORY from the
documentation sources.  The files are almost like the corresponding
chapters, but in some cases we use this as a kind of if/then/else to
adjust the content for the different contexts.  For example, you cannot
have links in INSTALL, because the rest of the documentation is not there
to link to.

Now, the problem in XML is that it no longer allows arbitary parameter
entities; that is, you can only hardcode IGNORE or INCLUDE, but not toggle
it anywhere.  So there is no straightforward conversion path for our
requirements.

If anyone can come up with a good solution for this problem, we can
convert to DocBook XML the next day.

-- 
Peter Eisentraut   peter_e@gmx.net