Title: RE: [dita] DTD Formatting: Element Alignment
Agreed,
For any of us looking through bifocals or trifocals, anything that makes
reading easier is a definite plus.
JoAnn
-----Original Message-----
From: Rob Frankland
[mailto:]
Sent: Wed 8/25/2004 9:08 AM
To: ; 'Deborah Aleyne Lapeyre'
Cc:
Subject: RE: [dita] DTD
Formatting: Element Alignment
I have documented a fair number of APIs and from that
experience like
Deborah's approach better. I find it much easier to
visually parse her
suggested format than the long snake like
format.
Rob
Rob Frankland, President & CEO
Rascal
Software
1511 3rd Ave, #523
Seattle, WA
98101
206-624-7300
-----Original Message-----
From: Eliot
Kimber [mailto:]
Sent:
Tuesday, August 24, 2004 3:25 PM
To: Deborah Aleyne Lapeyre
Cc:
Subject: Re: [dita] DTD Formatting: Element
Alignment
Deborah Aleyne Lapeyre wrote:
> ELEMENT
alignment:
>
> 1) It's personal I know, Eliot, and I can live with
your format.
> It is more important that we be consistent than that we
agree.
> But in a large and complicated content model (20-50 elements)
the
> every line format is, IMO, very hard to read.
And I feel
just the opposite--I find your style very hard to read :-)
Partly it's
what you're used to.
> When I need to read your models, I use a
graphical tool.
Indeed. Near and Far is really the only way to explore
DTDs.... (note I
didn't say "create").
>
> 2) Quickly, now,
is foo on the same level as bar or as the group:
The group--just count
the leading parens and scan down. Part of my syntax
depends on careful
alignment of tokens at the same level of indention. This
is essentially the
same as scheme/lisp-style indention.
> <!ELEMENT
foo
> ((bar |
>
baz)+,
> foo*)
> See what I
mean?
> 2) The models above may not be too different
from:
>
>
> <!ELEMENT foo ( (bar
| baz)+, foo*)
>
>>
>
> <!ELEMENT
bar ( (foo | baz)+,
woo*)
>
>>
>
> But I know which I'd rather read,
especially if there are multiple
> element declarations and I want to
eyeball the result as a comparison.
> Further, I can scan element names
quickly, even if the models are long.
I guess I've grown to really
dislike long snaky content models that go on
for line after
line.
One advantage to the one-token-per-line approach is that it makes
it very
easy to add and remove tokens from groups and helps to reduce
typos.
I will admit that it takes a little getting used to at first,
but once you
do you have a very hard time working with any other
declaration format. This
was my experience when we first started using it
for HyTime . I resisted but
then became a believer.
I guess it's a
little like Python in that regard....
> 3) The "as much as seems
reasonable on a line" also lets you edit for
> readability and do things
like the example below. Admittedly, this is
> a TERRIBLE content model
used for teaching and not for real, but you
> get the
idea:
>
> ( (title,
> ( (chptitle,
para*)+ |
> (sectitle, para*,
(chptitle, para*)+ )+
> )
>
)*, index
> )
I find this format really hard to parse because
I've got to look closely
to determine if it's an OR group of three
groups or an OR group of two
groups.
>
>
versus
>
> ((title,
>
((chptitle,
> para*)+
|
>
(sectitle,
>
para*,
>
(chptitle,
>
para*)+)+))*,
> index)
You didn't didn't indent
this correctly. It should be:
((title,
((chptitle,
para*)+
|
(sectitle,
para*,
(chptitle,
para*)+)+))*,
index)
Indented this way it becomes much
clearer (to my eyes) that the content
model is a sequence of two, the firs
group is then an OR of two groups, and
so on. This is entirely dependent on
correct indention--you just scan down
the left side of the model and you
can quickly identify the siblings, then
you can step into the individual
siblings.
Like I said I'll live with any style but I have found over
the years that my
one-per-line approach has served me
well.
Cheers,
E.
--
W. Eliot Kimber
Professional
Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX
78759
(512)
372-8122
www.innodata-isogen.com
