Re: [dita] referencing a bookmap from a map

[Eliot Kimber <ekimber@reallysi.com>]

But I don't think is a case where the spec can have an opinion on default
processing: either generalization is always applied or it's up to the
processor. That says nothing about default processing, or any processing,
only what the effective data values are.

I'm saying that requiring generalization is not the right answer.

The spec can certainly say "processors are welcome to set as their default
processing generalization of more-specialized map components when referenced
in the context of less-specialized map types".

But that's very different from specifying default processing.

On 6/12/09 3:32 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:

>> But in fact, as indicated in my note of a few minutes ago about
> clarifying
>> peer, there is no DITA-defined notion of "publication" nor is there a way
> to
>> indicate that a given map is only navigation over separate publications
> as
>> opposed to defining an atomic unit of publication.
> 
> The question is what do you want to happen by default.
> 
> By default, currently, a topicref to another map pulls that map into the
> processing context. This is not the only possible result, but it is
> certainly a possible result. If you do nothing except create a topicref to
> another map, and produce output, I think it is a reasonable default to
> expect the target map to be pulled in. It is also perfectly reasonable to
> override that default.

Here you say "pulls that map in to the processing context"--that does not,
by itself imply anything about sensibility or validation or the nature of
that processing, in particular, whether or not the processing treats the map
as a single effective map or what.

The problem is that the current spec is *seriously underspecified* on this
subject. For example, how does the scope attribute affect this processing,
if at all? The spec is currently silent.

Saying the "target map is pulled in" doesn't say what it means to be "pulled
in", it only says that the referenced map is processed in the same
"processing context" but we don't say what "processing context" implies
beyond the rules for key definition *because we can't*.

That is, "in the same processing context" does *not* imply, necessarily, a
single output result. That seems to be the assumption you are making.

I observe that the language under <mapref> is not consistent with the
language under format=ditamap:

Mapref: "The hierarchy of the referenced map is merged into the container
map at the position of the reference, and the relationship tables of the
child map are added to the parent map."

Format=ditamap: "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"

These two statements need to be the same or mapref needs to defer entirely
to format=ditamap since it cannot, by itself, change the semantics of
format=ditamap. And since these statements do not unambiguously mean the
same thing, we need to decide which one is correct (if any).

And reading the language of <mapref> I think I have to object to "merged
into" since that is processing talk. I think it needs to be something like
"is treated as though it had occurred at the point of reference" or
something similar (so that the language does not appear to imply a literal
transformation applied to the map).

I think we also need language that clarifies the implication of scope=peer
and scope=external in this case:

- Is peer or external even meaningful?
If they are meaningful:
- Does peer imply key merging?
- Does external imply key merging?

[And I will observe also that as far as I can tell there is no syntax for
one map referencing a key defined in another map that establishes a
separate, independent key namespace (e.g., scope="peer" (maybe) or
scope="external" (maybe). That's a hole (possibly) in the keyref design but
it does mean that there's no need to define what it means for one map to
reference a key in another, distinct key space, because it can't happen.

But I would definitely like to have a standard-defined way to reference one
publication from another publication's map without merging the keys of the
two maps. 
]

> The question is whether, *by default*, I should be able to pull in
> specialized portions of the target map into contexts *which will break
> default processing*.

What is default processing in this context? The Toolkit's implementation of
bookmap?

The definition of bookmap in the current 1.2 lang spec says nothing about
processing whatsoever. Likewise, the <chapter> element text says nothing
about it not being meaningful to allow nested chapters (although the content
model does not, of course, allow nested chapters--but without any supporting
prose its impossible to know if that is an arbitrary design decision, a bug,
or a reflection of a deeply-held conviction that chapters should never nest
in any possible context.

That is--the language of the current 1.2 draft spec provides little, if no,
basis for arguing semantics on the basis of processing *because it doesn't
define any* for bookmap.
 
> In other words, should the preprocess step that resolves references across
> specialized maps allow specialized content into places where it is not
> valid?
> 
>> In the case where map is only providing navigation
>> ... 
>> That argument alone, is sufficient, I think, to make it clear that
>> disallowing any particular organization of stuff in a map by the spec
> would
>> be wrong--the sensibleness is entirely a function of the processing
>> semantics of the map and not the things included.
> 
> You can organize your map any way you want. The question is, and has been
> from the start, what to do with the specialized semantics of the target
> *when aggregating the content for further processing*. The fact that other
> use cases exist is not relevant to this one.
> 
> 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/12/2009 04:15 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/12/09 1:50 PM, "Ogden, Jeff" <jogden@ptc.com> wrote:
> 
>> 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.
> 
> But in fact this use assumes that the intended (or only allowed) result is
> a
> single unit of publication.
> 
> But in fact, as indicated in my note of a few minutes ago about clarifying
> peer, there is no DITA-defined notion of "publication" nor is there a way
> to
> indicate that a given map is only navigation over separate publications as
> opposed to defining an atomic unit of publication.
> 
> In the case where map is only providing navigation, it's hard to argue
> that
> nesting reference to one bookmap inside a reference to another bookmap
> would
> be a problem since it's a purely navigation relationship and may simply
> indicate a hierarchy (similar to the library navigation trees we had at
> the
> front of the manuals in the Networking System publications back in my
> day).
> 
> That argument alone, is sufficient, I think, to make it clear that
> disallowing any particular organization of stuff in a map by the spec
> would
> be wrong--the sensibleness is entirely a function of the processing
> semantics of the map and not the things included.
> 
> 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
> 
> 

----
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>