dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] referencing a bookmap from a map
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Ogden, Jeff" <jogden@ptc.com>
- Date: Fri, 12 Jun 2009 15:25:58 -0400
If we feed our existing bookmap processes
a combo map - ie we literally aggregate several of them together, including
multiple backmatters etc. - and we normalize and remove DTDs so there's
no validation issue - do the processes work?
In other words, is there any code in
bookmap that depends on the structural rules of bookmap being followed?
If there are multiple definitions of the book title, for example, does
the code know to take the first one, even though structurally there should
only ever be one? If there are multiple indices, does the index processing
know to look only for index entries within each subsumed bookmap, rather
than the scope of the whole map?
I understand why the use case below
is a nice-to-have - but are we prepared to (re)code every process for specialized
maps to allow for the possibility of aggregation and recursive nesting,
even when explicitly prevented by the specialization? For example, if we
allow <topicref> to <appendix> to retain its <appendix>ness
no matter where we're referencing from, then we are allowing <appendix>
inside <frontmatter>. And <chapter> inside <appendix>.
And if that is ok, then my question
would be - why don't we allow the same arbitrary nesting rule in the DTD?
If we're going to allow reusers to circumvent the content model by reference,
why won't we let them do the same thing without referencing? Either way
we need to add the code to support it, so why the limitation for people
working in just one document?
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Ogden, Jeff"
<jogden@ptc.com>
06/12/2009 02:50 PM
|
To
| "dita" <dita@lists.oasis-open.org>
|
cc
|
|
Subject
| RE: [dita] referencing a bookmap from
a map |
|
One use case that uses map
to specialized map references involves several separate “books” each
developed independently and each with their own map. Each map is
a different map specialization. As an example we might use a bookmap and
a learningbookmap.
At a later time someone wants
to create a new deliverable that includes two or more of these existing
“books”. So they use a generic map that references each of the
specialized maps that they want to include, something like this:
map
title
topicref to bookmap
topicref to leaningbookmap
They might well get two separate
frontmatter and backmatter sections, one for each book and that is fine.
If we take approach #2 or approach
#4, I think this case works since the composition process has all of the
information that composition of the separate specialized maps had.
If we take approach #3, things
don’t work as well because we lose most of the specialized information
contained in the two specialized maps because those maps are referenced
from a generic map. And while you might replace the generic map with
one of the specialized maps, I don’t think that will always work unless
one of the specialized maps is a superset of the other or at least supports
a subset of the elements used in both specialized maps.
-Jeff
From: Ogden, Jeff
Sent: Friday, June 12, 2009 2:31 PM
To: 'dita'
Subject: RE: [dita] referencing a bookmap from a map
I’m not sure we’ve made much
progress on resolving the generic map to specialized map referencing issues.
Here is my summary from earlier
in the week:
> … it would seem that we have some choices,
but I'm losing track of who is pushing for what:
> 1) Make map to bookmap illegal, Bruce's original approach, now withdrawn.
>
> 2) Allow map to bookmap, where the bookmap context is not
> overridden by the map, my proposal from earlier today, still on the
> table.
>
> 3) Michael's proposal that I'm not sure I understand, but which
> would have map references behave more like conref and so presumably
more
> specialized topicrefs would be generalized to less specialized
> topicrefs, or pretty much the opposite of approach #2 (Michael, correct
> me if I got your proposal wrong).
>
> 4) Eliot's proposal, which I'm not sure I understand, but which
> seems to be "anything goes" leaving it up to the implementers
(Eliot,
> correct me if I got your proposal wrong). . Eliot would proposal
#2
> allow you to do what you want to do?
Since then, Michael has clarified
his proposal (#3), but it is pretty much based on making sure that the
referenced element makes sense in the context of the referenced element,
even if we lose information in the process and even if the elements below
the referenced element don’t make sense in the new context.
Eliott’s proposal (#4) is
quite different from Michael’s, and more similar to mine (#2).
Still another approach (#5)
is to simply punt and leave
this undefined in DITA 1.2 much as it was undefined in DITA 1.1 and 1.0.
I’m not sure how best to move
toward a decision, but one possibility is to have a few folks submit use
cases and then ask how well the different proposals work for each. I’ll
do one of those in a separate e-mail message later today or over the weekend.
I’d encourage others to submit their own use cases.
-Jeff
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, June 09, 2009 7:41 PM
To: Ogden, Jeff
Cc: dita; Eliot Kimber
Subject: RE: [dita] referencing a bookmap from a map
I think the role of the referencing element is the one thing we're sure
is valid in the referencing context. So we can have a <chapter> element
reference a bookmap, and it becomes a set of chapters; or it can reference
an appendix, and the appendix becomes a chapter. But either way, the semantics
of the referencing element wins over the semantics of the referenced element.
It does get interesting though in the case here:
http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html
>Note: In some cases, preserving the role of the referencing element
may result in out-of-context content. For example, a chapter that references
a >bookmap may pull in <part> elements. Those part elements take
on the role of chapter, but likely contain additional chapter elements.
The result in this >case is implementation specific; processors may
treat this as an error that prevents further processing, issue a warning,
or assign new roles to the >descendants without an error or warning.
That's still following the rule that the referencing element's semantic
wins: the parts become chapters because the referencing element is a chapter.
But the referenced parts in turn contain chapters, and it's less clear
what to do programmatically that would be safe. Generalizing happens to
be safe in this case, but isn't always going to be safe (eg, what if I'm
referencing from a specialized chapter element that only allows <subchapter>
references?). So I think the recommendation here still holds true - ie
that the result is up to the processor. But it doesn't change the clear
guidelines we have for the simple cases, where the semantic of the referencing
element wins every time.
Maybe I've been overselling the conref comparison. The key here is that
the semantic of the referencing element is the only semantic we know to
be valid in the current map. If topicref is the referencing element, that's
the only thing we know to be semantically safe. If the reference was done
with a <chapter> element, we'd pull in the target map's contents
as <chapter>s. If we reference with <topicref>, the contents
should be pulled in as <topicref>s.
Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Ogden, Jeff" <jogden@ptc.com>
06/09/2009 07:20 PM
|
To
| Michael Priestley/Toronto/IBM@IBMCA,
"Eliot Kimber" <ekimber@reallysi.com>
|
cc
| "dita" <dita@lists.oasis-open.org>
|
Subject
| RE: [dita] referencing a bookmap from a map |
|
Michael wrote:
> …by default, I think that a topicref to a bookmap
that pulls it into a non-valid context should
> generalize (ie treat it like an unspecialized map) rather than create
an aggregate whole that breaks
> the constraints of the structural specialization.
I realize we are talking about generic map to specialized map references
here, but the above isn’t the behavior that proposal 12055 calls for in
the case of a specialized map to a more specialized map reference, is it?
-Jeff
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, June 09, 2009 6:56 PM
To: Eliot Kimber
Cc: dita; Ogden, Jeff
Subject: Re: [dita] referencing a bookmap from a map
Hi Eliot,
As a level-set, here's what the spec currently says about format="ditamap":
http://docs.oasis-open.org/dita/v1.1/OS/langspec/common/theformatattribute.html
The linked-to resource is a DITA map. It represents a referenced hierarchy
at a position within referencing hierarchy, and a referenced relationship
table included outside the referencing hierarchy
So it does, at least to me, read like an explicit behavior. I'd agree that
this should be a default behavior, rather than required. But as a default
behavior, I think it should preserve the validity of the referencing map
as it aggregates, and not create invalid structures.
Earlier you wrote:
>My initial reaction to this is that it is unnecessarily restrictive
because
>map-to-map relationships are not really conref relationships (if you
want
>conref, use conref) but looser composition (of compound map) relationships
>where the relevant constraints and processing implications cannot be
known
>in advance.
Actually if you want conref you can't use conref - not unless we allow
<map> to nest arbitrarily. Note that the description above says to
create the referenced hierarchy at the current position, but any referenced
relationship table should be included outside. That preserves the validity
of the map (which doesn't allow reltable inside a topicref) in a way that
isn't possible with conref.
>That is, when processing a map, a processor need not create a literal
new
>map, but simply process the referenced map as it exists, with knowledge
of
>the referencing context. In that case, the fact that the referenced
topicref
>is a bookmap chapter may or may not be relevant and the user may or
may not
>care.
I agree that when processors aren't treating the mapref as an aggregator
there's no need to generalize. My concern is for when it is treated like
an aggregator, which is at least the default behavior.
If someone creates an override processor, or a specialized element with
overriding processing, they can do what they want. But by default, I think
that a topicref to a bookmap that pulls it into a non-valid context should
generalize (ie treat it like an unspecialized map) rather than create an
aggregate whole that breaks the constraints of the structural specialization.
Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
Eliot Kimber <ekimber@reallysi.com>
06/09/2009 06:20 PM
|
To
| "Ogden, Jeff" <jogden@ptc.com>,
dita <dita@lists.oasis-open.org>
|
cc
|
|
Subject
| Re: [dita] referencing a bookmap from a map |
|
On 6/9/09 5:00 PM, "Ogden, Jeff" <jogden@ptc.com> wrote:
> There are two classes of users here. Authors and implementers.
>
>
>
> Different authors will feel differently about being allowed or
> prohibited from shooting themselves in the foot. And they may
feel
> differently still before and after shooting themselves in the foot.
>
>
>
> Implementers (like me) are looking for some guidance. Should we keep
> authors from shooting themselves in the foot, warn them, but let them
> shoot themselves in the foot if they wish, or just let them shoot
> themselves in the foot without any warning. And if we let them shoot
> themselves in the foot, should different implementations always shoot
> the same foot or can some implementations shoot the left foot while
> others shoot the right, while still others shoot the head? As an
> implementer, what I want to avoid is having someone say that after
we
> shot them in the right foot that we should have shot them in the left
> foot because that is what some other implementation does or what the
> DITA specification calls for.
>
>
>
> To get back to DITA maps, it would seem that we have some choices,
but
> I'm losing track of who is pushing for what:
>
>
>
> 1) Make map to bookmap illegal, Bruce's original
approach, now
> withdrawn.
>
> 2) Allow map to bookmap, where the bookmap context
is not
> overridden by the map, my proposal from earlier today, still on the
> table.
>
> 3) Michael's proposal that I'm not sure I understand,
but which
> would have map references behave more like conref and so presumably
more
> specialized topicrefs would be generalized to less specialized
> topicrefs, or pretty much the opposite of approach #2 (Michael, correct
> me if I got your proposal wrong).
>
> 4) Eliot's proposal, which I'm not sure I understand,
but which
> seems to be "anything goes" leaving it up to the implementers
(Eliot,
> correct me if I got your proposal wrong). . Eliot would proposal
#2
> allow you to do what you want to do?
I'm saying #2, without bothering to say anything about "bookmap context"
because that's a processor-specific implementation detail. Either processors
are *obligated* to treat more-specialized topicrefs as generalized to the
level of the referencing topicref (Michael's proposal) or they aren't.
If
they aren't, then how they remember what the unspecialized type of a given
topicref is is an implementation detail.
I'm also suggesting that any implementor, e.g., Arbortext, is free to say,
for that implementation, whether a particular case is or isn't meaningful,
so if Editor said "maprefs from <map> to <bookmap> aren't
sensical *to us*"
I would be fine with that. But if it instead "this is the sense it
does make
to us" I would be fine with that too (from a conformance standpoint).
Cheers,
E.
----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email: ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com> | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]