Re: [dita] DTD Formatting: Element Alignment

[Eliot Kimber <ekimber@innodata-isogen.com>]

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