OASIS Darwin Information Typing Architecture (DITA) TC

Both the architecture spec and language reference use the terms 
"runtime" and "build time" (also found one occurrence of "build-time" in 
the language reference).

However, these terms do not appear to be defined anywhere and it's not 
entirely clear what they mean, at least not in all cases.

This is important because the processing and behaviors of some elements 
are defined in terms of "runtime" or "build time" behavior, for example 
the navref element, which is "resolved a runtime". Since runtime and 
build time could be different for different types of outputs, there is 
significant potential ambiguity in what the implications are for a given 
element in a given output or processing context.

I think the intent is to distinguish the processing of DITA source into 
some rendered form (build time) and the access or delivery of that 
rendered form (and, of course, the direct access and delivery of 
unmodified DITA content), but it's not always clear what that other 
processing is and is it being applied to DITA files or to some rendition 
of the DITA files.

For example, if I transform DITA files into a package of Windows help, 
is that run time or build time? I think the intent is that it is build 
time, but then there is no (DITA-specifiable) runtime behavior because 
the result of the build process is not DITA. That is, the DITA spec can 
only directly define the processing applied to DITA data, not to data 
generated from DITA content. What we can do is define the *intended* 
behavior (not processing) of the rendered result, without specifying 
when or how that behavior is achieved (which is what talking about 
things like "runtime" and "build time" is doing).

In the case of navref, which is where I started to notice this issue, 
the text says:

"The 

Re:
>However it's

>clear that a lot of the spec reflects things that were done specifically

>for Eclipse that and, at least today, only have meaning there and are

>defined in terms of Eclipse behavior.

"A lot of the spec" = the navref and anchor
elements in DITA maps?

I can agree that we should clear up the language to
make the Eclipse references examples. That seems like a good 1.1 goal.


For 1.2 we have proposals for an expansion of conref
capability that may be able to fold navref and anchor into a more comprehensive
architecture. That's probably an appropriate place to attempt crisper definitions
of build time vs. runtime.

Michael Priestley

IBM DITA Architect and Classification Schema PDT Lead

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





"W. Eliot Kimber"
<ekimber@innodata-isogen.com> 
01/24/2007 10:57 AM




To
<dita@lists.oasis-open.org>


cc



Subject
[dita] runtime vs build time and navref






Both the architecture spec and language reference
use the terms

"runtime" and "build time" (also found one occurrence
of "build-time" in

the language reference).


However, these terms do not appear to be defined anywhere and it's not

entirely clear what they mean, at least not in all cases.


This is important because the processing and behaviors of some elements

are defined in terms of "runtime" or "build time" behavior,
for example

the navref element, which is "resolved a runtime". Since runtime
and

build time could be different for different types of outputs, there is

significant potential ambiguity in what the implications are for a given

element in a given output or processing context.


I think the intent is to distinguish the processing of DITA source into

some rendered form (build time) and the access or delivery of that

rendered form (and, of course, the direct access and delivery of

unmodified DITA content), but it's not always clear what that other

processing is and is it being applied to DITA files or to some rendition

of the DITA files.


For example, if I transform DITA files into a package of Windows help,

is that run time or build time? I think the intent is that it is build

time, but then there is no (DITA-specifiable) runtime behavior because

the result of the build process is not DITA. That is, the DITA spec can

only directly define the processing applied to DITA data, not to data

generated from DITA content. What we can do is define the *intended*

behavior (not processing) of the rendered result, without specifying

when or how that behavior is achieved (which is what talking about

things like "runtime" and "build time" is doing).


In the case of navref, which is where I started to notice this issue,

the text says:


"The <navref> element references a map file from within a map
file. The

reference is resolved at runtime, typically to pull together the

navigation for multiple components into a product navigation."


What does "resolved at runtime mean" (and what does "product
navigation"

mean)? Does it mean that the rendered result, in whatever is doing the

rendered (e.g., Eclipse help) presents what appears to be a single set

of topic heads and topic references or does it mean that the rendered

result presents a navigable link from one navigation context to another?


Instead of saying "resolved at runtime", the spec should say
what the

presentation and interaction behavior expectation is and, if it can

vary, under what conditions does it vary.


For example, I assumed on first reading that when generating HTML or

PDF, navref would have the effect of creating a "compound map"
that is

processed equivalently to the same map held in a single documentd. But

clearly that is not the intent, at least of the Toolkit implementors,

who have not implemented navref for HTML or PDF processing.


On second reading, it's still not clear to me whether or not treating

navref as a transform-time include is appropriate behavior for navref.

That is, is navref closer in semantics to a conref to a map (in order to

use all its contained topicheads and topicrefs) or is it closer in

semantics to a topicref, which simply creates a link to the topic

referenced? Upon reflection I think it's the latter, but it's not clear

from the text that that's the case.


While it would be ideal to clean up all the places where runtime and

build time are used and replace them with more declarative definitions,

I know that's not practical for 1.1. However, I think we do need clear

and formal definitions of the terms "runtime" and "build
time" and what

they mean for different well-established rendition types (HTML, PDF,

help, etc.).


[As a side note: I have something of an issue with the mention of

Eclipse-specific behavior as anything other than examples--however it's

clear that a lot of the spec reflects things that were done specifically

for Eclipse that and, at least today, only have meaning there and are

defined in terms of Eclipse behavior. I don't think that's appropriate

for a general standard. I don't expect it to be addressed in

1.1--there's not time. But it needs to be addressed in 1.2. If I was

Sun, for example, I'd be rather upset that my competitor's IDE had

privledged status in this otherwise general standard.]


Cheers,


Eliot

--

W. Eliot Kimber

Professional Services

Innodata Isogen

8500 N. Mopac, Suite 402

Austin, TX 78759

(214) 954-5198


ekimber@innodata-isogen.com

www.innodata-isogen.com