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

[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]

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.

[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]

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]

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

[berniexmeyer]

Good suggestion, thanks for the link. I dood it!

[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.

[LTinker68]

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.)

[Dmuir]

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.

[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]

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]

Added a feature request....I'm really surprised this is not possible.

[chrispitude]

Added a feature request....I'm really surprised this is not possible.

Don't want to dogpile, but FrameMaker can do this.

[Nita Beck]

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

[pacdam]

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]

Sorry I can't say as I've never tried this technique myself. Anyone else?

[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]

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]

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]

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.

[rjplano]

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]

I'm shocked that one can't create a cross-reference to the step number of an ordered list in Flare.

[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?

[Nita Beck]

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 ".

[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