Re: [dita] Groups - Sample PDF uploaded

[Richard Hamilton <hamilton@xmlpress.net>]

Hi Robert,

I can see why the contains content model you have is worth having. I would argue, as you have, that it's not essential, but wouldn't fall on my sword to keep it out.

However, I think the main purpose of the content model is to show structure, not just a list of elements, and I think the current appearance of the Content Models appendix makes it hard to see the structure.

In particular, parentheses are overloaded in too many ways. Right now, they are used to separate the page numbers, identify repetition (zero or more, etc.), and show grouping. Consider the content model for <messagepanel>:

(<data> (416) or <sort-as> (448) or <data-about> (417)) (zero to many) then
<typeofhazard> (458) then <consequence> (414) (zero to many) then <howtoavoid>
(426) (one to many)

Even though the content model is pretty small, it is hard to figure out what's going on here.

When we were faced with this same problem with DocBook, we chose to use a simple syntax that is reminiscent of DTDs or BNF, but isn't any particular standard. We used "|" for or, "," for then, "*" for (zero or many), "+" for (one or many), and "?" for (optional). If you remove the page numbers and use this notation for <messagepanel>,, you would have this:

(<data> | <sort-as> | <data-about>)*, <typeofhazard>, <consequence>*, <howtoavoid>+

Even without removing the angle brackets, this is much easier to understand, more concise, and captures the same information (minus page numbers). I don't know how hard or easy it would be to do this, but if there is some way to avoid overloading the parentheses so much (for example, by removing the page numbers and possibly using tokens like zero-or-more instead of (zero or more)), I think it would help the readability.

Regarding "containment model," both the "contains" and "is contained by" tables are referred to as "content models" in the appendix. That is, each entry begins with "Content models for <elementname>" and then has two tables, one for "contains" and one for "is contained by." There's no indication that the "is contained by" table is not a content model.

That said, I can see why content model doesn't fit the "is contained by" table. If you retain those tables, I would say something like: "For each element in the base package, this section contains the content model and a list of parent elements that can contain that element." You could then just say, "Elements beginning with the letter x" at the beginning of each section and "Element <element name> (page YYY)" for each element.

BTW, having wrangled some of the same issues with DocBook (and having seen what Norm Walsh had to do to make the DocBook Definitive Guide), I can sympathize with the challenge of getting this kind of document to look reasonable. It isn't easy. I hope my suggestions help and don't make your life too much more complicated:-).

Dick
-------
XML Press
XML for Technical Communicators
http://xmlpress.net
hamilton@xmlpress.net



On Jun 4, 2015, at 14:31, Robert D Anderson <robander@us.ibm.com> wrote:

> Hi Dick,
> 
> Back when I started working on the redesign for content models, I brought up the idea of not shipping the content models in PDF. That idea was rather forcefully shut down - it seems quite a few people find it both critical, even in the PDF.
> 
> I do think it would be nice to remove page numbers from links inside the tables, but I'm less sure about the brackets. Personally, I like that the presentation is consistent with the rest of the spec. I'm guessing Bob could rig up something that identifies it is in a content model table and drops the page number, but I don't want to make promises on his behalf.
> 
> Back in DITA 1.2 we used "contains" and "contained by" as two distinct sections and distinct tables. That has been simplified a bit with 1.3 to one set of models per element. I don't remember any specific thoughts about the terminology "containment model", but it may have come about because "content model" implies just the one direction -- it usually means a list of what the element contains, but not a list of what contains it.
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
> 
> <graycol.gif>Richard Hamilton ---06/04/2015 14:33:34---Here are a few thoughts on the Content Model Appendix: Since the schemas themselves are part of the
> 
> From: Richard Hamilton <hamilton@xmlpress.net>
> To: Kristen Eberlein <kris@eberleinconsulting.com>
> Cc: dita <dita@lists.oasis-open.org>
> Date: 06/04/2015 14:33
> Subject: Re: [dita] Groups - Sample PDF uploaded
> Sent by: <dita@lists.oasis-open.org>
> 
> 
> 
> 
> Here are a few thoughts on the Content Model Appendix:
> 
> Since the schemas themselves are part of the standard, is it necessary to include this appendix in the specification at all?
> 
> It's useful information, but couldn't it be a non-normative, HTML-only, appendix? That would let you remove the page numbers, which would make the content models more readable. I would also suggest removing the brackets on the element names in this section, since they're not needed to avoid ambiguity in this context.
> 
> If you decide to keep this appendix in the PDF version of the spec, I would still remove the page number references (the whole section is in alphabetical order) and also remove the brackets. However, I would keep the page number references in the text at the top of each block (the text that reads: "Content models for <element name> on page XXX"). It would be nice, but not essential, to have a header on each page with the element names (like dictionaries have) so it would be easier to locate a particular element in the appendix.
> 
> Regarding the same appendix, why do you use the term "containment model"? I don't see a distinction between containment model and content model in this context. And I see no reference to containment model anywhere else in the spec (just a couple of passing references to "containment hierarchy").
> 
> Best regards,
> Dick
> -------
> XML Press
> XML for Technical Communicators
> http://xmlpress.net
> hamilton@xmlpress.net
> 
> 
> 
> On May 30, 2015, at 5:22, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:
> 
> > I am going to add some contents here, since I am familiar with the content. (And am procrastinating on cleaning my house before my cleaning lady arrives.)
> > 
> > Folks, when you provide feedback on the spec formatting, please be sure and include not just the page number, but also the number and title of the topic. For example, "2.5.4.1 RELAX NG document-type shell: Coding requirements".
> > 
> > Bob, here's my quick summary; almost everything concerns cross references:
> > • Cross references to <dlentry> elements are not being rendered as links. That happens out-of-the-box with HTML output, and I think Robert and I had forgotten that the PDF style sheets would need to be tweaked to accomplish that.
> > • Including the auto-generated text "on page" for <xref> to topics in the content model appendix just does not work. Let's you and I and Robert put our heads together about this one.
> > • Is there a way to suppress the auto-generated text "on page" when the cross reference is to something that will be rendered on the same PDF page?
> > • We lack styling for the different levels of an unordered list, except for indentaton. (Lower priority)
> > • Regarding the item on page 392, I'm leaving that one to Robert. (I'm not brave enough to venture into that topic.)
> > 
> > Best,
> > Kris
> > 
> > Kristen James Eberlein
> > Chair, OASIS DITA Technical Committee
> > Principal consultant, Eberlein Consulting
> > www.eberleinconsulting.com
> > +1 919 682-2290; kriseberlein (skype)
> > 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
> 
> 
>