forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "J.Pietschmann" <>
Subject Re: DTD questions
Date Fri, 31 May 2002 21:56:41 GMT
"Steven Noels" <> wrote:
 > > > [generated anchors]
 > I don't like the Topic Maps approach - this is simply too much work for
 > people adopting Forrest for their project needs. I'm -1 on the generated
 > anchors, too, but what else can we do? We can't force specify people to
 > add an ID attribute on each section, just for creating a little TOC on
 > top of the generated document. We could use numbers instead of ID's
 > however, or the text of the section title.
 > Opinions?

Topic maps, explicitely specified anchors and generated anchors can
and likely will coexist.

Generated anchors mean the links *have* to be generated too. This is
fine for generating TOCs and index pages.

Explicitely specified ids are targets for manually inserted
links. Whether the links are directly placed into the xdocs or placed
in a topic map is of no concern for the id.

The topic map is used as a central repository for links which are used
often, and perhaps from different documents. In case the URL changes,
there is only one change instead of a global S&R. It does not prohibit
placing links directly into the xdocs (although I find hrefs to .html
a bit strange in xml files). Links can be migrated to and out of the
topic map at any time, perhaps supported by a tool.

Really easy in Cocoon: directory generator -> xslt pulling in all
xdocs via document and extract <link> -> xslt for sort+count hrefs ->
html formatter -> happy developer staring at a nice report -> check
boxes next to hrefs to migrate to the topic map -> action: stream edit
documents and topic map using xslt.

 > > > > [title]
 > > I also don't see the need for using markup in titles;
 > > personally I've never
 > > seen it used AFAIR.
 > Glad I finally found a partisan on this ;-)

If the title is an attribute, you'll never see markup there for
obvious reasons.

Although I don't want to start a flame war about attribute
vs. element, there is still the rule of thumb: if it's finally seen on
the screen/paper, it should be put in an element.

Of course, is it really necessary to put "FubarException" in a <code>
to mark it as such? There is no real pressure for doing so. Same for
<em>. And for <icon>. Nevertheless, it's not common practice to have
first-class content in an attribute. And it *will* get in the way if
the document DTDs grow more complex. One of the major points of XML is
to allow markup mixed with text. And can we be sure that there will
never be a need to distinguish
  <class project="foovalon">FubarException</class>
  <class project="foorrest">FubarException</class>
in titles for neat indexing?

As already noted, I'd like to have a <keyword> (or <index>) element
for indexing keywords in questions (don't mind if it's used for
indexing elsewhere). Questions are transformed to titles. I'm not
going to keep a separate keyword register for a <faq>, I'd like to
mark keywords inline, it's much easier to keep them maintained (should
be obvious).

 > My fault, I never knew about the faqsection - would you like this to be
 > brought back to live? I like part better, but that's personal.

Part is both generic and overloaded, and not generally associated with
either a FAQ nor with a document structure element at the same level
of a section (I'd associate it either with a logical structure above
chapter or physical structure above page, perhaps a set of "volumes".
Well there are novels using a logical structure of work->book->part
->chapter->section->... rather humongous novels of course)
Of course, faq:section would be even better than faqsection :-)

 > > > >   XSLT based tool ... would help with stylesheet maintenance.
 > That would be cool, indeed.

Gimme a schema... okokok I'll see how to get one myself.

General question: Would you (and anybody else) be comfortable with a
strategy to make a schema (likely a XSchema subset) the primary
structure definition language and generate DTD and whatever else from
them? It's not meant to drop DTDs tomorrow, I think of it as a long
term goal.

 > > > >     <xsl:template match="*" priority="-2">
 > > > >     <xsl:if test="$check-all">
 > > > >       <xsl:message terminate="yes">Unexpected
 > > element</xsl:message>
 > > > >     </xsl:if>
 > > > >     <xsl:apply-templates/>
 > > > >   </xsl:template>
 > > >
 > > > OK. I will add that in over the weekend.
 > >
 > > +1
 > -1 - this should be solved/degraded gracefully, and not breaking the
 > build!

That's what the $check parameter is for. I hope the build.xml can
arrange for different build targets, one including rigorous checks.

 > > Have it output also any useful info to where the tag is, and
 > > what it is.

Either use saxon:lineNumber() :-P or the XPath-from-context-element
generator from the XSL list archive. I'll try to dig it out over the


View raw message