OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: Discuss list processing expectations


Hi Robert,

I'm copying the TC list to get this out for general comment, as you suggested.

Robert> I am happy to say that the output is implementation dependent

So am I. I think we should say this, and then add a few best practice rules ("should", not "must").

Robert> However, I am also happy to say that a leading paragraph should not create an extra break at the start of the list

As a best practice, I feel we should discourage mixed content. I know some folks at IBM pride themselves on the way they mix content, but from my experience most people adopting DITA don't have the broad SGML and XML background that some of the power DITA mixed-content users have. I think we should discourage mixed content, such as:

<li>This is a sentence in the first paragraph<p>This is now a second paragraph in the list item</p><p>And this is a third paragraph</p>And here is paragraph number four!</li>

While this is perfectly valid DITA XML, it's extremely badly marked up.

I feel that we should encourage users to be consistent within a list. So if one of the list items in a list contains a paragraph, they should mark all <li> elements up with <p>, as follows:

<ul>
  <li><p>A simple list item.</p>
  <li><p>A list item with multiple paragraphs.</p>
      <p>This is the second paragarph.</p></li>
  <li><p>Another simple list item.</p>
</ul>

If a list contains only simple list items (i.e., phrases, not paragraphs) then the <p> wrapper can be omitted (note that I personally don't like this rule, but I'm OK with the spec saying this to avoid users from being forced to add <p> where arguably they are not paragraphs). Here's an example:

<ul>
  <li>apples</li>
  <li>oranges</li>
  <li>pears</li>
  <li>tomatoes and cucumbers</li>
</ul>

As I mentioned, I prefer the DocBook approach that would include a <p> element inside each of these <li> elements. The end result is much more consistent and stylesheet maintenance is a bit easier.

The next issue (which you didn't mention) is nesting <ul> and other lists inside <p>, such as:

<p>Please remember to eat at least two of the following every day: <ul><li>apple</li><li>orange</li><li>lemon</li><li>tomatoe</li></ul>.<p>

Aside from the messed up output this will generate (unless you code intelligence in the stylesheets to insert punctuation etc) it will have negative translation side effects (is <ul> a block or inline element?) I think we listed <ul> as a block element, so it should not be used as an inline element. I often find users marking up as follows:

<p>In order to install Acme Pro Plus Plus, your system must meet the following requirements:
<ul>
  <li>Pentium 4 CPU or later</li>
  <li>1 GB RAM or more</li>
  <li>At least 350 MB free disk space</li>
</ul>
</p>

IMO, this should be marked up as follows, with the <ul> being a following sibling of <p>, not a child of <p>:


<p>In order to install Acme Pro Plus Plus, your system must meet the following requirements:</p>
<ul>
  <li>Pentium 4 CPU or later</li>
  <li>1 GB RAM or more</li>
  <li>At least 350 MB free disk space</li>
</ul>

I think this is all I have to say about lists ;-)

What does the rest of the TC think?

Gershon
 
Gershon L Joseph
Director of Technology and Single Sourcing
Tech-Tav Documentation Ltd.

Secretary, OASIS DITA Technical Committee
Secretary, OASIS DITA Translation Subcommittee
Member, OASIS DocBook Technical Committee


+972-8-974-1569 (direct)
+972-57-314-1170 (mobile)
http://www.tech-tav.com

----- Original Message ----
> From: Robert D Anderson <robander@us.ibm.com>
> To: Gershon L Joseph [Tech-Tav] <gershon.joseph@tech-tav.com>
> Sent: Monday, April 7, 2008 8:33:19 PM
> Subject: Re: Discuss list processing expectations
> 
> Hi Gershon,
> 
> Sorry I did not get with you on this sooner. I am going back to determine
> what needs to be done, and it looks like I was just supposed to send
> something to the list to provoke discussion. I do not have a strong opinion
> on what should be done, but I think you probably do, because you wanted to
> help on this. What are your thoughts?
> 
> My thoughts are -
> * I am happy to say that the output is implementation dependent
> * However, I am also happy to say that a leading paragraph should not
> create an extra break at the start of the list
> * I also know that some users do include a paragraph in the middle of a
> list, so I would not want to say that paragraphs in a list are ignored.
> That is, if I have <li>text<p>paragraph</p></li> I would not expect the
> contents to run together, just as I would not expect
> <li><p>one</p><p>two</p></li> to run together.

> Does that make sense?  Is there anything else you want to say about it? If
> you would like to send a note to the list in the morning, I think it is OK
> for you to do so. If you do not agree with my comments, that is still fine
> ... it would just be good to get something started on the list.
> 
> Thanks -
> 
> Robert D Anderson
> IBM Authoring Tools Development





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]