You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by "J.Pietschmann" <j3...@yahoo.de> on 2002/05/29 21:56:01 UTC
DTD questions
Hi forresters,
I got some questions regarding the current DTDs:
- The document-v11 has link, jump and fork for expressing links.
The difference between the link and the jump element makes
only sense if frames are used. Do you expect the xdocs will be ever
used in a frames environment?
I believe the intention was:
link: project internal
jump: other apache projects
fork: non-apache ressources
I get the impression this has been muddled over time.
Clarifications?
- The stylesheet document2html has the following template:
<xsl:template match="jump">
<a href="{@href}#{@anchor}">
<xsl:apply-templates/>
</a>
</xsl:template>
Unfortunately, there is no @anchor attribute defined for jump in the
DTD. This makes validation a bit of a farce. Moreover, if no anchor
is specified in the source, an empty fragment specifier is generated.
I have the feeling this could be bad or even illegal, in any case it
looks as if someone has been sloppy. I'd suggest to add some checks:
<xsl:template match="jump">
<xsl:choose>
<xsl:when test="@anchor and not(contains(@href,'#'))">
<a href="{@href}#{@anchor}">
<xsl:apply-templates/>
</a>
</xsl:when>
<xsl:when test="@anchor and contains(@href,'#')">
<xsl:message terminate="yes">Cannot have a fragment
specifier in href if anchor is also given</xsl:message>
</xsl:when>
<xsl:when test="@href">
<a href="{@href}">
<xsl:apply-templates/>
</a>
</xsl:when>
<xsl:otherwise>
<xsl:message terminate="yes">Either href or ancor must
be specified</xsl:message>
</xsl:otherwise>
<xsl:choose>
</xsl:template>
So, how should the issue with @anchor be handled?
- In particular within a FAQ, how should a crosslink to another question be
handled? I used <jump anchor="svghangs"> and
<faq>
<anchor id="svghangs">
<question>...
Yes, the faq element can have an id, but the faq2document doesn't
handle it. There is already an anchor generated for links from the
question index, but it is generated from the position (bad for links
from the outside). Having two anchors doesn't hurt, but it's ugly.
And, of course, anchor is not allowed at the point shown by the DTD.
- Many elements have a title attribute, in particular sections,
including FAQ sections. This precludes using markup in titles, in
particular <code>, <em> and a yet to invent <keyword> element (for
indexing, an obviously interesting feature for FAQs). I'd suggest
deprecating the title attribute and introducing a title child
element. Whether DocBook is about to be reinvented or not is a
question I will not ask here.
- The FAQ DTD has a part element for structuring the FAQ. This sounds
rather artificial. What's wrong with faqsection?
<plug>
With namespaces and XSchema, FAQ specific elements could have their own
namespace. This allows faq:section elements.
</plug>
- There is still a template for the connect element.
<plug>
With XSchema, an XSLT based tool could perform some primitive checks
on the style sheet, it could warn if templates matching removed elements
are still there.
</plug>
- I'd also suggest to add a catch-all template to document2html in
order to avoid nasty surprises caused by unhandled elements:
<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>
- The document DTD has some hooks for augmenting certain element
content. In the FAQ DTD the faq.mod is included after the
document.mod. This makes it impossible to use the hooks from within
the faq.mod. Is it planned to use the hooks for something, and if
so, what are the guidelines for this? Should there be a separate
faq.local.mod for local definitions, or should the faq.mod use for
this?
Comments?
J.Pietschmann
Re: DTD/XSLT mods: link and jump
Posted by Stefano Mazzocchi <st...@apache.org>.
David Crossley wrote:
>
> Here is my summary of the current situation with the
> link and jump and fork elements, of various discussion
> on the forrest-dev list, and of any outstanding issues.
> I am not saying that i know anything about this, rather
> trying to summarise it to keep the decision process moving.
>
> ----------------------------------------------------
> Current situation
> -----------------
> http://www.krysalis.org/forrest/document-v11.html
> demonstrates the behaviour. Here is just the text ...
> ----
> <link href="faq.html">
> Use this to *link* to another document. As per normal, this
> will open the new document in the same browser window.
>
> <link href="#section">
> Use this to *link* to the named anchor in the current document.
>
> <link href="contrib.html#cvshowto">
> Use this to *link* to another document and go to the named anchor.
> This will open the new document in the same browser window.
>
> <jump href="contrib.html">
> Use this to *jump* to another document and optionally go to a
> <jump href="contrib.html#cvshowto">
> named *anchor* within that document. This will open the new
> document in the same browser window. So what is the difference
> between link and jump? The jump behaves differently, in that
> it will replace any frames in the current window.
> This is the equivalent of <a ... target="_top">
>
> <fork href="faq.html">
> Use this to *fork* your webbrowser to another document. This
> will open the document in a new, unnamed browser window.
> This is the equivalent of <a ... target="_blank">
> ----
>
> I gather that the reason for having separate elements,
> rather than just the link element, was to implement the
> behaviour using a stylesheet to add target="_top|_blank".
>
> Another reason may have been to provide high-level tags
> so that authors could directly use the various link-type
> behaviours.
>
> ----------------------------------------------------
> Summary of forrest-dev discussion
> ---------------------------------
> <quote who="Nicola Ken Barozzi" ref="1">
> As the use of the old DTD showed us, link clones are
> at best confusing, and not well understood. This happens
> because we have different tags with the same meaning,
> but different behaviour.
> </quote>
>
> The discussion seemed to point to having only one element
> ... <link> ... with various attributes.
>
> The consensus was to not have an "anchor" attribute,
> but rather use the conventional # in the href.
>
> So ...
>
> <link href="..."
> [external="true|false"]
> [target="..."]
> [role="..."]
> [title="..."]
> />
>
> where ...
> href = the URL, which may include an optional named anchor using #
> external = define whether it is out-of-context (default false)
> target = named window or frame, e.g. _blank or _top
> role = (already in DTD, what is its purpose?)
> title = (already in DTD, what is its purpose?)
>
> ----------------------------------------------------
> Other issues
> ------------
> * The demo document-v11.html needs to provide clear examples
> and guidance about what situations the various possible
> link attributes should be used. [3]
>
> * There are some other link attributes that were in the
> document-v10.dtd which are dropped from document-v11.dtd
> These were to do with XLink. Was this drop intentional?
>
> * I became a little rushed towards the end of this summary.
> The discussion was in various threads, and i started to get
> lost.
As the original author of the Document DTD, I think I need to finally
take some time and jump in this discussion.
At some point, the idea was to use XLink. Unfortunately, XLink is
complex, heavy, hard-core namespace oriented (which is generally a good
thing, but since we still use DTDs, this is a real PITA)
For this reason, I decided to "extend" the hyperlink notion of HTML into
a more semantically meaningful markup. I identified three different
behaviors, each became a different tag
- link -> replaces the view containing the link with the linked
resource
- jump -> replaces the entire viewport with the linked resource
- fork -> creates another viewport with the linked resource
all these identify a 'starting point' of an hyperlink action.
Then, noting that the presence of the A/@name and A/@href change the
meaning of the element itself, I identified this as a markup design
mistake. This lead me to conclude that I needed a different element for
the 'ending point' of a hyperlink action. I identified only one:
- anchor -> identifies an intra-document ending point (every URI has an
implicit empty anchor at the beginning of itself)
At some point, I came up with the notion of 'soft linking' and 'hard
linking'. This is the reason why there is the 'role' attribute.
Currently is not used. But, for example, it could be used to identify a
different "way" to interpret the link itself (for example, allowing
link-map resolutions, etc.)
[the 'title' attribute is useful for tooltips and visual onmouseover
helps]
- o -
This said, after some thinking, I'm willing to reconsider those three
different link starting points because they mix concerns: the document
author doesn't know, nor should, if the hyperlink will be executed in a
fragmented viewport or if it makes sense to clear up the viewport (think
about navigation provided by frames).
The same could be said for forking the viewport. It is *not* the author
concern to determine *how* a particular hyperlink 'type' must be
translated in the appropriate hyperlinking behavior.
So, for this reason, one solution could be to flat out the hyperlink
elements to
<link href="..."
[type="..."]
[role="..."]
[title="..."]
/>
and
<anchor name="..."/>
One for the starting point, one for the end point.
At this point, the 'contract' is moved over to the definitions of
'roles' and 'types'.
Note that both are required because they are independent, for example
<link href="urn:apache-home-page"
type="external"
role="linkmap"/>
or
<link href="http://www.apache.org/"
type="external"
role="as-is"/>
NOTE: the type and role names are just an example, I'm not proposing to
use those.
Or, we can decide to make everything implicit and have Forrest associate
the linking behavior based on the URI only.
So,
<link href="urn:linkmap:apache-home-page"/>
<link href="http://www.apache.org"/>
<link href="index.html"/>
<link href="#welcome"/>
the only problem with this approach is that the document author lacks
the ability to indicate that a particular link must 'fork' the viewport.
But this might not be a problem since usability guidelines state
normally against forking the viewport in any circumstance.
What do you think?
--
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: DTD/XSLT mods: link and jump
Posted by David Crossley <cr...@indexgeo.com.au>.
Here is my summary of the current situation with the
link and jump and fork elements, of various discussion
on the forrest-dev list, and of any outstanding issues.
I am not saying that i know anything about this, rather
trying to summarise it to keep the decision process moving.
----------------------------------------------------
Current situation
-----------------
http://www.krysalis.org/forrest/document-v11.html
demonstrates the behaviour. Here is just the text ...
----
<link href="faq.html">
Use this to *link* to another document. As per normal, this
will open the new document in the same browser window.
<link href="#section">
Use this to *link* to the named anchor in the current document.
<link href="contrib.html#cvshowto">
Use this to *link* to another document and go to the named anchor.
This will open the new document in the same browser window.
<jump href="contrib.html">
Use this to *jump* to another document and optionally go to a
<jump href="contrib.html#cvshowto">
named *anchor* within that document. This will open the new
document in the same browser window. So what is the difference
between link and jump? The jump behaves differently, in that
it will replace any frames in the current window.
This is the equivalent of <a ... target="_top">
<fork href="faq.html">
Use this to *fork* your webbrowser to another document. This
will open the document in a new, unnamed browser window.
This is the equivalent of <a ... target="_blank">
----
I gather that the reason for having separate elements,
rather than just the link element, was to implement the
behaviour using a stylesheet to add target="_top|_blank".
Another reason may have been to provide high-level tags
so that authors could directly use the various link-type
behaviours.
----------------------------------------------------
Summary of forrest-dev discussion
---------------------------------
<quote who="Nicola Ken Barozzi" ref="1">
As the use of the old DTD showed us, link clones are
at best confusing, and not well understood. This happens
because we have different tags with the same meaning,
but different behaviour.
</quote>
The discussion seemed to point to having only one element
... <link> ... with various attributes.
The consensus was to not have an "anchor" attribute,
but rather use the conventional # in the href.
So ...
<link href="..."
[external="true|false"]
[target="..."]
[role="..."]
[title="..."]
/>
where ...
href = the URL, which may include an optional named anchor using #
external = define whether it is out-of-context (default false)
target = named window or frame, e.g. _blank or _top
role = (already in DTD, what is its purpose?)
title = (already in DTD, what is its purpose?)
----------------------------------------------------
Other issues
------------
* The demo document-v11.html needs to provide clear examples
and guidance about what situations the various possible
link attributes should be used. [3]
* There are some other link attributes that were in the
document-v10.dtd which are dropped from document-v11.dtd
These were to do with XLink. Was this drop intentional?
* I became a little rushed towards the end of this summary.
The discussion was in various threads, and i started to get
lost.
-------------
References:
[1] http://marc.theaimsgroup.com/?l=forrest-dev&m=102205960400385
[2] http://marc.theaimsgroup.com/?l=forrest-dev&m=102205550129667
[3] http://marc.theaimsgroup.com/?l=forrest-dev&m=102313254519092
Re: DTD/XSLT mods: link and jump (Was: DTD questions)
Posted by "J.Pietschmann" <j3...@yahoo.de>.
David Crossley wrote:
> This has only been a minor tidy up (there are
> broader issues still). I have clarified the current
> intention of jump and link at
> build/xml-forrest/docs/document-v11.html
> http://www.krysalis.org/forrest/document-v11.html
The @anchor attribute for <jump>is no longer explicitely
mentioned. Does this mean it's gone?
> Finally i figured out the difference between jump/link:
> ----
> The jump behaves differently, in that it will replace
> any frames in the current window. This is the equivalent
> of <a ... target="_top">
That's what made me to assume that
link: link within the same project: navigation panels of the
frame set stay the same, content window is replaced.
jump: jump to another apache project: content and navigation
panels are replaced
fork: fork a new window with content from somewhere else,
usually a non-apache ressource (but possibly also a help
window, or a search form)
These appear to be common designs, supposed you use frames,
and the apache projects use a common look&feel, in particular
similar frame sets and navigation panels (neither of which
is all that true currently)
The page mentioned above plainly states what the <link>,
<jump> and <fork> will likely do in the final HTML.
It would be interesting to actually have a guideline when to
use what. This is especially important because in the absence
of frames there is no difference between the HTML behaviour
of <link> and <jump>, so it's anybodies guess what to do.
If guessed wrong, this will strike back later, for example
if a PDF file is generated from the projects xdocs, a <link>
will become an internal link, while <jump> and <fork>
probably will become external links.
For really big projects like Cocoon, use subproject instead
of project. I guess a single PDF containing the full Cocoon
docs will be a bit oversized.
J.Pietschmann
DTD/XSLT mods: link and jump (Was: DTD questions)
Posted by David Crossley <cr...@indexgeo.com.au>.
I have waded through various previous discussion
on this list and made some minor adjustments to the
document-v10.dtd (only a comment tweak) and the
bert and forrest-site document2html stylesheets.
This has only been a minor tidy up (there are
broader issues still). I have clarified the current
intention of jump and link at
build/xml-forrest/docs/document-v11.html
http://www.krysalis.org/forrest/document-v11.html
Finally i figured out the difference between jump/link:
----
The jump behaves differently, in that it will replace
any frames in the current window. This is the equivalent
of <a ... target="_top">
----
I will try to summarise the past discussion in a separate
posting. We talked a lot about the link element over the
last few months. However, there was no consensus reached.
--David
Re: DTD questions
Posted by David Crossley <cr...@indexgeo.com.au>.
J.Pietschmann wrote:
> David Crossley wrote:
> <snip/>
> http://www.krysalis.org/forrest/document-v11.html
> BTW there are some text FIXMEs there, followed by a nice
> boxed <fixme> only a few lines later... :-)
> <fun>
> <p>(FIXME: Use <fixme> instead of FIXME)</p>
> <fixme>Should have used <fixme> for the above</fixme>
> </fun>
I had to do that for two reasons ...
That particular document is intended as a demonstration
of the available elements and using <fixme> would confuse that.
The document-v11.dtd has <fixme> as a block element. Therefore
it is not allowed inside <dd> or <li> or even <p>
Obviously there is a need for an inline-fixme element too.
--David
Re: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
David Crossley <cr...@indexgeo.com.au> wrote:
> > [link vs jump]
> I have been confused over these for ages. Steven, and then i,
> tried to demonstrate the differences in the Forrest demo
> document-v11.html ... Rather than try to express the differences
> here, please look at the demo document.
> http://www.krysalis.org/forrest/document-v11.html
Crashed my NS 4.74 :-(
> Your ideas about their use are somewhat different,
> but not orthogonal.
I cannot see much of a difference in the descriptions for
<link href="contrib.html#cvshowto">
and
<jump href="contrib.html" anchor="cvshowto">
Furthermore, it's hard to see why <jump> uses href+anchor
while <link> sticks both together into @href. I just can't see
what advantage splitting the base URL and the fragment identifier
into two attributes has. The disadvantage is quite obvious (the
huge <jump> processing template I posted, alternatively frequent
validation against the proper DTD).
Proposal: discard @anchor completely. Simply remove it from the
style sheet rather than reintroduce it into the DTD.
BTW there are some text FIXMEs there, followed by a nice
boxed <fixme> only a few lines later... :-)
<fun>
<p>(FIXME: Use <fixme> instead of FIXME)</p>
<fixme>Should have used <fixme> for the above</fixme>
</fun>
> We should perhaps implement
> your abovementioned validation routine via stylesheet until we
> get thorough XML validation happening.
Hmm. I'm for two years in the XML+XSLT business, and believe me,
keeping DTDs up to date in a distributed environment is a nightmare.
Apart from this, neither DTD nor any schema language I examined so
far can really handle all constraints. I finally took the following
approach:
1. Put incoming documents in an "incoming" directory. They are already
visible through the webserver for QA.
2. Validate the incoming docs against a somewhat general DTD. This
ensures the next step wont blow completely and weeds out the worst
problems (introduced by guys making "just a simple last minute fix"
with a text editor). Move the validated docs to a "pre-production"
tree.
3. Run a XSL transformation which checks the details and produces an
error report. In particular, check complicated cross dependencies
(if this is 'a', that should contain a <foo>), dead links across a
set of documents (mostly because of misspellings), names that have
to be unique across the set of documents and constraints for text
values like URL formats. Empty result -> ok. This is time consuming
and only run every once a while.
Nice property of the error report: It is XML like everything else
and can easily be viewed through the webserver with a browser.
4. Optional: Run another XSL transformation which inserts defaults for
optional stuff and kills the DTD reference. Improves performance
for documents where the DTD is larger and more complicated than the
document itself.
Generate system wide index files and some aggregated content at this
point too.
5. Move the checked docs into the "production" tree.
> Is the <connect> element still relevant?
I don't think so. It's been dropped from the DTD, and only
lurks in the style sheet. I propose to delete the template.
> > [DTD hooks]
> I am a bit lost on that - perhaps someone else can answer.
These are the customisation hooks, as seen in other large DTDs.
Example
<!ENTITY % localblock "">
<!ENTITY % block "(para|this-stuff|other-stuff %localblock;">
This allows other people to customise their DTD without editing
the .mod files:
<!-- override localblock -->
<!ENTITY % localblock "|custom-block">
%document.mod;
The customised DTD now allows
<section>
<para>A custom block:</para>
<custom-block/>
</section>
Note that this mechanism allows easy customisation but somewhat runs
counter to modularisation, because the parameter entities providing
the hooks have to be overridden before they get their empty default,
and there is only one chance to override it. If the FAQ DTD
introduces a FAQ-specific block element, there is no easy way to have
a HOWTO DTD which uses the faq.mod introducing its own specific block
element while keeping the faq specific block. Life sucks. As you
apparently are knowledgable with Relax NG, is there a way to solve
this problem there? I have some ideas how to tackle it using XSchema,
but it's not yet really satisfactory. Of course, this begs the
question: is there a problem that *needs* to be solved? The hooks seem
to be a bit - ahem - underutilised...
J.Pietschmann
Re: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Diana Shannon wrote:
>> Some
>> of the external stuff are HOWTOs, others are a new Understanding-stuff
>> series.
>
>
> Can you describe what this is? A guide? A set of topics?
A short article illustrating some commonly misunderstood,
abused or otherwise unclear aspects of a certain entity
or topic. May contain a bunch of one/two-line Micro-Howtos.
Example: Understanding URL:
"URLs are used for ... in <whatever>
The formal Syntax is in RFC NNNN
There are relative and absolute URLs...
A proper absolute file URL is...
A proper relative URL is...
There is no relative file URL per se...
The following are not URLs ..."
As for Micro-Howtos, the "Understanding Java Command line"
includes "Howto increase Memory" explaining memory settings
in lay terms etc.
J.Pietschmann
Re: DTD questions
Posted by Diana Shannon <te...@mac.com>.
On Monday, June 3, 2002, at 03:42 PM, J.Pietschmann wrote:
>> I'm trying to organize Cocoon FAQs into sections, and it's next to
>> impossible. Many Cocoon FAQs clearly belong in multiple sections.
>> Perhaps that's somewhat unique to Cocoon being a glue technology.
>> Instead of sections (although it's ok for now), I think it's better to
>> have something like a topic map decide relevant FAQs for a given
>> category/topic.
>
> I had this problem too. I finally settled to putting a one-liner and
> a link to an external description into every section, because most of
> the problems in need to be put into several categories warrant not
> only a description of a solution but also some background info.
Agreed. So a common FAQ topic (i.e. short amount of content, not enough
for a complete How-To) links where?
> Some
> of the external stuff are HOWTOs, others are a new Understanding-stuff
> series.
Can you describe what this is? A guide? A set of topics?
Diana
Re: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
> I'm trying to organize Cocoon FAQs into sections, and it's next to
> impossible. Many Cocoon FAQs clearly belong in multiple sections.
> Perhaps that's somewhat unique to Cocoon being a glue technology.
> Instead of sections (although it's ok for now), I think it's better to
> have something like a topic map decide relevant FAQs for a given
> category/topic.
I had this problem too. I finally settled to putting a one-liner and
a link to an external description into every section, because most of
the problems in need to be put into several categories warrant not
only a description of a solution but also some background info. Some
of the external stuff are HOWTOs, others are a new Understanding-stuff
series.
So far I have
- HOWTO track down and isolate problems
- HOWTO report bugs (abundant FOP specific hints)
- Understanding URLs
- Understanding URL resolving
- Understanding Java command line (classpath, memory settings)
Probably more to come.
> What I think we *do* need, for lots of document content types, is some
> way of indicating the source code/components and even version upon which
> they depend. Then, when something about that code/component changes,
> such content (FAQs, tutorials, how-tos, etc.) can be found and edited
> easily. When those inevitable delays occur, such docs could at least
> display warnings about being out-of-date/alpha etc. XSLT could include
> such flags (comparing doc version to release version) until the content
> is updated to reflect the current software status.
Interesting. I'll try to digest this.
J.Pietschmann
Re: DTD questions
Posted by Diana Shannon <te...@mac.com>.
On Friday, May 31, 2002, at 05:56 PM, J.Pietschmann wrote:
> From: "J.Pietschmann" <j3...@yahoo.de>
> Date: Fri May 31, 2002 05:56:41 PM US/Eastern
> To: forrest-dev@xml.apache.org
> Subject: Re: DTD questions
> Reply-To: forrest-dev@xml.apache.org
>
> "Steven Noels" <st...@outerthought.org> 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.
Please make it an element. What the simple need, conservatively applied,
to include <br /> for
some titles?
> > 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 :-)
I'm trying to organize Cocoon FAQs into sections, and it's next to
impossible. Many Cocoon FAQs clearly belong in multiple sections.
Perhaps that's somewhat unique to Cocoon being a glue technology.
Instead of sections (although it's ok for now), I think it's better to
have something like a topic map decide relevant FAQs for a given
category/topic.
What I think we *do* need, for lots of document content types, is some
way of indicating the source code/components and even version upon which
they depend. Then, when something about that code/component changes,
such content (FAQs, tutorials, how-tos, etc.) can be found and edited
easily. When those inevitable delays occur, such docs could at least
display warnings about being out-of-date/alpha etc. XSLT could include
such flags (comparing doc version to release version) until the content
is updated to reflect the current software status.
Have you seen this anywhere?
Diana
RE: DTD questions
Posted by Steven Noels <st...@outerthought.org>.
> From: J.Pietschmann [mailto:j3322ptm@yahoo.de]
> 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.
Most of this will be possible using libre, our book.xml nuker, which is
wrapped as a Cocoon generator. I'm readying it for commit these days,
expect to see it by the end of next week (really!)
</Steven>
Re: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
"Steven Noels" <st...@outerthought.org> 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>
from
<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
weekend.
J.Pietschmann
RE: DTD questions
Posted by Steven Noels <st...@outerthought.org>.
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> > J.Pietschmann wrote:
<snip/>
> What about the discussion we had about having only *one* link tag?
> http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-de
> v@xml.apache.o
> rg&msgId=339180
> http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-de
> v@xml.apache.o
> rg&msgId=339459
> http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-de
> v@xml.apache.o
> rg&msgNo=252
+1
<snip/>
> Which brings us back to the naming of the dtds.
> I *really* want to see the current DTD labelled as dev
> somehow, to prevent
> this (at least in part).
I'll see what I can do, you're right about this.
> > I would prefer to see proper XML validation via RELAX NG
> > happening. Then the stylesheets can rely on the XML stream
> > and be less verbose.
>
> http://www.xmlhack.com/read.php?item=1667
-1, I don't see how we can constrain this using DTD's, RELAXNG or
XSchema in a useful way. And people following XML-Dev (Joerg) already
know that while RNG is a Draft ISO spec, one of its authors doesn't mind
admitting publicly that marketing RNG has failed - so I won't assume
lots of tools doing RNG validation. I'm -1 on maintaining 2 grammars
independently of each other - but I know James Clark has an RNG2DTD
converter, need to check that however. But how will we integrate this
within the Cocoon environment? Xerces doesn't do any RNG validation
AFAIK - and validation should be an integral part of the process.
> > I too am not happy with generated anchors - they are always
> > changing, so you cannot link from another document to a specific
> > FAQ. I was pleased to see your recent Topic Map thread, and will
> > try to comment there.
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?
> > > - Many elements have a title attribute, in particular sections,
> > > including FAQ sections. This precludes using markup in
> titles, in
> > > particular <code>, <em> and a yet to invent <keyword>
> element (for
> > > indexing, an obviously interesting feature for FAQs).
> I'd suggest
> > > deprecating the title attribute and introducing a title child
> > > element. Whether DocBook is about to be reinvented or not is a
> > > question I will not ask here.
> >
> > You provide very sound reasons. There was some discussion
> > on forrest-dev around February - i cannot find it quickly.
>
> I find it harder to write stylesheets for the docbook way.
> 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 ;-)
> > > - The FAQ DTD has a part element for structuring the FAQ.
> This sounds
> > > rather artificial. What's wrong with faqsection?
> >
> > Mmmm .. Not sure happened with that. The Cocoon-1/faq.dtd
> > had faqsection. Then Cocoon-2/faq.dtd dropped it (perhaps
> > accidently). Then Forrest/faq.dtd brings it back differently.
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.
> > > <plug>
> > > With namespaces and XSchema, FAQ specific elements
> could have their
> own
> > > namespace. This allows faq:section elements.
> > > </plug>
> > >
> > > - There is still a template for the connect element.
> >
> > Is the <connect> element still relevant? There is still
> > confusion over the purpose of link|jump|connect and differences
> > between DTD v10 and v11 in this area. Does anyone know what
> > the <connect> is/was used for? Is it safe to drop it in DTD v11?
>
> 1 link tag... pleeeease ;-)
Let's vote on this.
> > I did a UNIX find/grep through Cocoon and Forrest xdocs and it
> > is not used anywhere. (There was one unlinked C2 doc at
> > xdocs/css/testdoc.xml that looks useful. It too has a message
> > "FIXME: what is this 'connect' thing for".)
>
> wireless? ;-P
LOL.
> > > <plug>
> > > With XSchema, an XSLT based tool could perform some
> primitive checks
> > > on the style sheet, it could warn if templates matching removed
> elements
> > > are still there.
> > > </plug>
> >
> > Great idea. That would help with stylesheet maintenance.
>
> +10
That would be cool, indeed.
> > > - I'd also suggest to add a catch-all template to document2html in
> > > order to avoid nasty surprises caused by unhandled elements:
> > >
> > > <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!
> Have it output also any useful info to where the tag is, and
> what it is.
>
> > If you have patches for anything else then please send them
> > via forrest-dev list.
> > > - The document DTD has some hooks for augmenting certain element
> > > content. In the FAQ DTD the faq.mod is included after the
> > > document.mod. This makes it impossible to use the
> hooks from within
> > > the faq.mod. Is it planned to use the hooks for
> something, and if
> > > so, what are the guidelines for this? Should there be
> a separate
> > > faq.local.mod for local definitions, or should the
> faq.mod use for
> > > this?
> >
> > I am a bit lost on that - perhaps someone else can answer.
>
> Ahem... anyone else? ;-)
I know, and Joerg has a point. The remodularization was a quick hack by
me. Doing this local stuff however will be hard to reflect in the
stylesheets, too. We need the modular structure, I'm not sure whether we
need all this local definition placeholders.
</Steven>
Re: DTD questions
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "David Crossley" <cr...@indexgeo.com.au>
> J.Pietschmann wrote:
> > Hi forresters,
> > I got some questions regarding the current DTDs:
> >
> > - The document-v11 has link, jump and fork for expressing links.
> > The difference between the link and the jump element makes
> > only sense if frames are used. Do you expect the xdocs will be ever
> > used in a frames environment?
>
> I sure hope not - frames yuk.
I disagree.
Frames make it easy to bring down the load on the server, by keeping common
components on the client.
In webapps, like the one we are doing at work for supply chain management
(www.intexti.it), it made the whole system faster and gives the user a much
better sensation.
Would you like it is your native program window needed repainting and
flickered at every action you do?
> However, the DTD needs
> to be general enough to be used in various situations.
+100
> > I believe the intention was:
> > link: project internal
> > jump: other apache projects
> > fork: non-apache ressources
> > I get the impression this has been muddled over time.
> > Clarifications?
>
> I have been confused over these for ages. Steven, and then i,
> tried to demonstrate the differences in the Forrest demo
> document-v11.html ... Rather than try to express the differences
> here, please look at the demo document.
> http://www.krysalis.org/forrest/document-v11.html
>
> Your ideas about their use are somewhat different,
> but not orthogonal.
>
> I will edit that document over the weekend to bring in
> some of the clarifications that you have provided.
What about the discussion we had about having only *one* link tag?
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgId=339180
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgId=339459
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgNo=252
> > - The stylesheet document2html has the following template:
> > <xsl:template match="jump">
> > <a href="{@href}#{@anchor}">
> > <xsl:apply-templates/>
> > </a>
> > </xsl:template>
> >
> > Unfortunately, there is no @anchor attribute defined for jump in the
> > DTD. This makes validation a bit of a farce.
>
> The anchor attribute for jump was in the document-v10 DTD.
> It was somehow missed when the document-v11 started to happen.
>
> This makes me concerned that other things are also inconsistent
> in the DTD. In the Cocoon project i saw some inconsistencies
> with DTDs too. It seems that the faq-v10.dtd took a backwards
> step between C1=>C2 ... perhaps an old copy was used.
Which brings us back to the naming of the dtds.
I *really* want to see the current DTD labelled as dev somehow, to prevent
this (at least in part).
> > Moreover, if no anchor
> > is specified in the source, an empty fragment specifier is generated.
> > I have the feeling this could be bad or even illegal, in any case it
> > looks as if someone has been sloppy. I'd suggest to add some checks:
>
> I would prefer to see proper XML validation via RELAX NG
> happening. Then the stylesheets can rely on the XML stream
> and be less verbose.
http://www.xmlhack.com/read.php?item=1667
> Of course, your solution addresses the current need, so is good.
+1
> > <xsl:template match="jump">
> > <xsl:choose>
> > <xsl:when test="@anchor and not(contains(@href,'#'))">
> > <a href="{@href}#{@anchor}">
> > <xsl:apply-templates/>
> > </a>
> > </xsl:when>
> > <xsl:when test="@anchor and contains(@href,'#')">
> > <xsl:message terminate="yes">Cannot have a fragment
> > specifier in href if anchor is also given</xsl:message>
> > </xsl:when>
> > <xsl:when test="@href">
> > <a href="{@href}">
> > <xsl:apply-templates/>
> > </a>
> > </xsl:when>
> > <xsl:otherwise>
> > <xsl:message terminate="yes">Either href or anchor must
> > be specified</xsl:message>
> > </xsl:otherwise>
> > <xsl:choose>
> > </xsl:template>
> >
> > So, how should the issue with @anchor be handled?
>
> First of all get it back into the DTD and jump/anchor handling
> back into all of the stylesheets. We should perhaps implement
> your abovementioned validation routine via stylesheet until we
> get thorough XML validation happening.
And get the validation target in the Ant build working correctly <hint hint>
> > - In particular within a FAQ, how should a crosslink to another question
be
> > handled? I used <jump anchor="svghangs"> and
> > <faq>
> > <anchor id="svghangs">
> > <question>...
> > Yes, the faq element can have an id, but the faq2document doesn't
> > handle it. There is already an anchor generated for links from the
> > question index, but it is generated from the position (bad for links
> > from the outside). Having two anchors doesn't hurt, but it's ugly.
> > And, of course, anchor is not allowed at the point shown by the DTD.
>
> I too am not happy with generated anchors - they are always
> changing, so you cannot link from another document to a specific
> FAQ. I was pleased to see your recent Topic Map thread, and will
> try to comment there.
+1
> > - Many elements have a title attribute, in particular sections,
> > including FAQ sections. This precludes using markup in titles, in
> > particular <code>, <em> and a yet to invent <keyword> element (for
> > indexing, an obviously interesting feature for FAQs). I'd suggest
> > deprecating the title attribute and introducing a title child
> > element. Whether DocBook is about to be reinvented or not is a
> > question I will not ask here.
>
> You provide very sound reasons. There was some discussion
> on forrest-dev around February - i cannot find it quickly.
I find it harder to write stylesheets for the docbook way.
I also don't see the need for using markup in titles; personally I've never
seen it used AFAIR.
> > - The FAQ DTD has a part element for structuring the FAQ. This sounds
> > rather artificial. What's wrong with faqsection?
>
> Mmmm .. Not sure happened with that. The Cocoon-1/faq.dtd
> had faqsection. Then Cocoon-2/faq.dtd dropped it (perhaps
> accidently). Then Forrest/faq.dtd brings it back differently.
>
> > <plug>
> > With namespaces and XSchema, FAQ specific elements could have their
own
> > namespace. This allows faq:section elements.
> > </plug>
> >
> > - There is still a template for the connect element.
>
> Is the <connect> element still relevant? There is still
> confusion over the purpose of link|jump|connect and differences
> between DTD v10 and v11 in this area. Does anyone know what
> the <connect> is/was used for? Is it safe to drop it in DTD v11?
1 link tag... pleeeease ;-)
> I did a UNIX find/grep through Cocoon and Forrest xdocs and it
> is not used anywhere. (There was one unlinked C2 doc at
> xdocs/css/testdoc.xml that looks useful. It too has a message
> "FIXME: what is this 'connect' thing for".)
wireless? ;-P
> > <plug>
> > With XSchema, an XSLT based tool could perform some primitive checks
> > on the style sheet, it could warn if templates matching removed
elements
> > are still there.
> > </plug>
>
> Great idea. That would help with stylesheet maintenance.
+10
> > - I'd also suggest to add a catch-all template to document2html in
> > order to avoid nasty surprises caused by unhandled elements:
> >
> > <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
Have it output also any useful info to where the tag is, and what it is.
> If you have patches for anything else then please send them
> via forrest-dev list.
>
> > - The document DTD has some hooks for augmenting certain element
> > content. In the FAQ DTD the faq.mod is included after the
> > document.mod. This makes it impossible to use the hooks from within
> > the faq.mod. Is it planned to use the hooks for something, and if
> > so, what are the guidelines for this? Should there be a separate
> > faq.local.mod for local definitions, or should the faq.mod use for
> > this?
>
> I am a bit lost on that - perhaps someone else can answer.
Ahem... anyone else? ;-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: DTD questions
Posted by David Crossley <cr...@indexgeo.com.au>.
J.Pietschmann wrote:
> Hi forresters,
> I got some questions regarding the current DTDs:
>
> - The document-v11 has link, jump and fork for expressing links.
> The difference between the link and the jump element makes
> only sense if frames are used. Do you expect the xdocs will be ever
> used in a frames environment?
I sure hope not - frames yuk. However, the DTD needs
to be general enough to be used in various situations.
> I believe the intention was:
> link: project internal
> jump: other apache projects
> fork: non-apache ressources
> I get the impression this has been muddled over time.
> Clarifications?
I have been confused over these for ages. Steven, and then i,
tried to demonstrate the differences in the Forrest demo
document-v11.html ... Rather than try to express the differences
here, please look at the demo document.
http://www.krysalis.org/forrest/document-v11.html
Your ideas about their use are somewhat different,
but not orthogonal.
I will edit that document over the weekend to bring in
some of the clarifications that you have provided.
> - The stylesheet document2html has the following template:
> <xsl:template match="jump">
> <a href="{@href}#{@anchor}">
> <xsl:apply-templates/>
> </a>
> </xsl:template>
>
> Unfortunately, there is no @anchor attribute defined for jump in the
> DTD. This makes validation a bit of a farce.
The anchor attribute for jump was in the document-v10 DTD.
It was somehow missed when the document-v11 started to happen.
This makes me concerned that other things are also inconsistent
in the DTD. In the Cocoon project i saw some inconsistencies
with DTDs too. It seems that the faq-v10.dtd took a backwards
step between C1=>C2 ... perhaps an old copy was used.
> Moreover, if no anchor
> is specified in the source, an empty fragment specifier is generated.
> I have the feeling this could be bad or even illegal, in any case it
> looks as if someone has been sloppy. I'd suggest to add some checks:
I would prefer to see proper XML validation via RELAX NG
happening. Then the stylesheets can rely on the XML stream
and be less verbose.
Of course, your solution addresses the current need, so is good.
> <xsl:template match="jump">
> <xsl:choose>
> <xsl:when test="@anchor and not(contains(@href,'#'))">
> <a href="{@href}#{@anchor}">
> <xsl:apply-templates/>
> </a>
> </xsl:when>
> <xsl:when test="@anchor and contains(@href,'#')">
> <xsl:message terminate="yes">Cannot have a fragment
> specifier in href if anchor is also given</xsl:message>
> </xsl:when>
> <xsl:when test="@href">
> <a href="{@href}">
> <xsl:apply-templates/>
> </a>
> </xsl:when>
> <xsl:otherwise>
> <xsl:message terminate="yes">Either href or anchor must
> be specified</xsl:message>
> </xsl:otherwise>
> <xsl:choose>
> </xsl:template>
>
> So, how should the issue with @anchor be handled?
First of all get it back into the DTD and jump/anchor handling
back into all of the stylesheets. We should perhaps implement
your abovementioned validation routine via stylesheet until we
get thorough XML validation happening.
> - In particular within a FAQ, how should a crosslink to another question be
> handled? I used <jump anchor="svghangs"> and
> <faq>
> <anchor id="svghangs">
> <question>...
> Yes, the faq element can have an id, but the faq2document doesn't
> handle it. There is already an anchor generated for links from the
> question index, but it is generated from the position (bad for links
> from the outside). Having two anchors doesn't hurt, but it's ugly.
> And, of course, anchor is not allowed at the point shown by the DTD.
I too am not happy with generated anchors - they are always
changing, so you cannot link from another document to a specific
FAQ. I was pleased to see your recent Topic Map thread, and will
try to comment there.
> - Many elements have a title attribute, in particular sections,
> including FAQ sections. This precludes using markup in titles, in
> particular <code>, <em> and a yet to invent <keyword> element (for
> indexing, an obviously interesting feature for FAQs). I'd suggest
> deprecating the title attribute and introducing a title child
> element. Whether DocBook is about to be reinvented or not is a
> question I will not ask here.
You provide very sound reasons. There was some discussion
on forrest-dev around February - i cannot find it quickly.
> - The FAQ DTD has a part element for structuring the FAQ. This sounds
> rather artificial. What's wrong with faqsection?
Mmmm .. Not sure happened with that. The Cocoon-1/faq.dtd
had faqsection. Then Cocoon-2/faq.dtd dropped it (perhaps
accidently). Then Forrest/faq.dtd brings it back differently.
> <plug>
> With namespaces and XSchema, FAQ specific elements could have their own
> namespace. This allows faq:section elements.
> </plug>
>
> - There is still a template for the connect element.
Is the <connect> element still relevant? There is still
confusion over the purpose of link|jump|connect and differences
between DTD v10 and v11 in this area. Does anyone know what
the <connect> is/was used for? Is it safe to drop it in DTD v11?
I did a UNIX find/grep through Cocoon and Forrest xdocs and it
is not used anywhere. (There was one unlinked C2 doc at
xdocs/css/testdoc.xml that looks useful. It too has a message
"FIXME: what is this 'connect' thing for".)
> <plug>
> With XSchema, an XSLT based tool could perform some primitive checks
> on the style sheet, it could warn if templates matching removed elements
> are still there.
> </plug>
Great idea. That would help with stylesheet maintenance.
> - I'd also suggest to add a catch-all template to document2html in
> order to avoid nasty surprises caused by unhandled elements:
>
> <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.
If you have patches for anything else then please send them
via forrest-dev list.
> - The document DTD has some hooks for augmenting certain element
> content. In the FAQ DTD the faq.mod is included after the
> document.mod. This makes it impossible to use the hooks from within
> the faq.mod. Is it planned to use the hooks for something, and if
> so, what are the guidelines for this? Should there be a separate
> faq.local.mod for local definitions, or should the faq.mod use for
> this?
I am a bit lost on that - perhaps someone else can answer.
--David
Re: DTD questions
Posted by Stefano Mazzocchi <st...@apache.org>.
"J.Pietschmann" wrote:
>
> Well, the problems still remain. Here a short form:
>
> 1. Make titles elements. This is a show-stopper for me.
> I'd take vetoes as cause to fork my own DTDs for FOP.
Hmmm, I don't think that anybody here has the power to veto something.
The goal of this project is to come up with a 'reasonable' common ground
for documentation across the xml.apache.org project and hopefully other
ASF efforts (and maybe more, but this is not our top priority).
I think you'll find out that people are very reasonable, but also
sensible forking threats. My suggestion would be to state clearly why
what exists doesn't work for you and I'm sure that people might provide
solutions that fit your needs, or decide to patch the DTD (which must
remain solid, but it's not carved in stone).
As for this particular problem, I came to agree with you that a <title>
element is required and I expressed why.
> 2. Handle links similarly, either provide all with an
> @anchor, or none. I'd prefer the latter, because of less
> ambiguity and for consistence with topic maps.
> 3. Provide more precise guidelines for when to use which
> link element than on
> http://www.krysalis.org/forrest/document-v11.html
> 4. Provide a mechanism for avoiding having the same target
> href in lots of links scattered all over the place, for
> the sake of easy maintainability of the hrefs.
>
> Is this concise enough to get some decisions (not necessarily
> final code) on short order?
I have clearly expressed the design ideas behind the current hyperlink
markup and I provided a solution for all the above problems and some
more.
Hopefully this meets your needs and will avoid any forking.
Thanks.
--
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: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Steven Noels wrote:
> Hey, cool down ;-)
Sorry, I was a bit disappointed that skin details got *much*
more attention than the somewhat more fundamental (and hard
to "fix later") structure details.
>> 2.
> Ditto - could you come up with a revised DTD fragment. Let the people
> choose between a number of different link elements, and only one with
> all possible attributes folded in.
The DTD is ok.
diff -u document2html.xsl.bak document2html.xsl
--- document2html.xsl.bak Thu Jun 6 21:00:55 2002
+++ document2html.xsl Thu Jun 6 21:01:48 2002
@@ -384,12 +384,8 @@
<a href="{@href}"><xsl:apply-templates/></a>
</xsl:template>
- <xsl:template match="connect">
- <xsl:apply-templates/>
- </xsl:template>
-
<xsl:template match="jump">
- <a href="{@href}#{@anchor}"><xsl:apply-templates/></a>
+ <a href="{@href}" target="_top"><xsl:apply-templates/></a>
</xsl:template>
Of course, you see, the @role and @title attribute are unused.
I like the (your?) idea to use @title for a tool tip and/or
an onMouseOver() script and perhaps as text in case the
link is empty.
Personally, I don't like the idea that the link tag describes
the mechanic involved when clicking on the link *in a HTML page*.
As I already noted, if several xdocs are formatted into a PDF
book, there is no such notion as "replace viewport". If a link
expresses this, there is trouble.
We could organize around scopes (document, project/subproject,
ASF, world), presentation organization (HTML and PDF files)
or UI mechanics (replace window, replace frame, fork).
The first is the most abstract, with the other you already have
to nail down presentational aspects weh writing the xdoc.
A suggestion
- link within the xdoc <link href="#id">
transforms to <a href="#id"> in HTML and
<fo:basic-link internal-destination="id"> in FO
- link to another xdoc of the same project/subproject scope
<link href="otherdoc.xml"> and <link href="otherdoc.xml#id">
Note the .xml (or whatever the original extension is)
Transforms to <a href="otherdoc.html"> respective
<a href="otherdoc.html#id"> in HTML and
<fo:basic-link internal-destination="geneate-id(element[@id])">
in FO (avoid id clashes)
- difficult, therefore skipped: link within ASF or broader project scope
- link arbitrary URL <jump href="arbitrary">
transforms to <a href="arbitrary"> in HTML and
<fo:basic-link external-destination="arbitrary"> in FO
- indirect links, through a map (perhaps, but not necessarily a topic map)
<xref ref="id"> (possible extensions: name map explicitely)
transforms to
<a href="document(map)/key('id',@ref)"> in HTML
more complex logic for FO for discriminating between internal and
external links.
>>4.
> This will take some more time, I believe. I don't want to impose yet
> another metadocument to manage to our users, but you have a point and we
> should fix this.
There is no requirement that the users *have* to use the
map/repository/metadocument. They *may* use it, and links
may be transformed from direct to indirect links and
vice-versa.
> Seriously: do you have a release date for FOP in mind?
There is a maitenance release pending in the short term,
however, I plan to overhaul the docs within 6-8 weeks.
J.Pietschmann
RE: DTD questions
Posted by Steven Noels <st...@outerthought.org>.
Joerg,
> Well, the problems still remain.
Hey, cool down ;-)
There is no boss or project manager keeping track of us, and we're all
useless in terms of time management.
> Here a short form:
>
> 1. Make titles elements. This is a show-stopper for me.
> I'd take vetoes as cause to fork my own DTDs for FOP.
A vote it will be - but please don't walk away if the result of this
vote is not to your liking. We need people like you over here. I'm +0.5
and will cast my vote in favor of the majority. It is trivial to add
this to the docv10->11 translation stylesheet after a decision has been
made.
> 2. Handle links similarly, either provide all with an
> @anchor, or none. I'd prefer the latter, because of less
> ambiguity and for consistence with topic maps.
Ditto - could you come up with a revised DTD fragment. Let the people
choose between a number of different link elements, and only one with
all possible attributes folded in.
> 3. Provide more precise guidelines for when to use which
> link element than on
> http://www.krysalis.org/forrest/document-v11.html
When we have decided on point 2, I will update the document. I'm +0 and
will cast my vote in favor of the majority.
> 4. Provide a mechanism for avoiding having the same target
> href in lots of links scattered all over the place, for
> the sake of easy maintainability of the hrefs.
This will take some more time, I believe. I don't want to impose yet
another metadocument to manage to our users, but you have a point and we
should fix this.
> Is this concise enough to get some decisions (not necessarily
> final code) on short order?
I'll ask the project manager ;-)
Seriously: do you have a release date for FOP in mind?
</Steven>
Re: DTD questions
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Well, the problems still remain. Here a short form:
1. Make titles elements. This is a show-stopper for me.
I'd take vetoes as cause to fork my own DTDs for FOP.
2. Handle links similarly, either provide all with an
@anchor, or none. I'd prefer the latter, because of less
ambiguity and for consistence with topic maps.
3. Provide more precise guidelines for when to use which
link element than on
http://www.krysalis.org/forrest/document-v11.html
4. Provide a mechanism for avoiding having the same target
href in lots of links scattered all over the place, for
the sake of easy maintainability of the hrefs.
Is this concise enough to get some decisions (not necessarily
final code) on short order?
J.Pietschmann