Bug 687894

The style for this was removed in 511404 after discussion off list. Please discuss any proposed changes on the publican list to get consensus for change.

From what I can see in 511404, the original request was to replace bullet points on alternative steps with alphabetic characters, and to add a text tag ("optional" or similar). I agree that it shouldn't have a text tag, but can we get the alphabetic characters added in please?

Thanks,
LKB

What I originally wrote here follows, but at least with Publican 2.6, which I installed just an hour ago, steps inside <stepalternatives> are being rendered with letters again. Is it just me, or is this bug now fixed?

<original>
I agree with Lana that the alphabetic letters should be added back to stepalternatives, which would allow them to at least be used again (they're unusable at present because there's no visual demarcation of steps inside of them). Text labels re easily added by the author.

A text tag on stepalternatives should be the focus of a discussion/upstream change/separate RFE bug, but that shouldn't hold back their functional re-enablement (this bug).

Thanks,

Silas

Nevermind comment 3! As Jarek pointed out, I was looking at <stepalternatives> inside a <step> with <substeps> and got dizzy. 

So this bug is not resolved.

Changed stepalternatives list style to upper-alpha.

Applied change to branches/publican-2x and trunk.

Committed revision 1909.

Confirmed stepalternatives now appear with alphabetic letters.

OS: Fedora 16
Publican: 3.0
Release designation: publican-3.0-0.fc16.t166.src.rpm

I disagree with the fix:
stepalternatives should render as bullet list items, while substeps are rendered as alphabetic letters.

Meta thought: stepalternatives should be an authorial flag to re-consider the procedure’s basic construction.

That aside, assuming stepalternatives are the best option in a given procedure, having them delineated by a distinguishable mark (eg a letter) does make it possible to reference the particular stepalternative elsewhere in the procedure.† This is potentially more useful to a reader than undistinguishable dingbats.


† This brings the meta thought above back into play however: if you’re referencing earlier stepalternatives later in a procedure, my reflexive thought is the entire procedure needs re-structuring.

The sample structure given in comment #1 above, for example, could be re-structured thus to avoid stepalternatives:

<procedure id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_5_and_6-Linux-RPM">
	<title>Stopping HTTP on Red Hat Enterprise Linux 5 and 6</title>
		<para>
		Follow this procedure to stop <classname>httpd</classname>:
		</para>

			<step>
				<para>
				 At the shell prompt, become the root user.
				</para>
			</step>

			<step>
				<para>
				Run the following <command>stop</command> command:
				</para>
			</step>
</procedure>

<procedure id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_4-Linux-RPM">
	<title>Stopping HTTP on Red Hat Enterprise Linux 4</title>
		<para>
		Follow this procedure to stop <classname>httpd</classname>:
		</para>

			<step>
				<para>
				 At the shell prompt, become the root user.
				</para>
			</step>

			<step>
				<para>
				Run the following <command>stop</command> command:
				</para>
			</step>
</procedure>

The above is longer but forks the reader’s attention before they begin following any steps in the procedure at all. This reduces the likelihood of error on the reader’s part considerably.

Hi Brian,
I would like to note:

> Meta thought: stepalternatives should be an authorial flag to re-consider the
> procedure’s basic construction.

If I am using stepalternatives (in this case), I am actually going out of my way to explain to the user things that are not really within the scope of the guide in this case:
I could have written: "Stop the httpd daemon." and not provide the exact commands for individual rhel versions; this would imply I should
reference rhel documentation on how to stop a service.
What I was trying to achieve (and am trying to achieve with
stepalternatives) is to prevent the user from having to go to another
resource and "click around" in the wikipedia style to achieve a single thing:
As stated in the DocBook Guide:

The |stepalternatives|
<http://docbook.org/tdg/en/html/stepalternatives.html> element was added
to support the semantics of alternative steps: perform exactly one of
the following steps. The reader is presumably given some criteria for
deciding which one to choose, but the significant difference is that
only one of the steps is performed.

If we claim that stepalternatives is not correct practise, then the next thing I would like propose is to pick 40 elements from DocBook and forget about the rest... and there goes DITA and Mallard. Why are we still using DocBook then?
>
> That aside, assuming stepalternatives are the best option in a given procedure,
> having them delineated by a distinguishable mark (eg a letter) does make it
> possible to reference the particular stepalternative elsewhere in the
> procedure.† This is potentially more useful to a reader than undistinguishable
> dingbats.

I am not aware of any use case when I would reference a stepalternatives element:
if I were in need of doing that, I would definitely not use the
stepalternatives tag but split the procedure as you did further below. If referencing then referencing the parent step.

>
>
> † This brings the meta thought above back into play however: if you’re
> referencing earlier stepalternatives later in a procedure, my reflexive thought
> is the entire procedure needs re-structuring.
>
> The sample structure given in comment #1 above, for example, could be
> re-structured thus to avoid stepalternatives:
>
> <procedure
> id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_5_and_6-Linux-RPM">
>   <title>Stopping HTTP on Red Hat Enterprise Linux 5 and 6</title>
>    <para>
>    Follow this procedure to stop<classname>httpd</classname>:
>    </para>
>
>     <step>
>      <para>
>       At the shell prompt, become the root user.
>      </para>
>     </step>
>
>     <step>
>      <para>
>      Run the following<command>stop</command>  command:
>      </para>
>     </step>
> </procedure>
>
> <procedure id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_4-Linux-RPM">
>   <title>Stopping HTTP on Red Hat Enterprise Linux 4</title>
>    <para>
>    Follow this procedure to stop<classname>httpd</classname>:
>    </para>
>
>     <step>
>      <para>
>       At the shell prompt, become the root user.
>      </para>
>     </step>
>
>     <step>
>      <para>
>      Run the following<command>stop</command>  command:
>      </para>
>     </step>
> </procedure>
>
> The above is longer but forks the reader’s attention before they begin
> following any steps in the procedure at all. This reduces the likelihood of
> error on the reader’s part considerably.

I really think that this is too atomic: there is only one step that is
different for individual rhel versions.
Also, please, consider that I am actually going out of my way on this
occasion and explaining to the user things I don't really have to.
If I were writing about how to stop a daemon, I would definitely agree
that it is good practise to split this in two procedures; however, the procedures would not appear in one guide anyway and therefore make no sense at all.

I also would like to add Stephen's (swadeley) comment, which covers another use case for stepalternatives:
"As I understand it, step alternatives would follow after a question: Do You want tea or coffee?
Why would you send someone directly to one of the alternatives? You either send them to the question or head of the decision tree so they can make an informed choice or just copy the bit that says 'Press this button for coffee'. Sending them to the middle of a list of choices when you don't want them to have a choice is perverse."