How do I create a cross-reference to a numbered step?

This forum is for all Flare related Tips and Tricks.
Have a tip or trick you use while working in Flare? Share it here.
Patt
Propeller Head
Posts: 40
Joined: Thu Apr 03, 2008 7:43 am

How do I create a cross-reference to a numbered step?

Post by Patt »

I'm new to Flare and still learning my way around. Here's my question of the day. I have a numbered list and I want one of the steps to be "Repeat steps x - y", where x and y refer to previous steps in the procedure. I want to make x and y a cross-reference to the numbered steps so that when I change the procedure, as I've just done, the right numbers are displayed.

Thanks
forfear
Propellus Maximus
Posts: 766
Joined: Sat Feb 16, 2008 3:37 am
Location: Jungle Jingles

Re: How do I create a cross-reference to a numbered step?

Post by forfear »

You can only do this to paragraphs and headings with auto-numbers in the styles defined.

Repeat x to z.

Numbered steps are a type of special list. They are not paragraphs.
The numbers in list items will not show as you want them to.

Currently there is no option to display the numbers only in numbered steps in List types. You can do it i.e. if your headings are auto-numbered. 1.0 Heading 1, 1.1 Heading 2.

To create cross-reference to numbered steps (option)
Create a new paragraph style i.e MyNumberedSteps
With Auto-Numbers, set each new instance of a step to auto-increase in number, like 'S:{n+}. '
Bookmark the two steps you want cross-referenced. (Insert Bookmark, i.e. Start and End)
Now create a new Cross-Reference Style, called ShowAutoNumbersOnly
For this cross-reference format, set the format to {paranumonly}.
Now insert the sentence

Repeat x and y.

Replace x and y with cross-references to the Start and End bookmarks.

Done.
If you submit your bug feedback request here, the more likely it'll get fixed or included in a future release
Open Utilities PageLayout Resizer for Flare/Blaze | Batch builder
RamBal
Jr. Propeller Head
Posts: 1
Joined: Mon Jul 29, 2013 2:30 am

How do I create a cross-reference to a numbered step?

Post by RamBal »

The following workaround configures the list [li] tags and any style changes to the list are propogated to all list items.

This is a test topic for demonstrating numbered list with cross-reference functionality.
1.After you start this list, open Paragraph Properties dialog (click the paragraph extension icon [\] on the ribbon).
2.Test extra line added above first cross-referred step. (add this line after first implementation of the following procedure).
3. In Enter format (preview below), type {color white}{ }{n+}{/color}. Click OK.
4.Test extra line added between two cross-referred steps.
5.To create a new line, press ENTER key.
6.The cursor position for your first character input will appear misaligned by a single character position.
7.Ignore this misalignment and enter your input for the next line.
8.To create as many line items as required, repeat step 5 to 7 as required.
9.When your required number of lines are created, position the cursor on step 5 and click Insert > Bookmark.
10.In Manage Bookmarks dialog, under New bookmark (do not use spaces), type your bookmark name. Click Add.
11.Repeat steps 9 to 10 on step 7.
12.Click (Insert a Cross-Reference) icon.
13.In the Insert Cross-Reference dialog, under Cross-Reference Properties and XRef Class, select MadCap:xref.
14.Click New.
15.In the New Cross-Reference Style Class dialog, and in XRef Class, type StepXRef as your new style format.
16.In Available commands, select Show Paragraphs Commands.
17.Under Command column, select Paranumonly. Click OK.
18.Apply the newly created cross-reference style format to each bookmark.
19.When you insert an additional line item between step 5 and 7, the cross-referenced step number(s) is updated.
berniexmeyer
Propeller Head
Posts: 35
Joined: Thu Dec 23, 2010 3:09 pm
Location: Oregon, USA

Re: How do I create a cross-reference to a numbered step?

Post by berniexmeyer »

This seems like a feature almost everybody would want at some time or other. The first query was in 2008. So Madcap has had 6 years to think about this. Is it slated to be implemented at some point? Having to create a special paragraph type to pull this off seems unreasonably klugy. Madcap, comments?
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

The best way to urge MadCap is to put in a feature request. The more people who request the same feature, the more likely MadCap is to act. Otherwise, telling your peers here just yields a lot of nodding heads!

You can submit a feature request here: https://www.madcapsoftware.com/feedback ... quest.aspx
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
berniexmeyer
Propeller Head
Posts: 35
Joined: Thu Dec 23, 2010 3:09 pm
Location: Oregon, USA

Re: How do I create a cross-reference to a numbered step?

Post by berniexmeyer »

Good suggestion, thanks for the link. I dood it!
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: How do I create a cross-reference to a numbered step?

Post by ChoccieMuffin »

Added another request. This is a real nuisance, particularly as ALL the other authoring programs I've played with - even Word - allow this really easily.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: How do I create a cross-reference to a numbered step?

Post by LTinker68 »

ChoccieMuffin wrote:Added another request. This is a real nuisance, particularly as ALL the other authoring programs I've played with - even Word - allow this really easily.
The problem is, they're not really analogous. When you use an HTML list, the numbers are not added into the content at all. If you build the output and look at the page code, you still only see <li> tags -- you don't see 1, 2, 3, etc. It's the browser that determines at run time what the value of each <li> is. In order to xref to a specific number, the browser would first have to render the page to determine the resulting list numbers, then re-render the page to fill in the xref with the values that were determined in the first pass. Browsers aren't programmed to do that, so in order to do what you want, Flare would have to add functionality to build a new auto-number sequence at build time, change the HTML list structure (ol and li tags) to paragraphs using that auto-number format, then convert the xref tags to point to the appropriate resulting paragraph item. The above would result in in-page style definitions being created for the auto-number formats and possibly the xref tags, which would bloat the topic code, and those in-page style definitions would override your stylesheet definitions because you'd no longer be using ol/li tags but in-page defined <p> styles. How many people have had problems styling their lists because in order to make a hanging outdent (?) list, Flare has to use a table structure to simulate that effect and people didn't know they had to style the table tags in order to control the look in the output?

If you know you're going to want to xref to a numbered item in a list, then start with the auto-numbered paragraph instead of an HTML list. Once you get the auto-number format set up in the stylesheet, it's just as easy to use that as to use the HTML list, plus you can xref to it. (Well, not quite as easy -- if you want to simulate a list-within-a-list then you have to select a different paragraph class for the first indented item then select the original class when you want to outdent, but that's still not that labor-intensive.)
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
Dmuir
Propeller Head
Posts: 10
Joined: Fri Sep 04, 2015 9:01 am

Re: How do I create a cross-reference to a numbered step?

Post by Dmuir »

LTinker68 wrote:In order to xref to a specific number, the browser would first have to render the page to determine the resulting list numbers, then re-render the page to fill in the xref with the values that were determined in the first pass. Browsers aren't programmed to do that, so in order to do what you want, Flare would have to add functionality to build a new auto-number sequence at build time, change the HTML list structure (ol and li tags) to paragraphs using that auto-number format, then convert the xref tags to point to the appropriate resulting paragraph item.
I disagree with the way you engineered your solution and the reasons why step numbers cannot be supported.

Yes, step numbers are rendered by the browser but they are based on the <li> count and the nesting, which is something that Flare could figure out at build time to to apply the cross references. You would not have to wait for the browser nor would you have to convert anything back to a paragraph.

I am glad someone opened a feature request for this, and I hope the Flare developers implement this idea in a relatively straightforward manner. By the way, cross-referencing often requires multiple passes anyway to adjust for conditional content and shifting page numbers.
David Muir | Technical Writer | Microdea Inc. | Markham ON | Canada
bianca_writer
Propeller Head
Posts: 54
Joined: Tue Mar 15, 2016 9:57 am
Location: Los Angeles, CA

Re: How do I create a cross-reference to a numbered step?

Post by bianca_writer »

I also submitted a feature request for the ability to cross-reference steps, as in:

1. Do this. If this isn't applicable to you, go straight to "Step 3".
2. Do this.
3. Do this.

MadCap has found creative ways to implement features, so I trust that they can figure out a way to do this! :)
rillettes
Jr. Propeller Head
Posts: 1
Joined: Mon May 30, 2016 12:27 pm

Re: How do I create a cross-reference to a numbered step?

Post by rillettes »

Hi all, long time listener, first time caller.

I was dealing with this this morning, and instead of doing any style modification or autonumbering, I went to the step I want to reference. Find the pertinent keyword for that step, i.e. Configure Azure. Create a bookmark for that step, eg. conf_azur. Then, for the cross-reference, I wrote something similar to "As noted in the Configuring Azure step, ...."
Works for me.
Wendy F
Propeller Head
Posts: 29
Joined: Thu Sep 10, 2015 5:24 am

Re: How do I create a cross-reference to a numbered step?

Post by Wendy F »

Added a feature request....I'm really surprised this is not possible.
chrispitude
Propeller Head
Posts: 58
Joined: Thu Mar 23, 2017 12:23 pm

Re: How do I create a cross-reference to a numbered step?

Post by chrispitude »

Wendy F wrote:Added a feature request....I'm really surprised this is not possible.
Don't want to dogpile, but FrameMaker can do this. :)
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

chrispitude wrote:
Wendy F wrote:Added a feature request....I'm really surprised this is not possible.
Don't want to dogpile, but FrameMaker can do this. :)
And so can Flare.

In Flare 2017 r2 (and I believe an earlier version), it is indeed possible to insert a cross-reference to list items, among a wide collection of other things that can also be xref-ed to.
variety of xref targets.png
You do not have the required permissions to view the files attached to this post.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
pacdam
Propeller Head
Posts: 10
Joined: Wed Mar 23, 2016 9:27 am

Re: How do I create a cross-reference to a numbered step?

Post by pacdam »

Nita Beck wrote:
chrispitude wrote:
Wendy F wrote:Added a feature request....I'm really surprised this is not possible.
Don't want to dogpile, but FrameMaker can do this. :)
And so can Flare.

In Flare 2017 r2 (and I believe an earlier version), it is indeed possible to insert a cross-reference to list items, among a wide collection of other things that can also be xref-ed to.
variety of xref targets.png
Thanks Nita. Am I missing something or is there a way for this to state the step number? I can see how to put in a cross-reference to the text in the step but I want it to say, "see step 3", or words to that effect. Thanks.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

Sorry I can't say as I've never tried this technique myself. Anyone else?
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
garyetzel
Jr. Propeller Head
Posts: 4
Joined: Tue Aug 25, 2015 7:32 am

Re: How do I create a cross-reference to a numbered step?

Post by garyetzel »

Regarding the screen shot previously posted, that's not the same thing. You can target a list item with a cross-reference, but you cannot have the cross-reference use the list item number (for example, "step 2"). That is what we are asking for. It's something that would be needed in the definition of the cross-reference format. Flare currently offers things like {paranum} and {paranumonly}, but those do not target list item numbers. They target "paragraphs and headings with auto-numbers in the styles defined", as someone else here mentioned all the way back in 2008.

Any other solutions or work-arounds out there?
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

This: Re: Cross References and Lists (viewtopic.php?f=13&t=26443&p=116778#p116778)
seems to be the current "solution" or work around
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

I also had another idea.
An even more workaroundish workaround, but an alternative nevertheless:
If one is ok with maintaining the numerical sequence of the numbered items by hand, but mainly wants to have automatically updating references of the step's number,
then one could simply create variables for each step number. Then insert the variables both in the "source" location and in each "reference" location as well.
If the numbering needs to change, then the variable must be edited once and it updates in all the places where it is used.

The benefit of this
is, that one can also use numbered steps within one paragraph, even in the same sentence, and still be able to "reference" them. (With the auto numbering system, one needs to create a new paragraph for each new numbered step, as far as I saw.)
debdebtig
Jr. Propeller Head
Posts: 7
Joined: Wed Jan 22, 2014 8:54 am
Location: New Hampshire

Re: How do I create a cross-reference to a numbered step?

Post by debdebtig »

Ok, it's now 6 years since the original post. And, it still doesn't work the way you'd expect. Any updates? I can't believe it still doesn't work. Nina, I did try your version from a separate post, great idea if I had started doing that from the beginning but with the number of topics I've already built I'm not willing to go back and redo them.

:shock: :? :shock:
:flare: 2022r2 :capture: v7
rjplano
Propeller Head
Posts: 51
Joined: Tue May 05, 2020 10:08 am

Re: How do I create a cross-reference to a numbered step?

Post by rjplano »

debdebtig wrote:Ok, it's now 6 years since the original post. And, it still doesn't work the way you'd expect. Any updates? I can't believe it still doesn't work.
Actually, it's been 12 years since the original post on the topic. Somehow I don't think MadCap can/will address this issue.
bcjorden
Jr. Propeller Head
Posts: 5
Joined: Thu Oct 01, 2020 5:22 am

Re: How do I create a cross-reference to a numbered step?

Post by bcjorden »

I'm shocked that one can't create a cross-reference to the step number of an ordered list in Flare.
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: How do I create a cross-reference to a numbered step?

Post by trent the thief »

There is a difference between using a defined Paragraph style that is configured with auto-numbering and simply clicking the "numbered list" button on the tool bar to make an Ordered List. One makes an object that has a numeric reference, while the other is a construct formed when a browser renders it and therefore has nothing that Flare ever sees.

Before griping that Flare can't do something, please be certain that what you are griping about is something that happens within Flare. IMHO, it's a poor practice to use Ordered Lists to make numbered lists in Flare. Just as it's bad practice in Word and every other authoring tool. If you can't reference it, what good is it?
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

trent the thief wrote:There is a difference between using a defined Paragraph style that is configured with auto-numbering and simply clicking the "numbered list" button on the tool bar to make an Ordered List. One makes an object that has a numeric reference, while the other is a construct formed when a browser renders it and therefore has nothing that Flare ever sees.

Before griping that Flare can't do something, please be certain that what you are griping about is something that happens within Flare. IMHO, it's a poor practice to use Ordered Lists to make numbered lists in Flare. Just as it's bad practice in Word and every other authoring tool. If you can't reference it, what good is it?
I respectfully disagree with my esteemed colleague. Using paragraphs with auto-numbering to serve as a numbered list -- instead of using a true ordered list -- is not best practice. Doing so will yield content that is not accessibility compliant. Screenreaders will not recognize the auto-numbered paragraphs as a list.

I would much rather have to figure out a way to refer my readers back to an earlier step in a procedure than to have said procedure as a whole be noncompliant.

I regret that I don't have anything to offer about the core question of this thread: how to cross-reference to a numbered step. I spent a few minutes yesterday at the end of my workday refamiliarizing myself with Flare's xref functionality specifically about list items. Despite Flare's allowing one to select a list item in an ordered list as the destination of an xref, it didn't seem to yield what is expected. I even created a new xref format that would include "Step " in the xref, but I just ended up with something like "See Step ".
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

Hi again,
sorry if any of my following words are nonsense, I currently don't have the newest version of Flare installed and am just brainstorming.

Two thoughts:
1) On the theoretical side, I hear (read) what @trent the thief is saying about "a construct formed when a browser renders it and therefore has nothing that Flare ever sees".
Still, a browser follows certain standardized rules (or should follow them) when rendering a list, and Flare could do the same when evaluating a list. On top of that, html tags (and also list items) can have IDs assigned to them. I think that should make the referencing even easier. But surely it might take some thought and effort to implement it in a fool proof way. It may be hard work and not be worth the effort for Madcap from an economical point of view, but I am just saying, in theory, I assume it could be done.

2) I think @Nita Beck has a good point regarding accessibility. As long as flare cannot easily reference ordered list items, maybe one could still use html-ordered lists (for accessibility reasons) and the Flare-supported autonumbering together and then hide the rendering of the auto-numbering with a short JavaScript, setting visibility to hidden or set the text color for the auto-numbering to 100 % transparent. This really is just a thought. Probably it won't work for one or the other reason, or if it works, it would probably be a messy and error-prone work-around. I did not try it at all. But maybe it is food for thought for someone else.

Regards, me
Post Reply