[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Map structure and possible new attribute for conref push and anchorref
Hi everyone,
In this morning's TC call we discussed the requirement to be able to say
"these topics need to be processed but do not contribute directly to any
output result". I said I would follow up by writing a proposal for
fulfilling this requirement, that the group could discuss and then vote
on. This is a proposed substantive change to the 1.2 specification:
Overview:
The discussion this morning centered on fulfilling this requirement by
adding a new attribute to the topicref attribute set. The new attribute
could be called "localdisplay" and would function in an analogous way to
the toc, print, and search attributes. There are other possible ways to
fulfill the requirement, such as the one suggested by Eliot in a branch
of this thread, however the idea of a new "localdisplay" attribute seems
like a clean and reasonable approach, so I will expand on it here.
Proposed scope:
The new attribute should be added to the %topicref-atts; and
%topicref-atts-no-toc; attribute sets described here:
http://docs.oasis-open.org/dita/v1.1/CD02/langspec/common/topicref-atts.
html
Proposed name:
"localdisplay". In previous discussions I've suggested a name of
"appear" or "display" but "localdisplay" is now my favourite (I think
Gershon suggested it).
Proposed description:
Specifies whether the topic should be displayed in output at the
location of the topic reference. For example, if a topic is not intended
to be used directly in output, but must be included in a map because it
contains content that is to be transcluded into another topic via the
conref push mechanism, set the localdisplay attribute to "no" to prevent
the topic from appearing twice in output. If the value is not specified
locally, but it specified on an ancestor, it will inherit the value of
the ancestor.
yes
Include the topic at the location of the topicref
no
Do not include the topic at the location of the topicref
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
Usage example:
Continuing on my example from below, the author of Folder2 can create a
third map called masterbuild.ditamap, with contents as follows:
<map>
<topicref href = "Folder1/default.ditamap" format = "ditamap"/>
<topicref href = "Folder2/pushmap.ditamap" format ="ditamap"
localdisplay ="no"/>
</map>
The author of Folder2 and of masterbuild.ditamap can then process
masterbuild.ditamap to create deliverables. Any topics referenced by
pushmap.ditamap will not appear at the end of a deliverable, however the
contents of the pushed topics will appear in appropriate locations
within the topics that are referenced by defaultmap.ditamap.
Regards,
Su-Laine
Su-Laine Yeo
Interaction Design Specialist
JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com
http://na.justsystems.com
-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
Sent: Wednesday, January 21, 2009 12:10 PM
To: dita@lists.oasis-open.org
Subject: [dita] Map structure and possible new attribute for conref push
and anchorref
From the Jan 20, 2009 minutes:
8. New ITEM: "Conref push for static output formats" discussion
* http://lists.oasis-open.org/archives/dita/200812/msg00006.html
* http://lists.oasis-open.org/archives/dita/200812/msg00007.html
Discussion from Su-Laine Yeo and Michael Priestley ensued. Michael
clarified that there would be a master build map (owned by the
information architect for the product) that the processor would call.
How to handle content that should not be displayed anywhere? Su-Laine
stated that this is a problem for anchorref also. Possibly need a new
attribute. Discussion to follow via e-mail.
------------------
Here is a summary of the overall user goal we discussed in the meeting:
Using this example:
- Folder1 containing a file called defaultmap.ditamap and a file called
default.dita. The map contains a topicref to default.dita.
- Folder2 containing a file called pushmap.ditamap and a file called
push.dita, where the push.dita topic has a <step> to be pushed into a
set of steps in default.dita. The map contains a topicref to push.dita.
We want the author of the Folder1 contents to not have to know anything
about the contents of Folder2. The author of Folder2 must be able to
produce a deliverable that resolves conrefs pushed from push.dita into
default.dita. One way for the author of Folder2 to do this is to create
a third map called masterbuild.ditamap, with contents as follows:
<map>
<topicref href = "Folder1/default.ditamap" format = "ditamap/>
<topicref href = "Folder2/pushmap.ditamap" format ="ditamap"/>
</map>
The author of Folder2 and of masterbuild.ditamap can then process
masterbuild.ditamap to create deliverables.
A problem with using master build maps is that, given current processing
rules, processing masterbuild.ditamap, the contents of pushmap.ditamap
would appear in output. Using the toc attribute will not solve the
problem as the toc attribute suppresses topics from the table of
contents but not the body of the deliverable. In PDF output the contents
of pushmap.ditamap would appear to be dumped at the end of the document.
Also, the toc attribute does not necessarily prevent the topics of
pushmap.ditamap from appearing twice in search results or indexes, as
the behaviour of the toc attribute with respect to search and indexes is
undefined. Therefore, a new @appear attribute which would completely
suppress pushmap.ditamap from the toc, the body of the document, and
other access points such as search and index, would be useful. There are
other ways to solve this problem, but a new attribute is one obvious
solution.
I briefly mentioned in the meeting that we have a similar problem with
anchorref. To explain further, the <anchorref> element proposed here:
http://www.oasis-open.org/committees/download.php/26092/IssueMapConvenie
nces12047.html is similar to conref push in that it is also intended to
allow pushing of content from one independent content set into another.
A master build map would also be needed with topicrefs to both the
default map containing the <anchor> and the pushing map containing the
<anchorref>.
The <anchorref> proposal currently says, " The copied child elements can
be suppressed in the current context by setting the toc attribute on the
child elements to "yes" and on the <anchorref> element to "no"." As I
explain above, setting a toc attribute would not suppress anything from
the current context, so I think the @appear attribute is what we'd need
on this as well.
As an aside, I am not sure why we need to add a new <anchorref> element
when it seems to do the same thing as conref push.
Regards,
Su-Laine
Su-Laine Yeo
Interaction Design Specialist
JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com
http://na.justsystems.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]