dita — archive

[Paul Grosso]

 MHonArc v2.5.0b2 -->
















dita message






[Date Prev]
 | [Thread Prev]
 | [Thread Next]
 | [Date Next]

--

[Date Index]
 | [Thread Index]
 | [List Home]








Subject: RE: [dita] file naming status (was: hyphens)




From: "Paul Grosso" <pgrosso@arbortext.com>
To: "Esrig, Bruce \(Bruce\)" <esrig@lucent.com>,"DITA TC list" <dita@lists.oasis-open.org>
Date: Tue, 8 Mar 2005 10:07:47 -0500









Good summary.
 
One point though. The original reason I raised this issue 
wasn't because
hyphens would be prettier.  It was because I thought 
there was an
obvious typo in the spec.  That is, the inconsistent 
use of hyphens
and underscores was confusing enough to me (no DITA expert, 
but
someone who has read the specs several times) that I was 
sure it
was a typo.
 
Granted, I may be more easily confused on these points than 
many
of the rest of us on this committee, but I suspect I won't 
be the only
person from the world of potential DITA users out there 
that will find
the current scheme somewhat confusing.
 
At least, if we don't change the file name scheme, we need 
to add
some much more explicit explanation that makes what is 
inherently
confusing much clearer.
 
paul



  

  

  From: Esrig, Bruce (Bruce) 
  [mailto:esrig@lucent.com]
Sent: Tuesday, 08 March, 2005 
  8:53
To: DITA TC list
Cc: 'Don Day'
Subject: RE: 
  [dita] file naming status (was: hyphens)


  

  
For 
  today's agenda, here is supporting information summarizing the discussion on 
  ...
  
 
  
File 
  naming for the DTD and schema files.
  
 
  
This 
  was first raised as a cosmetic issue (hyphens would be prettier), but there is 
  more behind it:
  
 - is there a need for filenames that better convey the contents 
  of the files and their relationships?
  
 - is this a good time to make that change, and is it worth the 
  effort?
  
 - do we have agreement on what we would change 
  to?
  
 
  
There has been some discussion off the list, which broke down roughly 
  as follows.
  
 
  
Meaningful filenames:
  
 - there is a relationship between the name of the file and its 
  function in the architecture (E. Hennum)
  
 - there are conventions inside the files that enable the savvy 
  specializer to work in a flexible way (E. Sirois)
  
 - how savvy should specializers be, and how much documentation do 
  we have / need on how to understand the files? (B. Esrig)
  
 
  
Good 
  time to change:
  
 - will DITA 1.0 be adopted more widely than the pre-releases? If 
  so, we are broadening the base.
  
 - will DITA 2.0 require incompatible changes? If we promise a 
  renaming tool, then any filename changes could be 
postponed
  
 - when does DITA 1.0 need to be available?
  
 
  
Agreement on what to change to:
  
 - OASIS has a naming convention in the works, although file names 
  may be exempted
  
 - one set of lexical suggestions for the naming 
  convention (B. Esrig) is:
  
       o hyphens as major dividers 
  among semantically distinct components of an identifier
  
       o hyphens could be optional in 
  "small suites" of identifiers
  
       o camelCase as a compounding 
  tool within a component that consists of multiple words
  
 - OASIS has a whole hierarchy of semantically significant 
  components, which would be used in order if used
  
 - The DITA TC claims that DITA artifacts (at least the file names 
  of the sample implementation) do not need to begin with the product name DITA 
  because they will be distributed in a DITA-specific folder (E. 
  Hennum)
  
 - The filenames in the DITA sample implementation could in 
  principle use a sequence of semantically distinct components (maybe just two 
  levels) as suggested by the OASIS naming convention (B. Esrig). For example, 
  it would be possible to clarify which files define a domain by having those 
  file names end in "-dom" (followed by a period and an 
  extension).
  
 
  
Bruce Esrig
  
Information Developer / Information Architect
  
Lucent Technologies