Bug 687894 - rendering of steps inside stepalternatives
rendering of steps inside stepalternatives
Status: CLOSED CURRENTRELEASE
Product: Publican
Classification: Community
Component: publican (Show other bugs)
2.5
Unspecified Unspecified
unspecified Severity unspecified
: 3.0
: ---
Assigned To: Jeff Fearn
Ruediger Landmann
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2011-03-15 12:46 EDT by Eva Kopalova
Modified: 2013-09-30 19:29 EDT (History)
9 users (show)

See Also:
Fixed In Version: 3.0.0
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-10-30 23:11:09 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:


Attachments (Terms of Use)

  None (edit)
Description Eva Kopalova 2011-03-15 12:46:10 EDT
Description of problem:
Steps nested in stepalternatives are only indented.

Version-Release number of selected component (if applicable):


How reproducible:
render this:
<procedure id="proc-Stopping_HTTP-Linux-RPM">
<title>Stopping HTTP</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>
<stepalternatives>
	<step>
	<para>
	On Red Hat Enterprise Linux 6 or Red Hat Enterprise Linux 5:
	</para>
	</step>
	<step>
	<para>
	On Red Hat Enterprise Linux 4:
	</para>
	</step>
</stepalternatives>
</step>
</procedure>

Steps to Reproduce:
1. 
2.
3.
  
Actual results:
steps in stepalternatives are only indented.

Expected results:
I would expect them have bullets. 

Additional info:
Comment 1 Jeff Fearn 2011-07-21 06:24:27 EDT
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.
Comment 2 Lana Brindley 2011-07-25 16:47:04 EDT
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
Comment 3 Douglas Silas 2011-07-26 03:02:00 EDT
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
Comment 4 Douglas Silas 2011-07-26 08:56:16 EDT
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.
Comment 5 Jeff Fearn 2011-10-10 07:00:27 EDT
Changed stepalternatives list style to upper-alpha.

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

Committed revision 1909.
Comment 6 Misha H. Ali 2012-04-20 03:30:58 EDT
Confirmed stepalternatives now appear with alphabetic letters.

OS: Fedora 16
Publican: 3.0
Release designation: publican-3.0-0.fc16.t166.src.rpm
Comment 7 Eva Kopalova 2012-04-24 11:46:26 EDT
I disagree with the fix:
stepalternatives should render as bullet list items, while substeps are rendered as alphabetic letters.
Comment 8 Brian Forte 2012-04-25 23:06:49 EDT
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.
Comment 9 Eva Kopalova 2012-04-26 10:17:15 EDT
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."

Note You need to log in before you can comment on or make changes to this bug.