Red Hat Bugzilla – Bug 840296
RFE: "Process:" rendering
Last modified: 2014-10-19 19:01:09 EDT
Created attachment 598310 [details]
Process rendered in html-single
Currently the Process: keyword is injecting structural metadata into topics.
Attached is a graphic of a Process: rendered in html-single.
I can't release the book with that much chrome for the Process.
I propose that we do two things:
1. use role attributes on generated and injected links and text, to enable us to customise the display according to the brand (which means that we could even suppress it in css or xsl for given outputs).
2. (a) Dynamically assemble a topic that is the Process topic. It is just a section with the title of the Process, and an itemized or orderedlist of the participants in the process. If we make it an itemizedlist with a role, then we can turn numbers on and off in css.
2. (b) Inject a single <xref> link at the top of each topic that is a participant in the Process, with the Process topic as the linkend.
The result of this will be much lighter chrome that is more customisable, and readers will still be able to get all the metadata that they are getting now, just in a more concentrated fashion. If they need to know what's next or previous, they are always just one click away from the Process topic with its linked list of steps in the Process.
OS: Fedora release 16 (Verne)
JAVA: java version "1.7.0"
Java(TM) SE Runtime Environment (build 1.7.0-b147)
Java HotSpot(TM) Client VM (build 21.0-b17, mixed mode, sharing)
1) I'll add parameters to the xref's and itemized lists. Some of these already exist but they are using roles when they should be xrefstyle's.
2) You can't do that as it needs the prev/next links in the topic, otherwise a process becomes useless as you have to keep going back up and down to see the next/previous stages. We've had issues with that already in Skynet and it just breaks the readers flow.
Added in 0.26.0
An example of the output is as follows:
<title role="process-next-title">Next Step in <link linkend="..." xrefstyle="process-next-title-link">...</link></title>
<xref linkend="..." xrefstyle="process-next-link"/>
For previous links:
<title role="process-previous-title">Next Step in <link linkend="..." xrefstyle="process-previous-title-link">...</link></title>
<xref linkend="..." xrefstyle="process-previous-link"/>
Great, thanks for 1 - I'll work on styling it in my brand.
For (2), if you're reading it in html-single, then the next step in the Process is the next piece of text on the page.
If you're reading it in html, then you keep the Process page open, and click on each link to open in a new tab, perform the step, close the tab, then click on the next step.
I think the other thing about (2) is that you can separate it into two separate things:
(i) Build a dynamic overview topic with the steps in it (just a list of xrefs)
(ii) Suppress the next and previous links in each step
Even if you disagree with (ii), that's ok. Since it has a style it can be suppressed in css on a brand-by-brand basis.
So implementing (i) shouldn't be a detraction from anyone's experience.
If you want 2) then let me know and I'll make a new bug (or you can do it yourself) because i'm going to mark this ON_QA since 1) was completed and released.
And just for reference I do disagree with two but I agree with your first point at a basic glance. The reason is that you still are forced to go back and forth between content which is something from feedback and review that didn't work well. However having the dynamic overview shouldn't effect anything but I'll have to have a look as I have a feeling that you will end up with multiple Table of Contents type views which isn't a good idea either.
If you include the overview and the injected links in each topic then you're not forced to go back and forth, but you *can*.
In the TOC it would appear like this:
23. Installing a New Node
23.1 Install a New Node Process Overview
23.2 Get the Binaries
23.3 Provision a new machine
23.1 would be the auto-generated process overview, and would be a linked-list of the steps.
I see what you mean, that 23 would have a publican-generated TOC that would be very similar, and potentially the same as 23.1.
So I'd say for now to leave (2) until we see some more use in production.
The RHEV guys took the Processes out of their books, so I don't have an example in the wild to examine atm. They asked for the untitled lists to essentially generate multiple Process overviews using the same task topics.
Closing and setting as current release as no QA was performed by the original reporter. If there is still an issue with this bug still than please re-open it.