RE: [dita] DTD Formatting: Element Alignment

["Rob Frankland" <robf@rascalsoftware.com>]

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:ekimber@innodata-isogen.com] 
Sent: Tuesday, August 24, 2004 3:25 PM
To: Deborah Aleyne Lapeyre
Cc: dita@lists.oasis-open.org
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

eliot@innodata-isogen.com
www.innodata-isogen.com