Thanks David. It seems pretty
much clear now.
Greetings,
Thanks for your feedback
regarding the DITA 1.2 specification.
My intent in this email is to
clarify the DITA specification language, and in the process help clarify the
processing examples regarding how topicrefs work in maps when they specify
processing-role=”resource-only”.
From the DITA 1.2 spec 2.1.2.2.4
DITA map attributes:
processing-role
Specifies whether the topic
or map referenced should be processed normally or treated as a resource that is
only included in order to resolve key or content references.
Topic T2 is in the map and
marked as processing-role=”resource-only”. When a resource is marked in this
way, then it does not contribute to output of the map. For output processing it
is as if this topicref is commented out. A topicref with
@processing-role=”resource-only” is identical to no topicref at all for
purposes of link resolution, either directly in a topic via the related-links
section or an xref, or in the reltable.
The next part of this is when
Topic T2 is now added to a row in a relationship table. Two cases are possible
the topicref of T2.
·
If the topicref of
T2 is copied as-is and processing-role=”resource-only” is maintained, then the
same rule applies as when T2 appears in the main body of the map. It would be
as if the topicref to T2 is commented out. Other topics in the row would not
“see” T2, hence no links.
·
If the topicref of
T2 is copied and processing-role is not set to “resource-only” then normal
processing for topicrefs in a reltable takes place. Since toc=”no” is the
default setting for a reltable this topic will normally not be output for
output like HTML. However if print=”yes” then this topic may be included for
PDF-like output.
The spec does not say what processors are to do in this or other
similar situations, and I think that is beyond what the spec should prescribe.
In the HTML example below:
·
If we take T1 and the 1st reltable case for T2, then
only T1 would be built, because T2 always has processing-role=”resource-only”.
·
If we take T1 and the 2nd reltable case for T2, then
T2 may be built, as T2 in the reltable does not have
processing-role=”resource-only”. A processor could then implement something
similar to the example given regarding HTML below.
In the PDF examples:
·
If we take T1 and the 1st reltable case for T2, then
only T1 would be built, because T2 always has processing-role=”resource-only”.
·
If we take T1 and the 2nd reltable case for T2, then
a processor might do either of the two PDF examples given, and either would be
equally valid.
Thanks.
- Dave H.
Dave Helfinstine
DHelfinstine@ptc.com
The processing for a topicref that is marked as ‘resource-only’
using the @processing-role and is used as a
referencing/referenced topic in the reltable is not clear. Suppose there are
two topicrefs – T1 & T2 in a map. T2 is marked as ‘resource-only’.
And in the reltable, it is defined such that both of these topic has a link to
the other.
As I remember from some earlier discussion, for HTML the
behavior shall be as follows:
·
Both T1 & T2 shall be built.
·
After building, T1 becomes a direct part of the
output.
·
After building, T2 just serves the linking
purpose.
·
After building, T1 shall have the link for T2.
Hence, the ‘resource-only’ topicref can act as a Target.
·
After building, T2 shall have the link for T1.
Hence, the ‘resource-only’ topicref can act as a Source.
For PDF, the behavior is not clear. I think it shall be as
follows:
·
Only T1 shall be built.
·
After building, T1 becomes a direct part of the
output.
·
After building, T1 shall not have a link
to T2. Hence, the ‘resource-only’ topicref cannot act as a
Target.
·
T2 shall not be built. Hence, the ‘resource-only’
topicref cannot act as a Source.
If that is the case, then for PDF the usability of the ‘resource-only’
topicref gets limited to Conrefs & Images. It cannot be used for links
& xrefs.
Another approach for PDF could be:
·
Both T1 & T2 shall be built.
·
After building, T1 becomes a part of the primary
PDF output.
·
T2 is built as a separate PDF & just serves
the linking purpose.
·
After building, T1 shall have the link for T2.
Hence, the ‘resource-only’ topicref can act as a Target.
·
After building, T2 shall have the link for T1.
Hence, the ‘resource-only’ topicref can act as a Source.
Regards,
Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com