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)
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
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