[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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: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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]