[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: assembly issues
|
Here
is my original email about assembly with comments from Norm,
Jirka, and Larry interleaved. Please review this before our
meeting on Wednesday 11 April. I hope to resolve these
issues so we can start the Errata process for DocBook 5.1. Bob On 3/15/2018 9:55 AM, Robert Stayton
wrote:
---------------------------------------------------------------------------
Those look like weird values for “@grammar” to me. I think there
should be a content type attribute for the media type, distinct from
the grammar.
In some cases, the content type is sufficient to identify the type of
resource, but for XML it often isn’t.
My understanding of @grammar is that it was for identifying the
“flavor” of markup: docbook, dita, html, etc.
---------------------------------------------------------------------------Norm: Assemblies mix together some fairly deep processing expectations with
an attempt at declarative markup. I’m not wholly satisfied with the
way it came out, but it’s what we all agreed it.
My understanding is that the transform element is a declaration: this
thing can translate from that format. It’s possibly an oversight that
we don’t have a way of saying what it’s translated into.
Jirka: I don't see why we would like to support any other kind of output than
DocBook.
---------------------------------------------------------------------------Norm: Given that we say they can be chained together, it’s possible that we
intentionally didn’t say anything about the output formats for what
might be intermediate transformations.
But the “last one” must be expected to generate DocBook, I think.
Larry: Outputs are not necessarily DocBook. Transforms are intended to serve two purposes:
1. Normalize different markups to DocBook for combination into the resulting structures.
2. Provide additional output capabilities beyond the standard DocBook outputs. In the example above, the transform with name=”tutorial” would produce the output to feed a tutorial delivery engine from the DocBook resulting from the assembly process.
---------------------------------------------------------------------------Norm:Both the resource and resources elements can have a grammar attribute.
So you could say:
<resource grammar="dita" href=""/>
The expectation being that if you refer to that in a module, and if
there’s a transform for the dita grammar, it will be transformed
automatically when it’s included.
Larry: The grammar attribute appears on two classes of elements, sources and transform references. They are used for matching. If a source of content is marked with a grammar=”dita” and a transform is marked with a grammar=”dita” the transform will be used to convert the dita-based resource to DocBook before the assembly of the content. The grammar-“text/xsl” is just incorrect and a red herring.
---------------------------------------------------------------------------Norm:Right. My comment above about content type is exactly this.
---------------------------------------------------------------------------Norm: I think that's a bug.Jirka: That seems strange and doesn't align with the fact that grammar and name
are exclusive. Perphaps there is missing additional attribute, something
like type that would indicate language in which transformation is written.
---------------------------------------------------------------------------Jirka: I think that grammar should hold name of vocabulary which can be
transformed to DocBook by the transformation. So grammar should be
contain values like "dita", "tei", etc.
---------------------------------------------------------------------------Norm: Exactly. My best guess is that the use of media types in grammar was
not carefully considered.
---------------------------------------------------------------------------Norm: I think href points to the transformation script (XSLT stylesheet,
XProc pipeline, whatever the processing environment supports). Grammar
identifies the kind of vocabulary that can be transformed with it. And
the element is currently missing a content-type attribute to identify
what kind of transformation technology it is.
Jirka:
As I have written above there should be different (and currently missing
attribute) used for this, IMHO.
Larry: The @href is a link to the actual transform. I think it was originally valid to provide @href or @fileref and the example was developed when either was valid. I actually prefer using fileref for local and href for HTTP exposed resources because I think it makes it easier to understand things, but whichever the grammar allows works. The @grammar is used as a match to @grammar elements on resources to say “use this transform to normalize this content to DocBook.”
---------------------------------------------------------------------------Norm: We’re definitely off in “guessing” territory now. But my guess is that
@name is meant to identify a resource element. It probably isn’t
called linkend, and isn’t of type IDREF(S) because the way assemblies
can be composed it would often be the case that the IDs wouldn’t be
available until assembly time.
So you can point to the resource by href or you can point to a
resource. If you point to a resource, there’s an @grammar there and
not allowing one on the transform means you can’t miss-match them.
But I’m not very confident of my guess. For one thing, the example in
3.5 has transforms with both @name and @grammar which isn’t allowed.
Maybe those names should be xml:ids.
Larry: The reason that @name and @grammar are exclusive is that the two have different purposes. I am not sure they have to be exclusive, I just didn’t see them being used at the same time. The @grammar is used to match incoming content for normalization to DocBook and the @name is used to specify transforms OTHER than the standard DocBook rendering (mostly for output operations beyond the normal DocBook render types). Making them non-exclusive is OK if there is another use model for the transforms. I suspect it should actually be a IDREF, but I seem to remember there was some reason we made it a TOKEN instead, perhaps to support multipart assemblies.
---------------------------------------------------------------------------Norm: That’s where the content-type should be.
Jirka: That's. I think @type should be used there instead of @grammar and then
it starts making sense.
Larry: This is something I don’t remember much about, but I think that the model is more one of fallback than one of type. In that case, I would presume that two transforms with the same grammar would be selected based on order; that is, the XProc transform for Office to Docbook would be listed first, then the XSLT-only transformation, so that if XProc is available, it will be used, otherwise the XSLT transform will be used. Otherwise, a priority indicator of some sort would have to be added. Both of the transforms would have the same @grammar attribute (@grammar=”office”). This is my understanding.
---------------------------------------------------------------------------Norm: If @name is a pointer, it would just refer to the same resource.
Jirka:
If we introdice @type in the above sense then assembly processor should
use transform element with supported @type and given name.
Larry: I believe the @name attribute should likely be unique rather than repeated. Otherwise it would be selected the same way described above for duplicate @grammar values. I would suspect this would be less used than the duplicate @grammar.
---------------------------------------------------------------------------Norm: I think this should be
<resource xml:id="overview" href=""
grammar="dita"/>
The processor should find an appropriate transformation from the list
of transforms.
Jirka: I don't know if I recall it correctly, but it could be that if
- resource has @grammar then appropriate transform is looked up based on
@grammar on transform
- resource has @transformation then appropriate transform is looked up
based on @name on transform
Larry: I believe the example is in error. It should be @grammar=”dita”. That would convert the DITA content to DocBook before assembly.
---------------------------------------------------------------------------Norm: Ah, this seems to just be broken.
Larry: I believe this example is an error (and was based on an earlier, more complex schema).
I agree with that change.
---------------------------------------------------------------------------Norm: I think the intent is that the “overview” module (presumably an
article) is to be transformed into a book by the transform (despite
its misleading name) and subsequently the standard transformation will
turn the book into a partintro.
Jirka: Perhaps yes and such functionality is there to support more complex
scenarios where @renderas is not sufficient.
---------------------------------------------------------------------------Norm: I expect that we did allow transform as a child of module at one
point. Either we decided this complicated chaining of transformations
was more than we needed, or we removed it by mistake.
Larry: I agree that the description is incorrect. There might be multiple output elements with different processes applied for the different output destinations.
---------------------------------------------------------------------------Norm: Application-dependent, I think. You can list several, and the
processor is expected to know which one is “best”. That seems a
bit…speculative to me.
Larry: I am not really clear on this. I don’t think fallback other than to the normal DocBook transforms for output is necessarily required, but fallback is something I have not really dealt with – if the system fails to correctly specify things, they typically fail and we fix them in our production environments (which are not currently using assemblies).
---------------------------------------------------------------------------Larry: I don’t see the need for this since they are
actually selection mechanisms for different classes of
transforms. However, this could be discussed.---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: I believe this is not appropriate since the @grammar
match is used for some selections. I think that either @grammar
or @name should be required.---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: I don’t think this is necessary since @grammar does
this matching.---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: I think this is reasonable (don’t remember why it
was there originally, but it was a long time ago).Norm: Assuming we all agree on the proposal, after we’ve explored our
respective understandings of the situation, I’ll undertake to fix the
documentation as appropriate.
Jirka:
That's one possibility. Second one is to introduce @type on tranform and
keep two ways of addressing transformation -- by name of the transform
or by the name of vocabulary (@grammar) that it supports. But it
probably doesn't make sense to support two different ways of referencing
transforms, so your prposal is more sound. But I think that in this case
@grammar should be renamed to @type.
I know that people from XML Mind XML editor are probably one of fews
that implemented Assemblies, so it could make sense to discuss proposal
with them once it's coherent.
---------------------------------------------------------------------------Larry: The transform element is also used to define
specialized transformations for output types that go beyond those
supported directly by the DocBook transformations.---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: Disagree. The @grammar match should be used for
binding transforms to <resource> elements.---------------------------------------------------------------------------
3. Define @grammar in a <transform> to be the grammar of its @href so the correct processor can be selected. ---------------------------------------------------------------------------Larry: Agree, but see below. ---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: Disagree. It is also the mechanism for matching the
required transform for converting the source schema to normalized
DocBook.---------------------------------------------------------------------------
4. If more than one transform has the same name, then the behavior is application defined. It could perform a selection based on some criteria or it could be sequential. Or it could be profiled to select one at runtime. ---------------------------------------------------------------------------Larry: I am ambivalent about this. This is probably the
correct behavior, but I have few enough transforms in any
environment I work with that it would likely be a single transform
of any given type that would be provided. However, for
portability I could see this being a reasonable description.---------------------------------------------------------------------------
---------------------------------------------------------------------------Larry: I would not see this as being a common occurrence,
since I envision transforms bound to resource elements being used
for normalization to DocBook and transforms being bound to output
elements being used for accomplishing specific classes of complex
outputs (like producing content to feed a tutorial delivery
engine). This is one reason I think the schema does not allow
@name and @grammar on the same transform, since the two attributes
are for different mappings.---------------------------------------------------------------------------
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]