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] file naming status (was: hyphens)


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
-----Original Message-----
From: Don Day [mailto:dond@us.ibm.com]
Sent: Tuesday, March 08, 2005 3:05 AM
To: DITA TC list
Subject: [dita] OASIS DITA TC: 08 March 2005 meeting reminder

------------------------------------------------------------------------
Greetings, DITA TC colleagues. This is a reminder for Tuesday's regular
telecon, from 11 AM to noon Eastern.

Public Review wraps up next week, so this is our formal review of what

has come in so far, and dispositions against the comments.  Also, we'll
do a bit of prework for the upcoming 1.1 requirements phase.

USA Toll Free Number: 866-566-4838
USA Toll Number: +1-210-280-1707
PASSCODE: 185771

AGENDA:

0. Minute-taker volunteer

1. Roll call (introduce new prospectives)

2. Review/approve minutes from 8 February
   
http://lists.oasis-open.org/archives/dita/200502/msg00018.html

3. Review comments thus far:
   (Note new Language spec version with context links)
   Lang Ref: http://lists.oasis-open.org/archives/dita/200503/msg00007.html
   Arch Spec: http://lists.oasis-open.org/archives/dita/200503/msg00002.html

4. File naming recommendation for DTD/Schemas


5. 1.1 requirements
   Define a process
   (need volunteer to find mentions of "post 1.0" deferred items in minutes)
   (rank by priority and difficulty) solid things for 1.1; medium effort design
   work candidates for 1.2; big items for 2.0

6. Migration discussion: looking ahead for current users.

7. AOB?


Regards,
--
Don Day <dond@us.ibm.com>
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
11501 Burnet Rd., MS 9037D018, Austin TX 78758
Ph. 512-838-8550   (T/L 678-8550)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
       --T.S. Eliot



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]