OASIS Darwin Information Typing Architecture (DITA) TC

Good 
clarification.
 
I assume the default value for 
@locktitle is "yes". (I see #IMPLIED in the description but I don't see the 
default value stated.) If so, it appears to me that the normal precedence 
in a <topicref> is:

  

  
<navtitle> if present; 
  if not
  

  
@navtitle if present; if 
  not
  

  
<title> in the 
  referenced topic, or in a referenced <topicref> the title 
  content according to these rules (recursively). 
If @locktitle="no" then (3) 
is the only option, the title content comes from the referenced element.
 
It would be helpful to pull the combined effect of these into a 
single statement along these lines. Readers can get confused as 
they integrate narrowly-focused statements that are found in different 
places.
 
    /B



  

  

  From: Su-Laine Yeo 
  [mailto:su-laine.yeo@justsystems.com]
Sent: Thursday, August 26, 
  2010 7:42 PM
To: dita
Subject: [dita] Clarification needed 
  on @locktitle behaviour


  

  
Hi 
  everyone,
  
I agree with some issues that 
  Doug raised earlier, below. The name "locktitle" has confused a lot of people. 
  
  

  
Doug: 
  We can't change the name of the attribute until DITA 2.0, 
  because DITA 1.2 and 1.3 have to be backwards-compatible. I've started a wiki 
  page for DITA 2.0 proposals at http://wiki.oasis-open.org/dita/DITA_2.0_Proposals and added it there.
  
However, the draft DITA 1.2 spec could be 
  clarified. The description on page 34 of the PDF file currently says: 
  
  

  
"locktitle
  
Specifies whether processors 
  should use the content of the <navtitle> element or the @navtitle 
  attribute for a navigation title."
  

  
Page 1161 could also be 
  clarified:
  
"This attribute makes sure the navtitle element or attribute is 
  used if it is present. If locktitle isn't set to “yes”, the navtitle 
  is ignored and text is retrieved from the target."
  
If a 
  definition needs to be in both places, we should make them both 
  say the same thing (conref, anyone?). I 
  suggest:
  
"If locktitle is set to 
  "yes", the <navtitle> element or @navtitle 
  attribute is used if it is 
  present. Otherwise, 
  the navtitle is ignored and the 
  navigation title 
  is 
  retrieved from the referenced file."
  

  
Cheers,
  
Su-Laine
  

  
Su-Laine Yeo
Solutions Consultant 
  
  
JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com
  
www.justsystems.com 
  
XMetaL Community Forums: 
  http://forums.xmetal.com/
  

  

  

  


                                                

					
                                                    

        
                                                
				

                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----

  
From: Doug Morrison [mailto:dmorrison@dita4all.com] 
  
  
Sent: Thursday, August 12, 2010 
  2:03 PM
  
To: dita
  
Subject: [dita] DITA 1.2 Review 
  Comment: Thoughts on topicgroup, navtitle, and locktitle
  
<snip>
  
Furthermore, here and elsewhere, why use the name 'locktitle' for 
  the attribute? Does locktitle="yes" mean a title is being locked in or locked 
  out, and which title is being locked in or locked out (navtitle or title)? Why 
  choose a name for the attribute that makes the user guess?
  
A name like 'usenavtitle' would 
  remove the guesswork. The attribute assignment usenavtitle="yes" means use the 
  navtitle, otherwise use the title from the referenced topic…
  
<snip>

  
    
    
  
  
    On 27/08/2010 16:41, Bruce Nevin (bnevin) wrote:
    
6D6F1AB5D0078540A309D4BACDCFA8E6026111ED@XMB-RCD-104.cisco.com" type="cite">I assume the
          default value for @locktitle is "yes". (I see #IMPLIED in the
          description but I don't see the default value stated.) 

The default value for @locktitle is "no". To quote from its
    description in
    http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/topicref-atts.html
    :

This attribute makes sure the navtitle element or attribute is used
    if it is present.
    If locktitle isn't set
    to "yes", the navtitle is ignored and text
    is retrieved from the
    target.

I.e. if you want to use a navtitle you have to explicitly set
    locktitle to "yes" - hence its default, implied value must be "no".
Regards,

Doug Morrison
Information Architect
http://dita4all.com


  

I don't know where I was 
looking, that I couldn't see the default. Weird.
 
The purpose of @locktitle is to 
compel the processor to use the navtitle. By default (when locktitle="no"), the 
processor uses other criteria to determine whether or not to use the 
navtitle if it is present. So we talk about what those other criteria might 
be?
 
If locktitle="yes" but there is 
no navtitle specified, do we leave it up to the implementer to decide whether to 
ignore it or report a user error?
 
    
/B



  

  

  From: Doug Morrison 
  [mailto:dmorrison@dita4all.com]
Sent: Friday, August 27, 2010 5:08 
  PM
To: dita@lists.oasis-open.org
Subject: Re: [dita] 
  Clarification needed on @locktitle behaviour


  
On 27/08/2010 16:41, Bruce Nevin (bnevin) wrote: 
  
6D6F1AB5D0078540A309D4BACDCFA8E6026111ED@XMB-RCD-104.cisco.com" type="cite">I assume the default value for @locktitle is "yes". (I 
    see #IMPLIED in the description but I don't see the default value stated.) 
    

The default value for @locktitle is "no". To 
  quote from its description in http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/topicref-atts.html 
  :

This attribute makes sure the navtitle element or attribute is used 
  if it is present. If locktitle isn't set 
  to "yes", the navtitle is ignored and text is retrieved 
  from the target.

I.e. if you want to use a navtitle you have to 
  explicitly set locktitle to "yes" - hence its default, implied value must be 
  "no".
Regards,

Doug Morrison
Information Architect
http://dita4all.com

If
locktitle = "no" or is unspecified, I don't believe the processor is
expected to use other criteria to determine whether or not to use the navtitle in
the map. My understanding is that in this case, the processor is supposed to ignore
any navtitle in the map.



We
can't change the behaviour until DITA 2.0 at the earliest, but currently everything
about this attribute is un-intuitive. 



Su-Laine



Su-Laine Yeo

Solutions
Consultant 

JustSystems
Canada, Inc.

Office:
778-327-6356

syeo@justsystems.com

www.justsystems.com 

XMetaL Community Forums: http://forums.xmetal.com/











From: Bruce Nevin (bnevin)
[mailto:bnevin@cisco.com]

Sent: Wednesday, September 01, 2010 8:55 AM

To: dita@lists.oasis-open.org

Subject: RE: [dita] Clarification needed on @locktitle behaviour







I don't know where I was looking, that I couldn't see the default.
Weird.

 

The purpose of @locktitle is to compel the processor to use the
navtitle. By default (when locktitle="no"), the processor uses other
criteria to determine whether or not to use the navtitle if it is present.
So we talk about what those other criteria might be?

 

If locktitle="yes" but there is no navtitle specified, do
we leave it up to the implementer to decide whether to ignore it or report a
user error?

 

    /B











From: Doug Morrison
[mailto:dmorrison@dita4all.com]

Sent: Friday, August 27, 2010 5:08 PM

To: dita@lists.oasis-open.org

Subject: Re: [dita] Clarification needed on @locktitle behaviour

On 27/08/2010 16:41, Bruce Nevin (bnevin) wrote: 

I assume the default value for @locktitle is "yes". (I
see #IMPLIED in the description but I don't see the default value stated.) 



The default value for @locktitle is "no". To quote from its
description in http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/topicref-atts.html
:


This attribute makes sure the navtitle element or attribute is used if it is
present. If locktitle isn't set to "yes", the navtitle is ignored and text is retrieved
from the target.


I.e. if you want to use a navtitle you have to explicitly set locktitle to
"yes" - hence its default, implied value must be "no".




Regards,
Doug Morrison
Information Architect
http://dita4all.com