OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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


I like the distinction of being a only a resource as 
opposed to being treated normally (e.g., rendered).

So I lean toward attribute values of "resource-only" 
(or resourceonly or resourceOnly) and "normal", the
latter being the default, of course.

For the attribute name, usage or any of those Robert
mentions (processingrole, topicusage, topicrole) would
be okay with me.

paul

> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com] 
> Sent: Friday, 2009 February 13 15:21
> To: dita@lists.oasis-open.org
> Subject: RE: [dita] Map structure and possible new attribute 
> for conref push and anchorref
> 
> Hi,
> 
> I just wanted to raise this issue again before our next 
> meeting. I don't
> have a solid solution, just a summary of where I think we are:
> * It seems we agree there should be a new attribute.
> * The purpose is to distinguish topics that are used as a 
> resource, for
> whatever reason, but are not meant to be read on their own as 
> part of the
> current information.
> * In many (most?) cases, the practical effect will be that 
> the topic does
> not get rendered (generated, output, whatever), even though 
> it is present
> for conref resolution or other uses
> 
> Right so far? If so, that just leaves the attribute name and 
> value. I think
> this is where the conflict lies.
> 
> My thoughts on this:
> * As I said on the call, I prefer to avoid an attribute named 
> "output",
> because of the implication that DITA has to generate some 
> other format.
> * That said - I realize that the average user is going to 
> think of this
> attribute in terms of its processing implications
> * If we go with an attribute related to the usage role, then 
> we have to
> find a way to distinguish it from other roles we have today. 
> We have a role
> attribute that describes how the target of a link relates to 
> the current
> topic (parent/child/etc), which is not the same as this role. 
> We also often
> talk about reader roles (administrator, etc). In this case we 
> mean the role
> of a topic within a set of topics, completely unrelated to the reader.
> * I prefer to avoid yes/no attribute values. We had 
> print=yes/no, which
> seemed obvious, until we had to add "printonly". We have 
> toc=yes/no, but
> there is discussion of new values to handle map references. 
> Yes/no makes it
> much more difficult to expand when we discover new cases.
> 
> To me - we are describing "This topic is not a readable topic 
> to be viewed
> or displayed" vs "This topic is a normal topic that makes sense on its
> own". To most users, it will probably be "This topic should 
> not generate
> output" vs "This topic is a normal topic". So, a few unlikely 
> suggestions:
> attribute - processingrole, topicusage, topicrole ...
> values - primary/extra, useful/notReadable, render/accessContent, ...
> 
> Maybe somebody else can think of better values?
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> "Su-Laine Yeo" <su-laine.yeo@justsystems.com> wrote on 
> 02/04/2009 02:17:41
> PM:
> 
> > RE: [dita] Map structure and possible new attribute for conref push
> > and anchorref
> >
> > I don't yet have a firm opinion on whether we should try to fix the
> > conref push feature by adding a new attribute or whether we should
> > drop the conref push feature entirely. However, I'd like to point
> > out that conref push is just one of the features that depends on the
> > new attribute. If I understand the specs correctly, the new
> > attribute is also needed in order to use the keyref feature and the
> > anchor/anchorref feature in all the ways they are intended 
> to be used.
> >
> > Su-Laine
> >
> >
> > Su-Laine Yeo
> > Interaction Design Specialist
> 
> > JustSystems Canada, Inc.
> > Office: 778-327-6356
> > syeo@justsystems.com
> > http://na.justsystems.com
> >
> >
> >
> >
> > From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
> > Sent: Wednesday, February 04, 2009 7:32 AM
> > To: Grosso, Paul
> > Cc: dita@lists.oasis-open.org
> > Subject: RE: [dita] Map structure and possible new attribute for
> > conref push and anchorref
> >
> >
> > Hi Paul,
> >
> > I agree this is an important change, and it's unfortunate it wasn't
> > caught before. As the original proposer of the feature, I thought
> > the TOC attribute would be sufficient. But I think Su-Laine makes a
> > good case for creating a new attribute.
> >
> > Having discovered a shortcoming in the feature, we do 
> indeed have two
> choices:
> > - fix it
> > - remove it
> >
> > We haven't had the discussion about removing it, but you're right
> > that we should have that discussion. However, I don't think removing
> > the entire feature (as planned and as already partially implemented
> > by some) is necesarily less disruptive than adding one new attribute
> > with clear semantics and general usefulness.
> >
> > Michael Priestley, Senior Technical Staff Member (STSM)
> > Lead IBM DITA Architect
> > mpriestl@ca.ibm.com
> > http://dita.xml.org/blog/25
> 
> >
> > "Grosso, Paul" <pgrosso@ptc.com>
> > 02/04/2009 10:19 AM
> >
> > To
> >
> > <dita@lists.oasis-open.org>
> >
> > cc
> >
> > Subject
> >
> > RE: [dita] Map structure and possible new attribute for conref push
> > and anchorref
> >
> >
> > Sorry I just noticed this, but I was quite surprised
> > to see we're talking about a major change/addition to
> > DITA 1.2.  I thought we had closed 1.2 to new things
> > quite some time ago.
> >
> > How did the discussion go that had us deciding we could
> > change our minds at this late date and add something new
> > to DITA 1.2?
> >
> > If this is "just" part of the conref push proposal, then
> > why did we just think of it?  The conref push proposal
> > was supposed to be completed months ago.  Perhaps this is
> > evidence that conref push is not ready for DITA 1.2.
> >
> > paul
> >
> > > -----Original Message-----
> > > From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> > > Sent: Tuesday, 2009 February 03 13:42
> > > To: dita@lists.oasis-open.org
> > > 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/topi
> > > cref-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/IssueM
> > > apConvenie
> > > 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_workgr
> > > oups.php
> > >
> > >
> > > 
> ---------------------------------------------------------------------
> > > 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_workgr
> > > oups.php
> > >
> > >
> >
> > 
> ---------------------------------------------------------------------
> > 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]