Add procedure steps style for labeled lists

mojavelinux commented 11 years ago

Add a style for supporting a procedure with steps (see example below). I think this can be done with a labeled list style.

<procedure>
  <title>Make a bed</title>
  <step>
    <title>Take off the old sheets.</title>
    <para>
      Remove the old sheets and put them in the hamper.
    </para>
  </step>
  <step>
    <para>
       Do the following sub-steps to finish the procedure.
    </para>
    <substeps>
      <step>
        <para>
          Put on the fitted sheet.
        </para>
      </step>
      <step>
        <para>
          Put on the flat sheet.
        </para>
      </step>
      <step performance="optional">
         <para>
            Form hospital corners with the flat sheet.
         </para>
      </step>
    </substeps>
    <stepalternatives>
       <para>Do one of the following options but not both.</para>
       <step>
         <para>Use a blanket.</para>
       </step>
       <step>
         <para>Use a quilt.</para>
       </step>
    </stepalterhatives>
</procedure>

Here's how this might be defined in AsciiDoc:

[procedure]
.Make a bed
Take off the old sheets:: Remove the old sheets and put them in the hamper.
Put on the new sheets:: Do the following sub-steps to finish the procedure
Put on the fitted sheet:::
Put on the flat sheet:::
Form hospital corners with the flat sheet.*:::
Do one of the following options but not both:::
+
[role="alternatives"]
* Use a blanket.
* Use a quilt.

That's just a rough sketch. We'll have to play around w/ the syntax.

bleathem commented 11 years ago

We use this in RichFaces. Would it be tough to impl? Do new asciidoc definitions have to be "approved" first in the asciidoc project before we implement them in asciidoctor?

mojavelinux commented 11 years ago

The difficulty is in designing the syntax. Implementing in Asciidoctor is not hard.

Ideally, we get this stuff pushed upstream. That is a key mission of Asciidoctor, to move the AsciiDoc syntax forward.

It does not need to go there first, we just want to be sure to follow up with the request.

The only limitation right now in Asciidoctor is not having an extension mechanism. For the time being we have to bake the logic into the core unless it can be done entirely in a custom template.

The next step is settling on a syntax.

bleathem commented 11 years ago

Sounds good. My experience with Asciidoc so far is limited (1 day into it!), so if we need to vet your proposed syntax for procedures we should do so in a wider context. I'll post to the Asciidoctor mailing list looking for feedback on this issue.

mojavelinux commented 11 years ago

Here's a slightly different approach that's based on an ordered list. It gets close to the output we would need, as is...with the exception of the step alternatives.

[procedure]
.Make a bed
. Take off the old sheets
+
Remove the old sheets and put them in the hamper.

. Put on the new sheets
+
.Do the following sub-steps to finish the procedure
.. Put on the fitted sheet
.. Put on the flat sheet
.. Form hospital corners with the flat sheet.*

+
[role="alternatives"]
.Do one of the following options but not both
. Use a blanket.
. Use a quilt.

A bug in Asciidoctor (or just a limitation of AsciiDoc) is preventing the title on the alternative list from showing.

Here's how that renders:

Make a bed

Take off the old sheets

Remove the old sheets and put them in the hamper.
Put on the new sheets
Do the following sub-steps to finish the procedure
1. Put on the fitted sheet
2. Put on the flat sheet
3. Form hospital corners with the flat sheet.*
Use a blanket.
Use a quilt.

mojavelinux commented 11 years ago

Could you link to the use case in RichFaces?

bleathem commented 11 years ago

Thanks for thinking more on this Dan, I'll explore how some of the comparable elements are implemented in asciidoc and provide some concrete feedback.

We use these in RichFaces docs in the following locations:

Developer Guide | Getting started with RichFaces

Developer Guide | Skinning and Themeing

Component Reference | Resources

https://github.com/richfaces/docs/blob/develop/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Resources.xml#L45

mojavelinux commented 11 years ago

The more I think about this, the more I think the focus should be to keep it simple and make it a special type of ordered list with some minor embellishments.

I recently came across an example of procedure steps on the GitHub Help site and I think it's a good representation of what we are looking for.

Here are some examples of them:

https://help.github.com/articles/how-do-i-change-my-primary-email-address https://help.github.com/articles/how-to-change-your-username

Notice the screenshot that is associated with each item. We could reserve a role (which, in HTML, is a style class) on an image in the content of the step and align it to the right as it appears in the GitHub Help.

Here's how the change your username might be written:

= How do I change my username?

[steps]
. image:account-settings.png[role="screenshot"]
Go to https://github.com/settings[Account Settings]

. image:account-settings-admin.png[role="screenshot"]
Click on https://github.com/settings/admin[Account Settings] in the sidebar

. image:change-username-button.png[role="screenshot"]
Click the btn:[Change Username] button

I think that's pretty elegant, but if you think there's a better way, I'd be glad to here it.

bleathem commented 11 years ago

The images are optional? How about support for the docbook alternative steps? Without that, it's really just an ordered list.

mojavelinux commented 11 years ago

Ah yes, I left that out. I think that alternative steps is just a nested list with the role (or option) named "alternatives". In HTML it's a styling issue. In DocBook it's about element selection.

...in the end, though, this really is just an ordered list...which is a good thing. Conceptually, it should be that simple. Behind the scenes, we'll emit the DocBook elements that retain the semantics. We can iterate until we get just the right balance.

mojavelinux commented 11 years ago

Yeah, the images are just optional. It's just if they are there, we'll give them proper layout.

bleathem commented 11 years ago

:+1: for nested ordered lists with a role indicating optional/alternative steps. That's a natural extension of the ordered list, and is a good fit here.

lopsotronic commented 3 years ago

Many thumbs up for this. Watching with great interest. It's a major roadblock for hardware/maintenance procedures, which mandate step numbers in cross reference gentext. Alternatives

On the DB backend, convince Asciidoc to inject the anchor id [[xml:id]] into //listitem/@xml:id instead of going to its own separate element //anchor/@xml:id (actually //listitem//simpara/anchor/@xml:id). If it was \n. [[foo]]Listitem --> <listitem xml:id="foo"><simpara>Listitem</simpara></listitem> then DocBook-XSL could catch the number label out-of-the-box when it styles xrefs. That's standard DBXSL behavior.
Or we could hit the DocBook-XSL customizations and try to grab that listitem number when xref target ancestor=listitem. It's sort of nuts that's not an option, but //anchor can go anywhere, so when you think about it that's a lot of possible ancestors to check for. This would not be much fun. I feel like the work-to-reward ratio for DBXSL customization is quite low however.

asciidoctor / asciidoctor