Numbered lists with per-item titles

Shaun McCance <shaunm at gnome.org>
Mon Feb 20 11:20:37 EST 2012

Hey Phil,

On Mon, 2012-02-20 at 13:49 +0000, Phil Bull wrote:
> Hi all,
> 
> I'm currently writing an introductory guide for software developers,
> and came across a use-case that I don't think the Mallard spec
> currently addresses completely. I would like to have a numbered list
> in the following format:
> 
> 1. Short, emphasised item title (bold)
>     Longer format text which goes into detail about the subject of this point.
> 2. ...
> 
> The reason for this is that I would like to summarise the content of
> each step with a little emphasis, to facilitate scanning of the list,
> and then to have comparatively de-emphasised content that provides the
> detailed information for each point. The idea is that the reader may
> want to skip some steps, but not others. I don't want to make the user
> have to start reading the start of each list item before they decide
> whether to skip it or not.
> 
> I could abuse <steps> slightly to achieve this, like so:
> 
> <steps>
>  <item>
>   <p><em style="strong">Short, emphasised item title</em></p>
>   <p>Longer format text which goes into detail about the subject of
> this point.</p>
>  </item>
> </steps>
> 
> but I think the following would probably be cleaner and less tied to a
> specific processing tool implementation:
> 
> <steps>
>  <item>
>   <title>Short, emphasised item title</title>
>   <p>Longer format text which goes into detail about the subject of
> this point.</p>
>  </item>
> </steps>

This seems pretty clean. It makes some sense for a step to have a
title. One other option I can think of would be if we had some sort
of titled div or formal paragraph. Example (using DocBook syntax):

<steps>
  <item>
    <formalpara>
      <title>Short, emphasized item title</title>
      <p>Longer format text which goes into detail about the
      subject of this point.</p>
    </formalpara>
  </item>
</steps>

We've talked about a formal paragraph in the past. I've never been
totally opposed, but nobody's ever been so strongly in favor for me
to care.

--
Shaun