You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Diana Shannon <te...@mac.com> on 2002/05/15 20:25:06 UTC
draft howto dtd
Attached is a howto dtd draft, along with a sample doc to validate. A
few notes.
1. I think the header element contains a lot of useful cms-related info.
Perhaps version can be used to imply status: draft/release/revision. I'm
not sure of its precise meaning with code, but perhaps "draft" document
versions could have a value less than 1, etc.
2. id attribute (via %common.att;) is defined for howto, so if CMS needs
to manage docs via that attribute, we're still ok.
3. I declared one additional child element of header:
last-modified-content-date. Its purpose is to provide meaning to the
reader based on content changes, not mere structural changes, etc. I'm
not sure if it duplicates revision history structure at the bottom.
4. I'm trying to take what is a liberal approach to what is allowed by
the dtd. For example, I didn't use %content.mix; anywhere. I wanted to
allow authors the chance to use lists for prerequesites, intended
audience, etc. Perhaps some of you will consider this too loose.
5. Steve, I wonder if you're going to dislike the way I'm treating
titles (as attributes) in each howto part. I just found it a little
simpler to implement this way. Feel free to revise, in anticipation of
your v11 work.
Anyway, please improve it. I'm certainly no expert. Snippets/tutorials
dtds will be similarly structured, so I'll wait for comments before
submitting those.
Many thanks.
Diana
Re: http://www.openebook.org/ compliance?
Posted by Ivelin Ivanov <iv...@apache.org>.
----- Original Message -----
From: "Steven Noels" <st...@outerthought.org>
To: <fo...@xml.apache.org>
Sent: Saturday, June 01, 2002 1:49 AM
Subject: RE: http://www.openebook.org/ compliance?
> > From: Ivelin Ivanov [mailto:ivelin@apache.org]
>
> > The xml markup appears to be a superset of document-v10.
> > Issues like resource referencing through a catalog of links have been
> > addressed.
> > (This is related to the issue Rob and I discussed recently.
> > The solution is
> > similar too, using ids for each link.)
>
> Seems like a mixture of XHTML and Dublin Core metadata to me. Ideally,
> we should have a pipeline that aggregates all documents and publishes
> them as one eBook 'pkg' document.
Correct. This is what I thought.
Another thing I like is that there are tons of publishing professionals
figuring out the presentation details, doing the usability research, etc. We
don't need to worry about it. Validating schemas, skins, etc. come for free
too.
At a first glance, it doesn't seem like an overbloated standard.
The major components of the OEBPS Package file look right:
Package Identity - A unique identifier for the OEBPS Publication as a whole.
Metadata - Publication metadata - (title, author, publisher, etc.).
Manifest - A list of files (documents, images, style sheets, etc.) that make
up the publication. The manifest also includes fallback declarations for
files of types not supported by this specification.
Spine - An arrangement of documents providing a linear reading order.
Tours - A set of alternate reading sequences through the publication, such
as selective views for various reading purposes, reader expertise levels,
etc.
Guide - A set of references to fundamental structural features of the
publication, such as table of contents, foreword, bibliography, etc.
>Interesting thought - does anyone has
> an eBook reading device on this list?
PalmOS and Windows CE devices can read eBooks with the right software.
eBook software:
http://publishing.about.com/cs/ebooksoftware/
You can download Acrobat eBook reader for free to read on your PC.
http://www.adobe.com/products/ebookreader/register.html
MS Word and Acrobat FrameMaker claim to be (soon) able to export/import Open
eBook docs.
eBook Software Capabilities: Pushing the Envelope
http://12.108.175.91/ebookweb/stories/storyReader$459
>
> </Steven>
>
RE: http://www.openebook.org/ compliance?
Posted by Steven Noels <st...@outerthought.org>.
> From: Ivelin Ivanov [mailto:ivelin@apache.org]
> The xml markup appears to be a superset of document-v10.
> Issues like resource referencing through a catalog of links have been
> addressed.
> (This is related to the issue Rob and I discussed recently.
> The solution is
> similar too, using ids for each link.)
Seems like a mixture of XHTML and Dublin Core metadata to me. Ideally,
we should have a pipeline that aggregates all documents and publishes
them as one eBook 'pkg' document. Interesting thought - does anyone has
an eBook reading device on this list?
</Steven>
http://www.openebook.org/ compliance?
Posted by Ivelin Ivanov <iv...@apache.org>.
I don't remember this being discussed here,
so I'll ask.
Have we considered compliance with the OpenBook initiative.
It appears to be a major undertaking in the publishing industry.
http://www.openebook.org/
The xml markup appears to be a superset of document-v10.
Issues like resource referencing through a catalog of links have been
addressed.
(This is related to the issue Rob and I discussed recently. The solution is
similar too, using ids for each link.)
Forrest can probably style just a subset of the markup for the web site.
However if the documents are stored as OpenBooks, then publishing in other
formats including printed media will be simpler. This is valuable especially
for documentation.
Thoughts?
Ivelin
book.xml [RE: document referencing through book.xml [was: draft howto dtd]]
Posted by Steven Noels <st...@outerthought.org>.
Ivelin,
yes it is, but I'll need some consecutive time to package and submit
what we already have as a book.xml replacer. I'm working on it!
Sorry for holding things up, I promise I'll post soon!
</Steven>
Re: document referencing through book.xml [was: draft howto dtd]
Posted by Ivelin Ivanov <iv...@apache.org>.
Steven,
Is our discussion with Rob relevant to your work?
Ivelin
----- Original Message -----
From: "David Crossley" <cr...@indexgeo.com.au>
To: <fo...@xml.apache.org>
Sent: Monday, May 27, 2002 8:58 PM
Subject: Re: draft howto dtd
> Hi Ivelin and Rob, i have an alert.
>
> I do not know how far they are progressed.
> However, Steven Noels and some of his colleagues
> are working a Cocoon facility that they referred to
> as directory-generator-on-steroids ... as a replacemnt
> for book.xml
>
> So what i am saying is ... Heads Up, be careful that
> you do not waste valuable effort. I am not saying
> that your discussion is not relevant.I have only
> skimmed through it and thought that i had better
> tell you about overlap.
>
> I think that there have been small discussions about
> their work on both cocoon-dev and forrest-dev
>
> Also i think that it would be a good idea for you
> to change the subject title of this thread.
> --David
>
> Ivelin Ivanov wrote:
> >
> > Rob,
> >
> > you guessed right, sorry I wasn't clear.
> > I meant that the reference to the book.xml files can be easily made
> > available to the other documents.
> > And yes your suggested syntax makes sence to me.
> >
> > <xsl:param name="bookDocument"/>
> > <xsl:variable
> > name="book-xml"
> > select="document($bookDocument)/book"/>
> >
> > Then referencing in documents can be as simple as:
> >
> > <link href="{book-xml/menu/menu-item[@id='howto-step1]/@href}'">
> >
> > or even
> >
> > <link href="{book-xml//*[@id='howto-step1]/@href}'">
> >
> > Provided ids are unique.
> >
> > That is when the documents are allowed to use xsl (why not?).
> >
> > If we prefer to keep documents strictly static, then your suggestion is
a
> > valid solution.
> > I would only prefer to use the attribute names as:
> >
> > <link href="http://good old method">
> >
> > and something like
> >
> > <link book-href="'howto-step1"/>
> >
> >
> > What do others think?
> >
> >
> > Ivelin
> >
> >
> >
> > ----- Original Message -----
> > From: "Robert Koberg" <ro...@koberg.com>
> > To: <fo...@xml.apache.org>
> > Sent: Monday, May 27, 2002 3:55 PM
> > Subject: Re: draft howto dtd
> >
> >
> > Hi again,
> >
> > A couple of things i want to mention after rereading this...
> >
> > the book.xml should have the cocoon folder-name so it can resolve to it
> > instead of the docroot, for example:
> >
> > <book id="f1" label="Cocoon" folder-name="cocoon">
> > <menu id="f1234" label="Samples" folder-name="samples">
> > <menu-item id="c3432" label="Samples Home" file-name="index.html"/>
> > etc...
> >
> > Also, I am thinking you meant the the book-xml param might be a string
> > with a relative or full path to the book.xml file??
> >
> > If so, then instead of:
> > <xsl:param name="book-xml"/>
> > use:
> > <xsl:param name="bookDocument"/>
> > <xsl:variable
> > name="book-xml"
> > select="document($bookDocument)/book"/>
> >
> > Does this make sense?
> >
> > -Rob
> >
> >
> > Robert Koberg wrote:
> >
> > > Hi Ivelin,
> > >
> > > Ivelin Ivanov wrote:
> > >
> > >> Good points.
> > >>
> > >> ----- Original Message -----
> > >> From: "Robert Koberg" <ro...@koberg.com>
> > >>
> > >>
> > >>> Hi,
> > >>>
> > >>> On the book.xml (menu/site-structure) and index.xml (content piece),
for
> > >>> example: why duplicate link's href values - if you had access to
> > >>> book.xml (the menu or site structure) you could reference links by
ID
> > >>> instead of a hard coded link. For example the content hard codes
links
> > >>> to faq.html or http://xml.apache.org/cocoon. Why not have th1?in
one
> > >>> location (book.xml) and refer to them? It would be nice to reuse the
> > >>> data provided by book.xml (perhaps even store more page level meta
info
> > >>> there?? show-toc, show-meta-data, show-on-nav - or at the folder
level:
> > >>> number-pages, show-on-nav - etc). Even better have book.xml be a
> > >>> representation of the entire site hierarchy. Then you can
recursviely
> > >>> build paths to documents. For all the good book.xml does it could be
> > >>> written straight into the XSLT (and included :).
> > >>>
> > >>
> > >>
> > >> Can you suggest a concrete (preferably standard) technique for
> > >> documents to
> > >> use links from within book.xml?
> > >>
> > > Sure. How about something like this:
> > >
> > > book.xml (I have an alternative if you are interested...)
> > > -----------------------------
> > > <book>
> > > <menu id="f1234" label="Document Sample" folder-name="samples">
> > > <menu-item id="c3432" label="Samples Home"
file-name="index.html"/>
> > > <menu id="f6234" label="Pipelines" folder-name="pipelines">
> > > <menu-item id="c7663" label="Pipeline 1"
> > > file-name="pipeline1.html"/>
> > > <menu-item id="c8795" label="Pipeline 2"
> > > file-name="pipeline2.html"/>
> > > </menu>
> > > </menu>
> > > </book>
> > >
> > > a content XML, say the cocoon home page:
> > > -----------------------------
> > > <article>
> > > <title>jdfghjdfgh jsdfjksd</title>
> > > <para>Check out <link id="c8795">Pipeline 2</link> or go out to
> > > bubba's site to see this <link
> > > out="http://www.bubba.com/example.html">example</link>
> > > </article>
> > >
> > > <!-- perhaps all you need is <link id="c8795"/> and the label or link
> > > text can come from the book.xml, see the XSLT below for clues how this
> > > could be done -->
> > >
> > > ============================
> > > If you can pass the XML (nodeset) in as a param then you would not
> > > need the XPath document function. In a primary XSLT you bring the
> > > top-level param for the above config XML:
> > > ---------
> > > <xsl:param name="book-xml"/>
> > > =======
> > > also make a key at the top-level for speed in accessing the correct
> > > menu{-item}:
> > > -------
> > > <xsl:key name="menu-id-key" match="menu | menu-item" use="@id"/>
> > > ========
> > > Then at some point you match a link:
> > > -------
> > > <xsl:template match="link">
> > > <!-- choose whether it is internal or external -->
> > > <xsl:variable name="href">
> > > <xsl:choose>
> > > <xsl:when test="boolean(@id)">
> > > <xsl:apply-templates select="$book-xml">
> > > <xsl:with-param name="link_id" select="@id"/>
> > > </xsl:apply-templates>
> > > </xsl:when>
> > > <xsl:when test="boolean(@out)">
> > > <xsl:value-of select="@out"/>
> > > </xsl:when>
> > > </xsl:choose>
> > > </xsl:variable>
> > >
> > > <a href="{$href}">
> > > <xsl:if test="boolean(@out)">
> > > <xsl:attribute name="target">_blank</xsl:attribute>
> > > </xsl:if>
> > > <xsl:apply-templates/>
> > > </a>
> > > </xsl:template>
> > >
> > > <!-- change contexts to the book-xml nodeset (so you can use the key
> > > and travel the XML) -->
> > > <xsl:template match="book">
> > > <xsl:param name="link_id"/>
> > > <xsl:apply-templates select="key('menu-id-key', $link_id)"
> > > mode="linker"/>
> > > </xsl:template>
> > >
> > > <!-- recurse over the path to the document and provide the path
info -->
> > > <!-- something like this - not tested -->
> > > <xsl:template match="menu-item | menu" mode="linker">
> > > <xsl:apply-templates select="parent::menu"/>
> > > <xsl:text>/<xsl:text>
> > > <xsl:value-of select="@file-name"/>
> > > </xsl:template>
> > >
> > > <xsl:template match="menu-item | menu">
> > > <xsl:apply-templates select="parent::menu"/>
> > > <xsl:text>/<xsl:text>
> > > <xsl:value-of select="@folder-name"/>
> > > </xsl:template>
> > >
> > >
> > >
> > >
> > >
> > >> It has been proposed that W3C Topic Maps can be useful.
> > >> http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
> > >>
> > > have not looked too far into this :(
> > >
> > >>
> > >> How about using the document link tag like this:
> > >>
> > >> <link
href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
> > >>
> > > See above
> > >
> > >>
> > >> Where the bookDocument variable is passed in from the sitemap.
> > >> This will require that the document files are not plain xml files,
> > >> but xslt
> > >> files instead.
> > >>
> > > hmmm... why do they need to be XSLT? Can it be passed in as a nodeset
> > > to a top-level param, since we can't use the XPath document function
> > > to get it from the filesystem.
> > >
> > > best,
> > > -Rob
> > >
> > >> To keep things clean maybe the <link/> tag can be extended with
> > >> syntax like:
> > >>
> > >> <link href="book/howto-step1"/> or similar
> > >>
> > >>
> > >>
> > >>> I still don't see what is wrong with using import or include to
bring
> > >>> together many XSLTs into one. The cocoon way of performing multiple
> > >>> transformations seems like way too much work when you want to break
your
> > >>> XSLT into component pieces for easy reusability.
> > >>>
> > >>> I think you miss a *great deal* of the benefit of XSLT by not using
the
> > >>> document function and import/include. I can't seem to come up with a
> > >>> good way to do the things I want to do without them.
> > >>>
> > >>
> > >>
> > >> I agree that the map:aggregate in the sitemap is somewhat redundand.
> > >> What are its advantages over passing the components as parameters to
a
> > >> normal XSLT page
> > >> which includes them either through include/import or the document()
> > >> function.
> > >> The advantages that I see in the latter approach are that its
> > >> utilizing XML
> > >> standards.
> > >> It also allows use of namespaces in the aggregating document, allows
> > >> references to validation documents,
> > >> and everything else you can use in an XSLT document.
> > >> Additionally the link referencing suggested above is natural.
> > >>
> > >>
> > >> Cheers,
> > >>
> > >> Ivelin
> > >>
> > >>
> > >>
> > >>
> > >>> I would love clear, explicit documentation on how to do things that
are
> > >>> commonplace in regular XSLT but are to be avoided when using cocoon.
> > >>>
> > >>> best,
> > >>> -Rob
> > >>>
> > >>>
> > >>>
> > >>
> > >
> > >
> >
> >
> >
> >
> >
>
>
Re: draft howto dtd
Posted by David Crossley <cr...@indexgeo.com.au>.
Hi Ivelin and Rob, i have an alert.
I do not know how far they are progressed.
However, Steven Noels and some of his colleagues
are working a Cocoon facility that they referred to
as directory-generator-on-steroids ... as a replacemnt
for book.xml
So what i am saying is ... Heads Up, be careful that
you do not waste valuable effort. I am not saying
that your discussion is not relevant.I have only
skimmed through it and thought that i had better
tell you about overlap.
I think that there have been small discussions about
their work on both cocoon-dev and forrest-dev
Also i think that it would be a good idea for you
to change the subject title of this thread.
--David
Ivelin Ivanov wrote:
>
> Rob,
>
> you guessed right, sorry I wasn't clear.
> I meant that the reference to the book.xml files can be easily made
> available to the other documents.
> And yes your suggested syntax makes sence to me.
>
> <xsl:param name="bookDocument"/>
> <xsl:variable
> name="book-xml"
> select="document($bookDocument)/book"/>
>
> Then referencing in documents can be as simple as:
>
> <link href="{book-xml/menu/menu-item[@id='howto-step1]/@href}'">
>
> or even
>
> <link href="{book-xml//*[@id='howto-step1]/@href}'">
>
> Provided ids are unique.
>
> That is when the documents are allowed to use xsl (why not?).
>
> If we prefer to keep documents strictly static, then your suggestion is a
> valid solution.
> I would only prefer to use the attribute names as:
>
> <link href="http://good old method">
>
> and something like
>
> <link book-href="'howto-step1"/>
>
>
> What do others think?
>
>
> Ivelin
>
>
>
> ----- Original Message -----
> From: "Robert Koberg" <ro...@koberg.com>
> To: <fo...@xml.apache.org>
> Sent: Monday, May 27, 2002 3:55 PM
> Subject: Re: draft howto dtd
>
>
> Hi again,
>
> A couple of things i want to mention after rereading this...
>
> the book.xml should have the cocoon folder-name so it can resolve to it
> instead of the docroot, for example:
>
> <book id="f1" label="Cocoon" folder-name="cocoon">
> <menu id="f1234" label="Samples" folder-name="samples">
> <menu-item id="c3432" label="Samples Home" file-name="index.html"/>
> etc...
>
> Also, I am thinking you meant the the book-xml param might be a string
> with a relative or full path to the book.xml file??
>
> If so, then instead of:
> <xsl:param name="book-xml"/>
> use:
> <xsl:param name="bookDocument"/>
> <xsl:variable
> name="book-xml"
> select="document($bookDocument)/book"/>
>
> Does this make sense?
>
> -Rob
>
>
> Robert Koberg wrote:
>
> > Hi Ivelin,
> >
> > Ivelin Ivanov wrote:
> >
> >> Good points.
> >>
> >> ----- Original Message -----
> >> From: "Robert Koberg" <ro...@koberg.com>
> >>
> >>
> >>> Hi,
> >>>
> >>> On the book.xml (menu/site-structure) and index.xml (content piece), for
> >>> example: why duplicate link's href values - if you had access to
> >>> book.xml (the menu or site structure) you could reference links by ID
> >>> instead of a hard coded link. For example the content hard codes links
> >>> to faq.html or http://xml.apache.org/cocoon. Why not have th1?in one
> >>> location (book.xml) and refer to them? It would be nice to reuse the
> >>> data provided by book.xml (perhaps even store more page level meta info
> >>> there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
> >>> number-pages, show-on-nav - etc). Even better have book.xml be a
> >>> representation of the entire site hierarchy. Then you can recursviely
> >>> build paths to documents. For all the good book.xml does it could be
> >>> written straight into the XSLT (and included :).
> >>>
> >>
> >>
> >> Can you suggest a concrete (preferably standard) technique for
> >> documents to
> >> use links from within book.xml?
> >>
> > Sure. How about something like this:
> >
> > book.xml (I have an alternative if you are interested...)
> > -----------------------------
> > <book>
> > <menu id="f1234" label="Document Sample" folder-name="samples">
> > <menu-item id="c3432" label="Samples Home" file-name="index.html"/>
> > <menu id="f6234" label="Pipelines" folder-name="pipelines">
> > <menu-item id="c7663" label="Pipeline 1"
> > file-name="pipeline1.html"/>
> > <menu-item id="c8795" label="Pipeline 2"
> > file-name="pipeline2.html"/>
> > </menu>
> > </menu>
> > </book>
> >
> > a content XML, say the cocoon home page:
> > -----------------------------
> > <article>
> > <title>jdfghjdfgh jsdfjksd</title>
> > <para>Check out <link id="c8795">Pipeline 2</link> or go out to
> > bubba's site to see this <link
> > out="http://www.bubba.com/example.html">example</link>
> > </article>
> >
> > <!-- perhaps all you need is <link id="c8795"/> and the label or link
> > text can come from the book.xml, see the XSLT below for clues how this
> > could be done -->
> >
> > ============================
> > If you can pass the XML (nodeset) in as a param then you would not
> > need the XPath document function. In a primary XSLT you bring the
> > top-level param for the above config XML:
> > ---------
> > <xsl:param name="book-xml"/>
> > =======
> > also make a key at the top-level for speed in accessing the correct
> > menu{-item}:
> > -------
> > <xsl:key name="menu-id-key" match="menu | menu-item" use="@id"/>
> > ========
> > Then at some point you match a link:
> > -------
> > <xsl:template match="link">
> > <!-- choose whether it is internal or external -->
> > <xsl:variable name="href">
> > <xsl:choose>
> > <xsl:when test="boolean(@id)">
> > <xsl:apply-templates select="$book-xml">
> > <xsl:with-param name="link_id" select="@id"/>
> > </xsl:apply-templates>
> > </xsl:when>
> > <xsl:when test="boolean(@out)">
> > <xsl:value-of select="@out"/>
> > </xsl:when>
> > </xsl:choose>
> > </xsl:variable>
> >
> > <a href="{$href}">
> > <xsl:if test="boolean(@out)">
> > <xsl:attribute name="target">_blank</xsl:attribute>
> > </xsl:if>
> > <xsl:apply-templates/>
> > </a>
> > </xsl:template>
> >
> > <!-- change contexts to the book-xml nodeset (so you can use the key
> > and travel the XML) -->
> > <xsl:template match="book">
> > <xsl:param name="link_id"/>
> > <xsl:apply-templates select="key('menu-id-key', $link_id)"
> > mode="linker"/>
> > </xsl:template>
> >
> > <!-- recurse over the path to the document and provide the path info -->
> > <!-- something like this - not tested -->
> > <xsl:template match="menu-item | menu" mode="linker">
> > <xsl:apply-templates select="parent::menu"/>
> > <xsl:text>/<xsl:text>
> > <xsl:value-of select="@file-name"/>
> > </xsl:template>
> >
> > <xsl:template match="menu-item | menu">
> > <xsl:apply-templates select="parent::menu"/>
> > <xsl:text>/<xsl:text>
> > <xsl:value-of select="@folder-name"/>
> > </xsl:template>
> >
> >
> >
> >
> >
> >> It has been proposed that W3C Topic Maps can be useful.
> >> http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
> >>
> > have not looked too far into this :(
> >
> >>
> >> How about using the document link tag like this:
> >>
> >> <link href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
> >>
> > See above
> >
> >>
> >> Where the bookDocument variable is passed in from the sitemap.
> >> This will require that the document files are not plain xml files,
> >> but xslt
> >> files instead.
> >>
> > hmmm... why do they need to be XSLT? Can it be passed in as a nodeset
> > to a top-level param, since we can't use the XPath document function
> > to get it from the filesystem.
> >
> > best,
> > -Rob
> >
> >> To keep things clean maybe the <link/> tag can be extended with
> >> syntax like:
> >>
> >> <link href="book/howto-step1"/> or similar
> >>
> >>
> >>
> >>> I still don't see what is wrong with using import or include to bring
> >>> together many XSLTs into one. The cocoon way of performing multiple
> >>> transformations seems like way too much work when you want to break your
> >>> XSLT into component pieces for easy reusability.
> >>>
> >>> I think you miss a *great deal* of the benefit of XSLT by not using the
> >>> document function and import/include. I can't seem to come up with a
> >>> good way to do the things I want to do without them.
> >>>
> >>
> >>
> >> I agree that the map:aggregate in the sitemap is somewhat redundand.
> >> What are its advantages over passing the components as parameters to a
> >> normal XSLT page
> >> which includes them either through include/import or the document()
> >> function.
> >> The advantages that I see in the latter approach are that its
> >> utilizing XML
> >> standards.
> >> It also allows use of namespaces in the aggregating document, allows
> >> references to validation documents,
> >> and everything else you can use in an XSLT document.
> >> Additionally the link referencing suggested above is natural.
> >>
> >>
> >> Cheers,
> >>
> >> Ivelin
> >>
> >>
> >>
> >>
> >>> I would love clear, explicit documentation on how to do things that are
> >>> commonplace in regular XSLT but are to be avoided when using cocoon.
> >>>
> >>> best,
> >>> -Rob
> >>>
> >>>
> >>>
> >>
> >
> >
>
>
>
>
>
Re: draft howto dtd
Posted by Ivelin Ivanov <iv...@apache.org>.
Rob,
you guessed right, sorry I wasn't clear.
I meant that the reference to the book.xml files can be easily made
available to the other documents.
And yes your suggested syntax makes sence to me.
<xsl:param name="bookDocument"/>
<xsl:variable
name="book-xml"
select="document($bookDocument)/book"/>
Then referencing in documents can be as simple as:
<link href="{book-xml/menu/menu-item[@id='howto-step1]/@href}'">
or even
<link href="{book-xml//*[@id='howto-step1]/@href}'">
Provided ids are unique.
That is when the documents are allowed to use xsl (why not?).
If we prefer to keep documents strictly static, then your suggestion is a
valid solution.
I would only prefer to use the attribute names as:
<link href="http://good old method">
and something like
<link book-href="'howto-step1"/>
What do others think?
Ivelin
----- Original Message -----
From: "Robert Koberg" <ro...@koberg.com>
To: <fo...@xml.apache.org>
Sent: Monday, May 27, 2002 3:55 PM
Subject: Re: draft howto dtd
Hi again,
A couple of things i want to mention after rereading this...
the book.xml should have the cocoon folder-name so it can resolve to it
instead of the docroot, for example:
<book id="f1" label="Cocoon" folder-name="cocoon">
<menu id="f1234" label="Samples" folder-name="samples">
<menu-item id="c3432" label="Samples Home" file-name="index.html"/>
etc...
Also, I am thinking you meant the the book-xml param might be a string
with a relative or full path to the book.xml file??
If so, then instead of:
<xsl:param name="book-xml"/>
use:
<xsl:param name="bookDocument"/>
<xsl:variable
name="book-xml"
select="document($bookDocument)/book"/>
Does this make sense?
-Rob
Robert Koberg wrote:
> Hi Ivelin,
>
> Ivelin Ivanov wrote:
>
>> Good points.
>>
>> ----- Original Message -----
>> From: "Robert Koberg" <ro...@koberg.com>
>>
>>
>>> Hi,
>>>
>>> On the book.xml (menu/site-structure) and index.xml (content piece), for
>>> example: why duplicate link's href values - if you had access to
>>> book.xml (the menu or site structure) you could reference links by ID
>>> instead of a hard coded link. For example the content hard codes links
>>> to faq.html or http://xml.apache.org/cocoon. Why not have th1?in one
>>> location (book.xml) and refer to them? It would be nice to reuse the
>>> data provided by book.xml (perhaps even store more page level meta info
>>> there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
>>> number-pages, show-on-nav - etc). Even better have book.xml be a
>>> representation of the entire site hierarchy. Then you can recursviely
>>> build paths to documents. For all the good book.xml does it could be
>>> written straight into the XSLT (and included :).
>>>
>>
>>
>> Can you suggest a concrete (preferably standard) technique for
>> documents to
>> use links from within book.xml?
>>
> Sure. How about something like this:
>
> book.xml (I have an alternative if you are interested...)
> -----------------------------
> <book>
> <menu id="f1234" label="Document Sample" folder-name="samples">
> <menu-item id="c3432" label="Samples Home" file-name="index.html"/>
> <menu id="f6234" label="Pipelines" folder-name="pipelines">
> <menu-item id="c7663" label="Pipeline 1"
> file-name="pipeline1.html"/>
> <menu-item id="c8795" label="Pipeline 2"
> file-name="pipeline2.html"/>
> </menu>
> </menu>
> </book>
>
> a content XML, say the cocoon home page:
> -----------------------------
> <article>
> <title>jdfghjdfgh jsdfjksd</title>
> <para>Check out <link id="c8795">Pipeline 2</link> or go out to
> bubba's site to see this <link
> out="http://www.bubba.com/example.html">example</link>
> </article>
>
> <!-- perhaps all you need is <link id="c8795"/> and the label or link
> text can come from the book.xml, see the XSLT below for clues how this
> could be done -->
>
> ============================
> If you can pass the XML (nodeset) in as a param then you would not
> need the XPath document function. In a primary XSLT you bring the
> top-level param for the above config XML:
> ---------
> <xsl:param name="book-xml"/>
> =======
> also make a key at the top-level for speed in accessing the correct
> menu{-item}:
> -------
> <xsl:key name="menu-id-key" match="menu | menu-item" use="@id"/>
> ========
> Then at some point you match a link:
> -------
> <xsl:template match="link">
> <!-- choose whether it is internal or external -->
> <xsl:variable name="href">
> <xsl:choose>
> <xsl:when test="boolean(@id)">
> <xsl:apply-templates select="$book-xml">
> <xsl:with-param name="link_id" select="@id"/>
> </xsl:apply-templates>
> </xsl:when>
> <xsl:when test="boolean(@out)">
> <xsl:value-of select="@out"/>
> </xsl:when>
> </xsl:choose>
> </xsl:variable>
>
> <a href="{$href}">
> <xsl:if test="boolean(@out)">
> <xsl:attribute name="target">_blank</xsl:attribute>
> </xsl:if>
> <xsl:apply-templates/>
> </a>
> </xsl:template>
>
> <!-- change contexts to the book-xml nodeset (so you can use the key
> and travel the XML) -->
> <xsl:template match="book">
> <xsl:param name="link_id"/>
> <xsl:apply-templates select="key('menu-id-key', $link_id)"
> mode="linker"/>
> </xsl:template>
>
> <!-- recurse over the path to the document and provide the path info -->
> <!-- something like this - not tested -->
> <xsl:template match="menu-item | menu" mode="linker">
> <xsl:apply-templates select="parent::menu"/>
> <xsl:text>/<xsl:text>
> <xsl:value-of select="@file-name"/>
> </xsl:template>
>
> <xsl:template match="menu-item | menu">
> <xsl:apply-templates select="parent::menu"/>
> <xsl:text>/<xsl:text>
> <xsl:value-of select="@folder-name"/>
> </xsl:template>
>
>
>
>
>
>> It has been proposed that W3C Topic Maps can be useful.
>> http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
>>
> have not looked too far into this :(
>
>>
>> How about using the document link tag like this:
>>
>> <link href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
>>
> See above
>
>>
>> Where the bookDocument variable is passed in from the sitemap.
>> This will require that the document files are not plain xml files,
>> but xslt
>> files instead.
>>
> hmmm... why do they need to be XSLT? Can it be passed in as a nodeset
> to a top-level param, since we can't use the XPath document function
> to get it from the filesystem.
>
> best,
> -Rob
>
>> To keep things clean maybe the <link/> tag can be extended with
>> syntax like:
>>
>> <link href="book/howto-step1"/> or similar
>>
>>
>>
>>> I still don't see what is wrong with using import or include to bring
>>> together many XSLTs into one. The cocoon way of performing multiple
>>> transformations seems like way too much work when you want to break your
>>> XSLT into component pieces for easy reusability.
>>>
>>> I think you miss a *great deal* of the benefit of XSLT by not using the
>>> document function and import/include. I can't seem to come up with a
>>> good way to do the things I want to do without them.
>>>
>>
>>
>> I agree that the map:aggregate in the sitemap is somewhat redundand.
>> What are its advantages over passing the components as parameters to a
>> normal XSLT page
>> which includes them either through include/import or the document()
>> function.
>> The advantages that I see in the latter approach are that its
>> utilizing XML
>> standards.
>> It also allows use of namespaces in the aggregating document, allows
>> references to validation documents,
>> and everything else you can use in an XSLT document.
>> Additionally the link referencing suggested above is natural.
>>
>>
>> Cheers,
>>
>> Ivelin
>>
>>
>>
>>
>>> I would love clear, explicit documentation on how to do things that are
>>> commonplace in regular XSLT but are to be avoided when using cocoon.
>>>
>>> best,
>>> -Rob
>>>
>>>
>>>
>>
>
>
Re: draft howto dtd
Posted by Robert Koberg <ro...@koberg.com>.
Hi again,
A couple of things i want to mention after rereading this...
the book.xml should have the cocoon folder-name so it can resolve to it
instead of the docroot, for example:
<book id="f1" label="Cocoon" folder-name="cocoon">
<menu id="f1234" label="Samples" folder-name="samples">
<menu-item id="c3432" label="Samples Home" file-name="index.html"/>
etc...
Also, I am thinking you meant the the book-xml param might be a string
with a relative or full path to the book.xml file??
If so, then instead of:
<xsl:param name="book-xml"/>
use:
<xsl:param name="bookDocument"/>
<xsl:variable
name="book-xml"
select="document($bookDocument)/book"/>
Does this make sense?
-Rob
Robert Koberg wrote:
> Hi Ivelin,
>
> Ivelin Ivanov wrote:
>
>> Good points.
>>
>> ----- Original Message -----
>> From: "Robert Koberg" <ro...@koberg.com>
>>
>>
>>> Hi,
>>>
>>> On the book.xml (menu/site-structure) and index.xml (content piece), for
>>> example: why duplicate link's href values - if you had access to
>>> book.xml (the menu or site structure) you could reference links by ID
>>> instead of a hard coded link. For example the content hard codes links
>>> to faq.html or http://xml.apache.org/cocoon. Why not have th1� in one
>>> location (book.xml) and refer to them? It would be nice to reuse the
>>> data provided by book.xml (perhaps even store more page level meta info
>>> there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
>>> number-pages, show-on-nav - etc). Even better have book.xml be a
>>> representation of the entire site hierarchy. Then you can recursviely
>>> build paths to documents. For all the good book.xml does it could be
>>> written straight into the XSLT (and included :).
>>>
>>
>>
>> Can you suggest a concrete (preferably standard) technique for
>> documents to
>> use links from within book.xml?
>>
> Sure. How about something like this:
>
> book.xml (I have an alternative if you are interested...)
> -----------------------------
> <book>
> <menu id="f1234" label="Document Sample" folder-name="samples">
> <menu-item id="c3432" label="Samples Home" file-name="index.html"/>
> <menu id="f6234" label="Pipelines" folder-name="pipelines">
> <menu-item id="c7663" label="Pipeline 1"
> file-name="pipeline1.html"/>
> <menu-item id="c8795" label="Pipeline 2"
> file-name="pipeline2.html"/>
> </menu>
> </menu>
> </book>
>
> a content XML, say the cocoon home page:
> -----------------------------
> <article>
> <title>jdfghjdfgh jsdfjksd</title>
> <para>Check out <link id="c8795">Pipeline 2</link> or go out to
> bubba's site to see this <link
> out="http://www.bubba.com/example.html">example</link>
> </article>
>
> <!-- perhaps all you need is <link id="c8795"/> and the label or link
> text can come from the book.xml, see the XSLT below for clues how this
> could be done -->
>
> ============================
> If you can pass the XML (nodeset) in as a param then you would not
> need the XPath document function. In a primary XSLT you bring the
> top-level param for the above config XML:
> ---------
> <xsl:param name="book-xml"/>
> =======
> also make a key at the top-level for speed in accessing the correct
> menu{-item}:
> -------
> <xsl:key name="menu-id-key" match="menu | menu-item" use="@id"/>
> ========
> Then at some point you match a link:
> -------
> <xsl:template match="link">
> <!-- choose whether it is internal or external -->
> <xsl:variable name="href">
> <xsl:choose>
> <xsl:when test="boolean(@id)">
> <xsl:apply-templates select="$book-xml">
> <xsl:with-param name="link_id" select="@id"/>
> </xsl:apply-templates>
> </xsl:when>
> <xsl:when test="boolean(@out)">
> <xsl:value-of select="@out"/>
> </xsl:when>
> </xsl:choose>
> </xsl:variable>
>
> <a href="{$href}">
> <xsl:if test="boolean(@out)">
> <xsl:attribute name="target">_blank</xsl:attribute>
> </xsl:if>
> <xsl:apply-templates/>
> </a>
> </xsl:template>
>
> <!-- change contexts to the book-xml nodeset (so you can use the key
> and travel the XML) -->
> <xsl:template match="book">
> <xsl:param name="link_id"/>
> <xsl:apply-templates select="key('menu-id-key', $link_id)"
> mode="linker"/>
> </xsl:template>
>
> <!-- recurse over the path to the document and provide the path info -->
> <!-- something like this - not tested -->
> <xsl:template match="menu-item | menu" mode="linker">
> <xsl:apply-templates select="parent::menu"/>
> <xsl:text>/<xsl:text>
> <xsl:value-of select="@file-name"/>
> </xsl:template>
>
> <xsl:template match="menu-item | menu">
> <xsl:apply-templates select="parent::menu"/>
> <xsl:text>/<xsl:text>
> <xsl:value-of select="@folder-name"/>
> </xsl:template>
>
>
>
>
>
>> It has been proposed that W3C Topic Maps can be useful.
>> http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
>>
> have not looked too far into this :(
>
>>
>> How about using the document link tag like this:
>>
>> <link href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
>>
> See above
>
>>
>> Where the bookDocument variable is passed in from the sitemap.
>> This will require that the document files are not plain xml files,
>> but xslt
>> files instead.
>>
> hmmm... why do they need to be XSLT? Can it be passed in as a nodeset
> to a top-level param, since we can't use the XPath document function
> to get it from the filesystem.
>
> best,
> -Rob
>
>> To keep things clean maybe the <link/> tag can be extended with
>> syntax like:
>>
>> <link href="book/howto-step1"/> or similar
>>
>>
>>
>>> I still don't see what is wrong with using import or include to bring
>>> together many XSLTs into one. The cocoon way of performing multiple
>>> transformations seems like way too much work when you want to break your
>>> XSLT into component pieces for easy reusability.
>>>
>>> I think you miss a *great deal* of the benefit of XSLT by not using the
>>> document function and import/include. I can't seem to come up with a
>>> good way to do the things I want to do without them.
>>>
>>
>>
>> I agree that the map:aggregate in the sitemap is somewhat redundand.
>> What are its advantages over passing the components as parameters to a
>> normal XSLT page
>> which includes them either through include/import or the document()
>> function.
>> The advantages that I see in the latter approach are that its
>> utilizing XML
>> standards.
>> It also allows use of namespaces in the aggregating document, allows
>> references to validation documents,
>> and everything else you can use in an XSLT document.
>> Additionally the link referencing suggested above is natural.
>>
>>
>> Cheers,
>>
>> Ivelin
>>
>>
>>
>>
>>> I would love clear, explicit documentation on how to do things that are
>>> commonplace in regular XSLT but are to be avoided when using cocoon.
>>>
>>> best,
>>> -Rob
>>>
>>>
>>>
>>
>
>
Re: draft howto dtd
Posted by Robert Koberg <ro...@koberg.com>.
Hi Ivelin,
Ivelin Ivanov wrote:
>Good points.
>
>----- Original Message -----
>From: "Robert Koberg" <ro...@koberg.com>
>
>
>>Hi,
>>
>>On the book.xml (menu/site-structure) and index.xml (content piece), for
>>example: why duplicate link's href values - if you had access to
>>book.xml (the menu or site structure) you could reference links by ID
>>instead of a hard coded link. For example the content hard codes links
>>to faq.html or http://xml.apache.org/cocoon. Why not have these in one
>>location (book.xml) and refer to them? It would be nice to reuse the
>>data provided by book.xml (perhaps even store more page level meta info
>>there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
>>number-pages, show-on-nav - etc). Even better have book.xml be a
>>representation of the entire site hierarchy. Then you can recursviely
>>build paths to documents. For all the good book.xml does it could be
>>written straight into the XSLT (and included :).
>>
>>
>
>Can you suggest a concrete (preferably standard) technique for documents to
>use links from within book.xml?
>
Sure. How about something like this:
book.xml (I have an alternative if you are interested...)
-----------------------------
<book>
<menu id="f1234" label="Document Sample" folder-name="samples">
<menu-item id="c3432" label="Samples Home" file-name="index.html"/>
<menu id="f6234" label="Pipelines" folder-name="pipelines">
<menu-item id="c7663" label="Pipeline 1"
file-name="pipeline1.html"/>
<menu-item id="c8795" label="Pipeline
2" file-name="pipeline2.html"/>
</menu>
</menu>
</book>
a content XML, say the cocoon home page:
-----------------------------
<article>
<title>jdfghjdfgh jsdfjksd</title>
<para>Check out <link id="c8795">Pipeline 2</link> or go out to
bubba's site to see this <link
out="http://www.bubba.com/example.html">example</link>
</article>
<!-- perhaps all you need is <link id="c8795"/> and the label or link
text can come from the book.xml, see the XSLT below for clues how this
could be done -->
============================
If you can pass the XML (nodeset) in as a param then you would not need
the XPath document function. In a primary XSLT you bring the top-level
param for the above config XML:
---------
<xsl:param name="book-xml"/>
=======
also make a key at the top-level for speed in accessing the correct
menu{-item}:
-------
<xsl:key name="menu-id-key" match="menu | menu-item" use="@id"/>
========
Then at some point you match a link:
-------
<xsl:template match="link">
<!-- choose whether it is internal or external -->
<xsl:variable name="href">
<xsl:choose>
<xsl:when test="boolean(@id)">
<xsl:apply-templates select="$book-xml">
<xsl:with-param name="link_id" select="@id"/>
</xsl:apply-templates>
</xsl:when>
<xsl:when test="boolean(@out)">
<xsl:value-of select="@out"/>
</xsl:when>
</xsl:choose>
</xsl:variable>
<a href="{$href}">
<xsl:if test="boolean(@out)">
<xsl:attribute name="target">_blank</xsl:attribute>
</xsl:if>
<xsl:apply-templates/>
</a>
</xsl:template>
<!-- change contexts to the book-xml nodeset (so you can use the key and
travel the XML) -->
<xsl:template match="book">
<xsl:param name="link_id"/>
<xsl:apply-templates select="key('menu-id-key', $link_id)"
mode="linker"/>
</xsl:template>
<!-- recurse over the path to the document and provide the path info -->
<!-- something like this - not tested -->
<xsl:template match="menu-item | menu" mode="linker">
<xsl:apply-templates select="parent::menu"/>
<xsl:text>/<xsl:text>
<xsl:value-of select="@file-name"/>
</xsl:template>
<xsl:template match="menu-item | menu">
<xsl:apply-templates select="parent::menu"/>
<xsl:text>/<xsl:text>
<xsl:value-of select="@folder-name"/>
</xsl:template>
>It has been proposed that W3C Topic Maps can be useful.
>http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
>
have not looked too far into this :(
>
>How about using the document link tag like this:
>
><link href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
>
See above
>
>Where the bookDocument variable is passed in from the sitemap.
>This will require that the document files are not plain xml files, but xslt
>files instead.
>
hmmm... why do they need to be XSLT? Can it be passed in as a nodeset to
a top-level param, since we can't use the XPath document function to get
it from the filesystem.
best,
-Rob
>To keep things clean maybe the <link/> tag can be extended with syntax like:
>
><link href="book/howto-step1"/> or similar
>
>
>
>>I still don't see what is wrong with using import or include to bring
>>together many XSLTs into one. The cocoon way of performing multiple
>>transformations seems like way too much work when you want to break your
>>XSLT into component pieces for easy reusability.
>>
>>I think you miss a *great deal* of the benefit of XSLT by not using the
>>document function and import/include. I can't seem to come up with a
>>good way to do the things I want to do without them.
>>
>>
>
>I agree that the map:aggregate in the sitemap is somewhat redundand.
>What are its advantages over passing the components as parameters to a
>normal XSLT page
>which includes them either through include/import or the document()
>function.
>The advantages that I see in the latter approach are that its utilizing XML
>standards.
>It also allows use of namespaces in the aggregating document, allows
>references to validation documents,
>and everything else you can use in an XSLT document.
>Additionally the link referencing suggested above is natural.
>
>
>Cheers,
>
>Ivelin
>
>
>
>
>>I would love clear, explicit documentation on how to do things that are
>>commonplace in regular XSLT but are to be avoided when using cocoon.
>>
>>best,
>>-Rob
>>
>>
>>
>>
Re: draft howto dtd
Posted by Ivelin Ivanov <iv...@apache.org>.
Good points.
----- Original Message -----
From: "Robert Koberg" <ro...@koberg.com>
To: <fo...@xml.apache.org>
Sent: Sunday, May 26, 2002 12:10 AM
Subject: Re: draft howto dtd
> Hi,
>
> On the book.xml (menu/site-structure) and index.xml (content piece), for
> example: why duplicate link's href values - if you had access to
> book.xml (the menu or site structure) you could reference links by ID
> instead of a hard coded link. For example the content hard codes links
> to faq.html or http://xml.apache.org/cocoon. Why not have these in one
> location (book.xml) and refer to them? It would be nice to reuse the
> data provided by book.xml (perhaps even store more page level meta info
> there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
> number-pages, show-on-nav - etc). Even better have book.xml be a
> representation of the entire site hierarchy. Then you can recursviely
> build paths to documents. For all the good book.xml does it could be
> written straight into the XSLT (and included :).
Can you suggest a concrete (preferably standard) technique for documents to
use links from within book.xml?
It has been proposed that W3C Topic Maps can be useful.
http://www.gca.org/papers/xmleurope2000/papers/s11-02.html
How about using the document link tag like this:
<link href="document({$bookDocument})/menu/menu-item[@id='howto-step1'">
Where the bookDocument variable is passed in from the sitemap.
This will require that the document files are not plain xml files, but xslt
files instead.
To keep things clean maybe the <link/> tag can be extended with syntax like:
<link href="book/howto-step1"/> or similar.
> I still don't see what is wrong with using import or include to bring
> together many XSLTs into one. The cocoon way of performing multiple
> transformations seems like way too much work when you want to break your
> XSLT into component pieces for easy reusability.
>
> I think you miss a *great deal* of the benefit of XSLT by not using the
> document function and import/include. I can't seem to come up with a
> good way to do the things I want to do without them.
I agree that the map:aggregate in the sitemap is somewhat redundand.
What are its advantages over passing the components as parameters to a
normal XSLT page
which includes them either through include/import or the document()
function.
The advantages that I see in the latter approach are that its utilizing XML
standards.
It also allows use of namespaces in the aggregating document, allows
references to validation documents,
and everything else you can use in an XSLT document.
Additionally the link referencing suggested above is natural.
Cheers,
Ivelin
>
> I would love clear, explicit documentation on how to do things that are
> commonplace in regular XSLT but are to be avoided when using cocoon.
>
> best,
> -Rob
>
>
> Ivelin Ivanov wrote:
>
> >I just finished reviewing all pages on xml.apache.org/forrest
> >
> >Encouraging first steps !
> >
> >
> >A few more almost-negligible notes:
> >
> >Typos:
> >
> >http://xml.apache.org/forrest/primer.html
> >Forrest site generation using Cocoon
> >
> >The docs target of the Forrest build environment invokes Cocoon as a
> >command-line application to generate an HTML rendition of the project's
> >documentation. It is not within the scope of this document to explain the
> >Cocoon internals, please read ***the its*** own documentation to fully
> >understand the power of Cocoon.
> >
> >
> >Cocoon responds by aggregating two 'sub-requests'. The first is for the
> >resource book-{1}.xml, the second is for the resource body-{1}.xml. The
{1}
> >parameter is replaced by the ***valuse*** of the first wildcard in the
> >matching pattern above. These 'sub-requests' are passed through the
cocoon
> >pipeline just like any other request. This results in the following flow:
> >
> >
> >
> >
> >----- Original Message -----
> >From: "Diana Shannon" <te...@mac.com>
> >To: <fo...@xml.apache.org>
> >Sent: Wednesday, May 15, 2002 1:25 PM
> >Subject: draft howto dtd
> >
> >
> >
> >
> >>Attached is a howto dtd draft, along with a sample doc to validate. A
> >>few notes.
> >>
> >>1. I think the header element contains a lot of useful cms-related info.
> >>Perhaps version can be used to imply status: draft/release/revision. I'm
> >>not sure of its precise meaning with code, but perhaps "draft" document
> >>versions could have a value less than 1, etc.
> >>
> >>2. id attribute (via %common.att;) is defined for howto, so if CMS needs
> >>to manage docs via that attribute, we're still ok.
> >>
> >>3. I declared one additional child element of header:
> >>last-modified-content-date. Its purpose is to provide meaning to the
> >>reader based on content changes, not mere structural changes, etc. I'm
> >>not sure if it duplicates revision history structure at the bottom.
> >>
> >>4. I'm trying to take what is a liberal approach to what is allowed by
> >>the dtd. For example, I didn't use %content.mix; anywhere. I wanted to
> >>allow authors the chance to use lists for prerequesites, intended
> >>audience, etc. Perhaps some of you will consider this too loose.
> >>
> >>5. Steve, I wonder if you're going to dislike the way I'm treating
> >>titles (as attributes) in each howto part. I just found it a little
> >>simpler to implement this way. Feel free to revise, in anticipation of
> >>your v11 work.
> >>
> >>Anyway, please improve it. I'm certainly no expert. Snippets/tutorials
> >>dtds will be similarly structured, so I'll wait for comments before
> >>submitting those.
> >>
> >>Many thanks.
> >>
> >>Diana
> >>
> >>
> >>
> >>
> >
> >
>
>---------------------------------------------------------------------------
-
> >----
> >
> >
> >
> >
> >>
> >>
> >>
> >>
> >
> >
> >
>
>
Re: draft howto dtd
Posted by Robert Koberg <ro...@koberg.com>.
Hi,
On the book.xml (menu/site-structure) and index.xml (content piece), for
example: why duplicate link's href values - if you had access to
book.xml (the menu or site structure) you could reference links by ID
instead of a hard coded link. For example the content hard codes links
to faq.html or http://xml.apache.org/cocoon. Why not have these in one
location (book.xml) and refer to them? It would be nice to reuse the
data provided by book.xml (perhaps even store more page level meta info
there?? show-toc, show-meta-data, show-on-nav - or at the folder level:
number-pages, show-on-nav - etc). Even better have book.xml be a
representation of the entire site hierarchy. Then you can recursviely
build paths to documents. For all the good book.xml does it could be
written straight into the XSLT (and included :).
I still don't see what is wrong with using import or include to bring
together many XSLTs into one. The cocoon way of performing multiple
transformations seems like way too much work when you want to break your
XSLT into component pieces for easy reusability.
I think you miss a *great deal* of the benefit of XSLT by not using the
document function and import/include. I can't seem to come up with a
good way to do the things I want to do without them.
I would love clear, explicit documentation on how to do things that are
commonplace in regular XSLT but are to be avoided when using cocoon.
best,
-Rob
Ivelin Ivanov wrote:
>I just finished reviewing all pages on xml.apache.org/forrest
>
>Encouraging first steps !
>
>
>A few more almost-negligible notes:
>
>Typos:
>
>http://xml.apache.org/forrest/primer.html
>Forrest site generation using Cocoon
>
>The docs target of the Forrest build environment invokes Cocoon as a
>command-line application to generate an HTML rendition of the project's
>documentation. It is not within the scope of this document to explain the
>Cocoon internals, please read ***the its*** own documentation to fully
>understand the power of Cocoon.
>
>
>Cocoon responds by aggregating two 'sub-requests'. The first is for the
>resource book-{1}.xml, the second is for the resource body-{1}.xml. The {1}
>parameter is replaced by the ***valuse*** of the first wildcard in the
>matching pattern above. These 'sub-requests' are passed through the cocoon
>pipeline just like any other request. This results in the following flow:
>
>
>
>
>----- Original Message -----
>From: "Diana Shannon" <te...@mac.com>
>To: <fo...@xml.apache.org>
>Sent: Wednesday, May 15, 2002 1:25 PM
>Subject: draft howto dtd
>
>
>
>
>>Attached is a howto dtd draft, along with a sample doc to validate. A
>>few notes.
>>
>>1. I think the header element contains a lot of useful cms-related info.
>>Perhaps version can be used to imply status: draft/release/revision. I'm
>>not sure of its precise meaning with code, but perhaps "draft" document
>>versions could have a value less than 1, etc.
>>
>>2. id attribute (via %common.att;) is defined for howto, so if CMS needs
>>to manage docs via that attribute, we're still ok.
>>
>>3. I declared one additional child element of header:
>>last-modified-content-date. Its purpose is to provide meaning to the
>>reader based on content changes, not mere structural changes, etc. I'm
>>not sure if it duplicates revision history structure at the bottom.
>>
>>4. I'm trying to take what is a liberal approach to what is allowed by
>>the dtd. For example, I didn't use %content.mix; anywhere. I wanted to
>>allow authors the chance to use lists for prerequesites, intended
>>audience, etc. Perhaps some of you will consider this too loose.
>>
>>5. Steve, I wonder if you're going to dislike the way I'm treating
>>titles (as attributes) in each howto part. I just found it a little
>>simpler to implement this way. Feel free to revise, in anticipation of
>>your v11 work.
>>
>>Anyway, please improve it. I'm certainly no expert. Snippets/tutorials
>>dtds will be similarly structured, so I'll wait for comments before
>>submitting those.
>>
>>Many thanks.
>>
>>Diana
>>
>>
>>
>>
>
>
>----------------------------------------------------------------------------
>----
>
>
>
>
>>
>>
>>
>>
>
>
>
Re: draft howto dtd
Posted by Ivelin Ivanov <iv...@apache.org>.
I just finished reviewing all pages on xml.apache.org/forrest
Encouraging first steps !
A few more almost-negligible notes:
Typos:
http://xml.apache.org/forrest/primer.html
Forrest site generation using Cocoon
The docs target of the Forrest build environment invokes Cocoon as a
command-line application to generate an HTML rendition of the project's
documentation. It is not within the scope of this document to explain the
Cocoon internals, please read ***the its*** own documentation to fully
understand the power of Cocoon.
Cocoon responds by aggregating two 'sub-requests'. The first is for the
resource book-{1}.xml, the second is for the resource body-{1}.xml. The {1}
parameter is replaced by the ***valuse*** of the first wildcard in the
matching pattern above. These 'sub-requests' are passed through the cocoon
pipeline just like any other request. This results in the following flow:
----- Original Message -----
From: "Diana Shannon" <te...@mac.com>
To: <fo...@xml.apache.org>
Sent: Wednesday, May 15, 2002 1:25 PM
Subject: draft howto dtd
> Attached is a howto dtd draft, along with a sample doc to validate. A
> few notes.
>
> 1. I think the header element contains a lot of useful cms-related info.
> Perhaps version can be used to imply status: draft/release/revision. I'm
> not sure of its precise meaning with code, but perhaps "draft" document
> versions could have a value less than 1, etc.
>
> 2. id attribute (via %common.att;) is defined for howto, so if CMS needs
> to manage docs via that attribute, we're still ok.
>
> 3. I declared one additional child element of header:
> last-modified-content-date. Its purpose is to provide meaning to the
> reader based on content changes, not mere structural changes, etc. I'm
> not sure if it duplicates revision history structure at the bottom.
>
> 4. I'm trying to take what is a liberal approach to what is allowed by
> the dtd. For example, I didn't use %content.mix; anywhere. I wanted to
> allow authors the chance to use lists for prerequesites, intended
> audience, etc. Perhaps some of you will consider this too loose.
>
> 5. Steve, I wonder if you're going to dislike the way I'm treating
> titles (as attributes) in each howto part. I just found it a little
> simpler to implement this way. Feel free to revise, in anticipation of
> your v11 work.
>
> Anyway, please improve it. I'm certainly no expert. Snippets/tutorials
> dtds will be similarly structured, so I'll wait for comments before
> submitting those.
>
> Many thanks.
>
> Diana
>
>
----------------------------------------------------------------------------
----
>
>
>
>
Re: draft howto dtd
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Nicola Ken Barozzi wrote:
> From: "Ivelin Ivanov" <iv...@apache.org>
>>Do you guys thing its time to switch the DTD to XML Schema ?
> What is the technical reason for the use we do?
You can do some rather cooooool things with XSchema. For
example having elements which can have elements from
a *namespace* as children. In general, namespace support
can make for a much better modularity.
Lets say you write some docs (<grin>). You have some
elements for prosa. Some elements for describing
command line programs. Of course, you have a "parameter"
element there. Then you describe APIs, where you also
want to have a "parameter" element, but this, of course,
has slightly different semantics. With namespaces, you
can have cmd-ui:parameter and api:parameter elements,
and you can use them within one document. Even more useful
for other heavily overloaded terms, like "class" and
"component". You can have an element doc:command-line-def
which has only elements from cmd-ui:*. You can start with
a few elements in the cmd-ui namespace and add more later,
without having to change the definitions of the elements
where they are referred to. This can save a lot of work
while keeping validation useful (rather than ANY). It's
even better for references, for example you can reference
XMI stuff from docs. Basically, XSchema allows you to
view all your current DTD as one big modular structure
definition (if you want to), and you can do cross references
to *stuff* in other docs rather that using URLs to the
HTMLized transformation result. If properly done, you can
automatically check and *construct* cross references.
Well, lets stop here...
J.Pietschmann
Re: draft howto dtd
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Ivelin Ivanov" <iv...@apache.org>
> Do you guys thing its time to switch the DTD to XML Schema ?
> Xalan supports XML Schema validation and I've used it in production for a
> while now.
What is the technical reason for the use we do?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Forrest needs to settle down (Was: draft howto dtd)
Posted by David Crossley <cr...@indexgeo.com.au>.
Steady on, people, steady on. All these heated arguments
about Schema are not helping Forrest to move forward.
We have a young project here that we are trying to fledge [1].
We need to maintain our steady progress or it will die while
still in the nest. Please, rather focus your energies on the
current tasks. Later we can dream some more.
Anyway, we need solid DTDs for the current work. With that
base, we can later generate other schema from it.
[1] fledge ... verb. To raise a young bird until it is ready to fly.
--David
Re: draft howto dtd
Posted by Stefano Mazzocchi <st...@apache.org>.
Steven Noels wrote:
> Sorry for being so frank, but after teaching some courses on XML
> Schemas, I'm quite convinced it is a horribly bloated language.
Could hardly agree more.
I still think RelaxNG is the way to go... besides, it's piece of cake to
write a Cocoon transformer that uses JClark's code to perform
validation. Or even more: write a Xerces2 XNI plugin that does that (if
you don't know, Xerces 2.0 internally uses a pipeline approach which is
very similar to Cocoon's even if only parsing/validation oriented).
So, please, if we move away from DTDs (and I think we should at one
point, given the lack of namespace support that is starting to hurt a
lot!) please consider RelaxNG before XMLSchema.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: draft howto dtd
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Steven Noels wrote:
> You live with the assumption standards are correctly implemented by
> tools, regardless of their complexity.
Not really.
> If a standard (or better: the
> application of a standard) can only live within a certain predefined set
> of tools, it isn't much worth as a standard.
Well, even many mainstream XML parsers don't implement
all obscure *DTD* features:
http://www.biglist.com/lists/xsl-list/archives/200109/msg00406.html
and there are rarely complaints about this.
I'll note that the number of features used in the currend
Apache DTDs is fairly limited, I haven't found, for example
any conditional DTD sections.
> My problem with XML Schema is that it offers too many possible ways of
> declaring the same kind of thing, and believe me, when you hand over
> such a language to a creative user, he will make use of the exotic
> features, too.
Using XSchema for defining structures of Apache documents
is not exactly the same as handing it to arbitrary creative
users. Nobody stops the initial committers from writing up
some guidelines to restrict the subset to use. This can even
be quite fuzzy, the community will self correct and amend the
guidelines as needed. For example if there are repeated
complaints that a certain feature won't work, there will be
a discussion whether it's really necessary to use it, and
either it will be dropped or replaced or the complaining
people are convinced and move to tools which support the
feature or work around the deficiencies. I firmly believe
that XSchemas for Apache documents will start fairly simple
and probably stay so for quite some time, introduction of
"exotic features" will be frowned upon unless they add
real value.
For a start, because XSchema is hardly universally supported
by editors, it would be necessary to generate DTDs from the
schemas, and of course documents which validate against such
a DTD and some verbal guidelines ("put only svg:* in this
ANY element") should validate against the schema. The
pressure to keep the additional verbal guidelines as small
as possible will prevent usage of most of the "exotic
features" for some time.
As for your particular example regarding elements with
default content: I'm in favor of the view that XSLT
processors should be able to do their work without being
forced to read DTDs or schemas. Declaring default values
there thwarts this, therefore I don't like it.
> And then, you can only hope your editor, validation
> engine et al. will implement the same kind of 'standard', which is
> currently not the case.
Well, XSchema is bloated and I think it will finally topple
under its own weight and be replaced by something else,
perhaps by some subsets or "profiles" defining validation
against certain sets of rules. Until then, we can stick to
DTDs and deal with the restrictions (no namespaces, ANY,
no processing by XSLT), or we can make up our own rules
on how to deal with the problems XSchema while taking
adantage of the virtues.
J.Pietschmann
RE: draft howto dtd
Posted by Steven Noels <st...@outerthought.org>.
Joerg wrote:
> You can do the same things a DTD can: describe what elements
> can be children to elements, and what attributes an element
> can have.
> The equivalent of
> <!ELEMENT document (title,sect1+)>
> is
> <xsd:element name="document">
> <xsd:sequence>
> <xsd:element name="title" type="title"/>
> <xsd:element maxOccurs="unbounded" name="sect1" type="sect1"/>
> </xsd:sequence>
> </xsd:complexType>
>
> It's not all that horrible. And if you don't want to look at it,
> don't do it: write a style sheet to visualize the aspects you want.
> By the time you need it, chances are that some other lazy guy has
> already done this.
Of course, but this is only the simplest of examples. It's not the
syntax, the angle brackets nor the namespace prefixes that I have
troubles with. After all, we're used at using XML for various purposes
over here ;-)
Consider this:
<!ELEMENT foo (#PCDATA) >
<!ATTLIST foo bar CDATA #REQUIRED >
compared to:
<xsd:element name="foo">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="bar" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
and
<xsd:element name="foo">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="bar" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:attribute name="bar" type="xsd:string"/>
The concept of local vs global declarations is clear to me, but adds
dramatically to the burden of doing XSLT on top of XML Schema. Add the
possibility of substition to that (not to mention extension/restriction
which are horribly implemented if you compare them with subclassing or
inheritance in OO languages), and the transformation problem becomes
even worse.
And these examples only touch the basic features of the XML Schema
language.
On a more tricky level (element content defaulting, gleaned from a post
by Jeni Tennison on xml-dev):
Wrong (and impossible to create using the graphical view of XMLSpy):
<xsd:element name="foo" default="default">
<xsd:complexType mixed="true">
<xsd:sequence>
<xsd:element name="bar" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Right (impossible too, alas):
<xsd:element name="foo" default="default">
<xsd:complexType mixed="true">
<xsd:sequence>
<xsd:element name="bar" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Find the difference :-)
> > and in many chances not transferable/equivalently
> > interpreted between different tools.
>
> On what observations do you base this statement? After all,
> I have no really good idea what else beside a schema driven
> editor and a validator is going to use the schema, and both
> use it for validation, which is pretty much nailed down, no
> room for interpretation there.
You live with the assumption standards are correctly implemented by
tools, regardless of their complexity. If a standard (or better: the
application of a standard) can only live within a certain predefined set
of tools, it isn't much worth as a standard.
My problem with XML Schema is that it offers too many possible ways of
declaring the same kind of thing, and believe me, when you hand over
such a language to a creative user, he will make use of the exotic
features, too. And then, you can only hope your editor, validation
engine et al. will implement the same kind of 'standard', which is
currently not the case.
</Steven>
Re: draft howto dtd
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Steven Noels wrote:
> My main concerns with XML Schemas isn't based on its (quite insane set
> of) data types. It's the model behind it which tries to be too much for
> too many different people, and the syntax which is obfuscating at best.
You can do the same things a DTD can: describe what elements
can be children to elements, and what attributes an element
can have.
The equivalent of
<!ELEMENT document (title,sect1+)>
is
<xsd:element name="document">
<xsd:sequence>
<xsd:element name="title" type="title"/>
<xsd:element maxOccurs="unbounded" name="sect1" type="sect1"/>
</xsd:sequence>
</xsd:complexType>
It's not all that horrible. And if you don't want to look at it,
don't do it: write a style sheet to visualize the aspects you want.
By the time you need it, chances are that some other lazy guy has
already done this.
> and in many chances not transferable/equivalently
> interpreted between different tools.
On what observations do you base this statement? After all,
I have no really good idea what else beside a schema driven
editor and a validator is going to use the schema, and both
use it for validation, which is pretty much nailed down, no
room for interpretation there.
And the validation is also only used to assure that you are
not missing important stuff in your documents and that snippet
grabbers get their stuff at the place where they expect it.
We are not writing XML database optimizers taking advantage
of arcane complex restrictions on the data structure for
performance boost of two orders of magnitudes. We can worry
about this after Forrest is built on top of an XML database :-)
J.Pietschmann
RE: draft howto dtd
Posted by Steven Noels <st...@outerthought.org>.
> From: J.Pietschmann [mailto:j3322ptm@yahoo.de]
> Steven Noels wrote:
> > At best, XML Schemas are commonly considered to be primarly
> data- and
> > not document-focused. Furthermore, the spec is crap, and the
> > implementations are only able to make some sense of this crap.
>
> You don't have to use every feature XSchema allows. I basically
> use a subset roughly equivalent to DTD but with namespace support.
> The only primitive datatypes in my schemas are strings and dates.
My main concerns with XML Schemas isn't based on its (quite insane set
of) data types. It's the model behind it which tries to be too much for
too many different people, and the syntax which is obfuscating at best.
Let's be honest: the example you give in your other mail could be
possible, but you know the Schema syntax in which it will be encoded
will be horrible, and in many chances not transferable/equivalently
interpreted between different tools.
Just my ? 0.02
</Steven>
Re: draft howto dtd
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Steven Noels wrote:
> At best, XML Schemas are commonly considered to be primarly data- and
> not document-focused. Furthermore, the spec is crap, and the
> implementations are only able to make some sense of this crap.
You don't have to use every feature XSchema allows. I basically
use a subset roughly equivalent to DTD but with namespace support.
The only primitive datatypes in my schemas are strings and dates.
J.Pietschmann
RE: draft howto dtd
Posted by Steven Noels <st...@outerthought.org>.
Ivelin,
> Do you guys thing its time to switch the DTD to XML Schema ?
> Xalan supports XML Schema validation and I've used it in
> production for a
> while now.
At best, XML Schemas are commonly considered to be primarly data- and
not document-focused. Furthermore, the spec is crap, and the
implementations are only able to make some sense of this crap.
Sorry for being so frank, but after teaching some courses on XML
Schemas, I'm quite convinced it is a horribly bloated language.
Cheers,
</Steven>
Re: draft howto dtd
Posted by Ivelin Ivanov <iv...@apache.org>.
Do you guys thing its time to switch the DTD to XML Schema ?
Xalan supports XML Schema validation and I've used it in production for a
while now.
----- Original Message -----
From: "Diana Shannon" <te...@mac.com>
To: <fo...@xml.apache.org>
Sent: Thursday, May 16, 2002 7:37 AM
Subject: Re: draft howto dtd
> Steven,
>
> > 1) too few optional elements
> >
> > - overview, audience, purpose and prerequisites (or is it really
> > prerequesites?) should be optional, I guess...
>
> I don't understand. A howto should be more structured than your average
> document page. I consider those elements vital and user-friendly. They
> are only a few sentences. Why make them optional? It creates more work
> others.
>
> > - furthermore, I believe there will be confusion between
> > header>abstract, overview and purpose, especially if they all need to be
> > filled in
>
> Ok, I considered that too. However, abstract is optional in the document
> dtd, and I wanted it required. I wasn't sure how to override that. Any
> suggestions?
>
> > - reference to faqs elements, but not reusing the one defined in
> > faq-v11.dtd
> Good point. I'll add that.
>
> > 3) Obviously, I don't like the s2/title attributes... :-)
> >
> > This is a nice example of the tedious result of including a
> > hierarchy/nesting indication in an element name...
> >
> > I'd much prefer this:
> >
> > <!ELEMENT steps (section | %blocks;)+ >
> > <!ATTLIST steps %common.att;>
>
> Not all how-tos will fit perfectly into the step by step model. I had
> this originally, but I took it out.
>
> > On a related note: why provide title elems/attrs with the various parts
> > of your DTD... the meaning of the parts (and the title using which they
> > should be rendered) is pretty clear and perhaps is something which can
> > be automated using a stylesheet, I believe:
> >
> > <xsl:template match="steps">
> > <section>
> > <title>Steps</title>
> > <xsl:apply-templates/>
> > </section>
> > </xsl:template>
>
> I wasn't sure if I should allow readers to write their own section
> titles. Most how-tos do... My titles are too generic, and I don't really
> like that.
>
> >> 1. I think the header element contains a lot of useful
> >> cms-related info.
> >> Perhaps version can be used to imply status:
> >> draft/release/revision. I'm
> >> not sure of its precise meaning with code, but perhaps
> >> "draft" document
> >> versions could have a value less than 1, etc.
> >
> > We could provide use a list of possible attribute values for that, too -
> > so that not everybody starts to invent his own classification.
>
> Great.
>
> >> 5. Steve, I wonder if you're going to dislike the way I'm treating
> >> titles (as attributes) in each howto part. I just found it a little
> >> simpler to implement this way. Feel free to revise, in
> >> anticipation of
> >> your v11 work.
> >
> > That's Steven ;-)
>
> Ooops. Really sorry ;).
>
> > See above - will you update, or will I do? Decision to be made is
> > integration with the new doc-v11 or not.
>
> Let me try another pass, and then you can refine it as necessary. I'm
> still rather confused, v10 or v11? Please, I just don't want the doc-v11
> decision to delay the howto effort. I have put warnings on the how to
> write a how-to, etc. pages (which are based on v10), so potential
> authors are alerted that things will change.
>
> Diana
>
RE: draft howto dtd
Posted by Steven Noels <st...@outerthought.org>.
Diana,
> > 1) too few optional elements
> >
> > - overview, audience, purpose and prerequisites (or is it really
> > prerequesites?) should be optional, I guess...
>
> I don't understand. A howto should be more structured than
> your average
> document page. I consider those elements vital and
> user-friendly. They
> are only a few sentences. Why make them optional? It creates
> more work
> others.
Extra work to me seems like having a lot of similar elements which
*have* to be filled in before you can submit a how-to. I'm not saying
all of these should be made optional, I'l just saying that the barrier
for would-be document editors is quite high of you have a lot of
(similar) elements which have to be filled in. So OK for more structure,
i.e. providing useful elements for people who want to add these elements
to their how-to's - but not OK for making them required. If they are
made optional, others can come in afterwards to fill them in when
needed.
Look at your own remark 4) - it's the same discussion I guess... not?
> > - furthermore, I believe there will be confusion between
> > header>abstract, overview and purpose, especially if they
> all need to be
> > filled in
>
> Ok, I considered that too. However, abstract is optional in
> the document
> dtd, and I wanted it required. I wasn't sure how to override
> that. Any
> suggestions?
You can't :-|
(Well, technically, you can, but that would mean redeclaring the header
element inside the local declaration subset (i.e.: in the instance),
something which looks really hairy to XML-newbies:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-To V1.0//EN" "howto-v10.dtd"
[
<!ELEMENT header (title, subtitle?, version?, type?, authors,
notice*, abstract %local.headers;)>
<!ATTLIST header %common.att;>
]>
<howto>
...
</howto>
> > - reference to faqs elements, but not reusing the one defined in
> > faq-v11.dtd
> Good point. I'll add that.
Won't be simple since the faq.dtd already references the document.dtd,
too, so you would get duplicate element declarations, too. We'd better
split up the DTDs in two documents, i.e. one specifying the external
entity references needed, and one describing the DTD-specific content
model. I'll think of that and commit a better infrastructure when I
found a more maintainable solution.
> > 3) Obviously, I don't like the s2/title attributes... :-)
> >
> > This is a nice example of the tedious result of including a
> > hierarchy/nesting indication in an element name...
> >
> > I'd much prefer this:
> >
> > <!ELEMENT steps (section | %blocks;)+ >
> > <!ATTLIST steps %common.att;>
>
> Not all how-tos will fit perfectly into the step by step model. I had
> this originally, but I took it out.
OK for me, as long as we don't use <s2> inside that content model ;-)
> > On a related note: why provide title elems/attrs with the
> various parts
> > of your DTD... the meaning of the parts (and the title
> using which they
> > should be rendered) is pretty clear and perhaps is
> something which can
> > be automated using a stylesheet, I believe:
> >
> > <xsl:template match="steps">
> > <section>
> > <title>Steps</title>
> > <xsl:apply-templates/>
> > </section>
> > </xsl:template>
>
> I wasn't sure if I should allow readers to write their own section
> titles. Most how-tos do... My titles are too generic, and I
> don't really
> like that.
Hm. If you want your authors to be able to create their own titles for
specific sections, how will you prevent this:
<!ELEMENT prerequesites (%blocks;)* >
<!ATTLIST prerequesites %title.att; %common.att;>
<prerequesites title="Audience">
...
</prerequesites>
> >> 1. I think the header element contains a lot of useful
> >> cms-related info.
> >> Perhaps version can be used to imply status:
> >> draft/release/revision. I'm
> >> not sure of its precise meaning with code, but perhaps
> >> "draft" document
> >> versions could have a value less than 1, etc.
> >
> > We could provide use a list of possible attribute values
> for that, too -
> > so that not everybody starts to invent his own classification.
>
> Great.
Will do... suggestions?
> >> 5. Steve, I wonder if you're going to dislike the way I'm treating
> >> titles (as attributes) in each howto part. I just found it a little
> >> simpler to implement this way. Feel free to revise, in
> >> anticipation of
> >> your v11 work.
> >
> > That's Steven ;-)
>
> Ooops. Really sorry ;).
>
> > See above - will you update, or will I do? Decision to be made is
> > integration with the new doc-v11 or not.
>
> Let me try another pass, and then you can refine it as necessary. I'm
> still rather confused, v10 or v11? Please, I just don't want
> the doc-v11
> decision to delay the howto effort. I have put warnings on the how to
> write a how-to, etc. pages (which are based on v10), so potential
> authors are alerted that things will change.
OK - let's please swap files again so that we reach a consensus.
Thanks,
Diane ;-)
Re: draft howto dtd
Posted by Diana Shannon <te...@mac.com>.
Steven,
> 1) too few optional elements
>
> - overview, audience, purpose and prerequisites (or is it really
> prerequesites?) should be optional, I guess...
I don't understand. A howto should be more structured than your average
document page. I consider those elements vital and user-friendly. They
are only a few sentences. Why make them optional? It creates more work
others.
> - furthermore, I believe there will be confusion between
> header>abstract, overview and purpose, especially if they all need to be
> filled in
Ok, I considered that too. However, abstract is optional in the document
dtd, and I wanted it required. I wasn't sure how to override that. Any
suggestions?
> - reference to faqs elements, but not reusing the one defined in
> faq-v11.dtd
Good point. I'll add that.
> 3) Obviously, I don't like the s2/title attributes... :-)
>
> This is a nice example of the tedious result of including a
> hierarchy/nesting indication in an element name...
>
> I'd much prefer this:
>
> <!ELEMENT steps (section | %blocks;)+ >
> <!ATTLIST steps %common.att;>
Not all how-tos will fit perfectly into the step by step model. I had
this originally, but I took it out.
> On a related note: why provide title elems/attrs with the various parts
> of your DTD... the meaning of the parts (and the title using which they
> should be rendered) is pretty clear and perhaps is something which can
> be automated using a stylesheet, I believe:
>
> <xsl:template match="steps">
> <section>
> <title>Steps</title>
> <xsl:apply-templates/>
> </section>
> </xsl:template>
I wasn't sure if I should allow readers to write their own section
titles. Most how-tos do... My titles are too generic, and I don't really
like that.
>> 1. I think the header element contains a lot of useful
>> cms-related info.
>> Perhaps version can be used to imply status:
>> draft/release/revision. I'm
>> not sure of its precise meaning with code, but perhaps
>> "draft" document
>> versions could have a value less than 1, etc.
>
> We could provide use a list of possible attribute values for that, too -
> so that not everybody starts to invent his own classification.
Great.
>> 5. Steve, I wonder if you're going to dislike the way I'm treating
>> titles (as attributes) in each howto part. I just found it a little
>> simpler to implement this way. Feel free to revise, in
>> anticipation of
>> your v11 work.
>
> That's Steven ;-)
Ooops. Really sorry ;).
> See above - will you update, or will I do? Decision to be made is
> integration with the new doc-v11 or not.
Let me try another pass, and then you can refine it as necessary. I'm
still rather confused, v10 or v11? Please, I just don't want the doc-v11
decision to delay the howto effort. I have put warnings on the how to
write a how-to, etc. pages (which are based on v10), so potential
authors are alerted that things will change.
Diana
RE: draft howto dtd
Posted by Steven Noels <st...@outerthought.org>.
Diana,
quickly reviewing:
<!ELEMENT howto (header, overview, audience, purpose, prerequesites,
steps, extension, faqs?, tips?, references?, revisions? )>
1) too few optional elements
- overview, audience, purpose and prerequisites (or is it really
prerequesites?) should be optional, I guess...
- furthermore, I believe there will be confusion between
header>abstract, overview and purpose, especially if they all need to be
filled in
- reference to faqs elements, but not reusing the one defined in
faq-v11.dtd
2) the reference to the document-vxx.dtd should be done like this:
<!ENTITY % document PUBLIC
"-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
%document;
so that it gets picked up by the entity resolving mechanism. We have to
decide which version of the document-vxx.dtd this howto-dtd will be
using. Personally, I'd like to isolate DTD management to Forrest, and
having the latest & greatest (+ archived) versions of the DTD modules on
our website.
3) Obviously, I don't like the s2/title attributes... :-)
This is a nice example of the tedious result of including a
hierarchy/nesting indication in an element name...
I'd much prefer this:
<!ELEMENT steps (section | %blocks;)+ >
<!ATTLIST steps %common.att;>
On a related note: why provide title elems/attrs with the various parts
of your DTD... the meaning of the parts (and the title using which they
should be rendered) is pretty clear and perhaps is something which can
be automated using a stylesheet, I believe:
<xsl:template match="steps">
<section>
<title>Steps</title>
<xsl:apply-templates/>
</section>
</xsl:template>
Further comments below...
> -----Original Message-----
> From: Diana Shannon [mailto:terracare@mac.com]
> Sent: woensdag 15 mei 2002 20:25
> To: forrest-dev@xml.apache.org
> Subject: draft howto dtd
>
>
> Attached is a howto dtd draft, along with a sample doc to validate. A
> few notes.
>
> 1. I think the header element contains a lot of useful
> cms-related info.
> Perhaps version can be used to imply status:
> draft/release/revision. I'm
> not sure of its precise meaning with code, but perhaps
> "draft" document
> versions could have a value less than 1, etc.
We could provide use a list of possible attribute values for that, too -
so that not everybody starts to invent his own classification.
> 2. id attribute (via %common.att;) is defined for howto, so
> if CMS needs
> to manage docs via that attribute, we're still ok.
>
> 3. I declared one additional child element of header:
> last-modified-content-date. Its purpose is to provide meaning to the
> reader based on content changes, not mere structural changes,
> etc. I'm
> not sure if it duplicates revision history structure at the bottom.
I like that, and maybe we should make it a default for header...
> 4. I'm trying to take what is a liberal approach to what is
> allowed by
> the dtd. For example, I didn't use %content.mix; anywhere. I
> wanted to
> allow authors the chance to use lists for prerequesites, intended
> audience, etc. Perhaps some of you will consider this too loose.
>
> 5. Steve, I wonder if you're going to dislike the way I'm treating
> titles (as attributes) in each howto part. I just found it a little
> simpler to implement this way. Feel free to revise, in
> anticipation of
> your v11 work.
That's Steven ;-)
^
See above - will you update, or will I do? Decision to be made is
integration with the new doc-v11 or not.
> Anyway, please improve it. I'm certainly no expert.
> Snippets/tutorials
> dtds will be similarly structured, so I'll wait for comments before
> submitting those.
>
> Many thanks.
Obliged to do so. Just give a yell.
</Steven>