Procedure numbering: autonumber and <p> tag vs. <ol> <li>

[joannak]

Hi
I need to understand the difference between using auto-numbering and ordered lists for procedure steps.

There are problems with ordered lists that I can't seem to overcome: defining a specific indent (which works for html5 and pdfs), deciding whether a sub-list/image should be in the same paragraph (tag) as the parent li or a separate tag, and so on...

A colleague of mine has started trying to use auto-numbering.
As Madcap specifically has a feature for lists (ie <ol>), it goes against my gut feeling to start using auto-numbering.... like using series fields in MSWord instead of auto-numbering (because it never worked properly...)
What is the correct way to work? - and where can I find the best explanation how to set up my <ol> or autonumbers? - whichever is best..... Looking forward to reading your responses/suggestions...
Joanna

[Olin]

I only use the ordered lists for simple lists. I use an auto-numbered paragraph for my numbered, alpha, and roman numeral lists.
My primary reason for doing this is that you can't Xref to a specific step number of an ordered list, but you can if its an auto-numbered paragraph style.

You do need to create a style for the first line in a numbered list, then an additional style for the following lines--just like you would do in FrameMaker.

[joannak]

Hi
I am not a Framemaker user - please can you explain why/how I need to make different style for first line. Thanks.
Joanna

[emsachs]

This may be TMI, but here goes.

Here are my styles for numbered paragraphs:
p.Numbered_First
{
margin-top: 2pt;
mc-auto-number-format: 'N:{n=1}.';
mc-auto-number-position: outside-head;
mc-auto-number-offset: .25in;
margin-left: .25in;
mc-next-class: Numbered;
}

p.Numbered
{
margin-top: 2pt;
mc-auto-number-format: 'N:{n+}.';
mc-auto-number-position: outside-head;
mc-auto-number-offset: .25in;
margin-left: .25in;
}

Let's look at the mc-auto-number-format to see why you need two different styles.

in p.Numbered, the mc-auto-number-format: 'N:{n=1}.' says these things:
* Use a numbering sequence called N. I'll explain this in a bit
* the n=1 part says two things - use a number format n (instead of a letter format) and set the value of this number to 1.
* the . says add a period after your number

Also note the mc-next-class: Numbered; This tells Flare that when you press Return, the next paragraph should be p.Numbered.

Now look at the autonumbered format for p.Numbered
mc-auto-number-format: 'N:{n+}.';

It says something a little different. The n+ here actually says, go look at the previous paragraph with the numbering sequence N. Look at that number, whatever it is, and add 1.

So when you have a sequence of paragraphs:

p.Numbered1
p.Indent
p.Bullet
table (could have numbering)
p.Numbered
p.Numbered
h2
p.Numbered
p.Numbered1

The numbering comes out as
p.Numbered1 1
p.Indent
p.Bullet
table (could have numbering)
p.Numbered 2
p.Numbered 3
h2
p.Numbered 4
p.Numbered1 1

What is happening is that each p.Numbered looks before it and finds the last paragraph that used that numbering sequence N. Then it bumps it up by 1 for the correct number. You don't get reset until you explicitly use p.Numbered1 to reset.

Also, you can have paragraphs with their own numbering sequences in between (for example, H for heading, T for table), and they won't affect this numbering.

In this way you have total control. In Word, you get into trouble because Word tries to guess and you can't stop that. In Flare, it does exactly what you tell it to.

[SteveS]

Autonumbering is far more powerful than using standard ordered lists. You have far more control over formatting, you can run multiple instances of numbering sets, including numbering within numbering, you can continue numbering through multiple topics and so on.

The difficulty is in ease of use, thereis more involved in creating the autonumber styles, rather than just clicking the numbered list button.

[joannak]

Thank you so much. That is a very clear explanation.

[sitapatel]

Can I say a huge 'thank you' too?

I spent most of Friday trying to figure this out!

[BadMichael]

While I was successful in getting Autonumbering to work, strange borders are appearing around my steps. Am I inheriting unwanted attributes from another style?

[ChoccieMuffin]

While I was successful in getting Autonumbering to work, strange borders are appearing around my steps. Am I inheriting unwanted attributes from another style?

Do you have anything set up in your stylesheets for <tr> that includes borders? There's a "gotcha" mentioned in Flare's help about tables being used in the background for things like auto-generated content, so that could be the cause.

[KreepLX]

I disagree that using paragraph steps are superior than ordered lists. I believe the benefits of using ordered lists include:

*Using tabs in the list automatically adjust the style and numbering system type, which is familiar to writers (MS Word Style)
*The writer can nest different list types in levels
*Images can be aligned to levels in the list
*The <ol> style can reduce the overall style list down significantly for standard items, two for each level

Interestly enough, I was able to find a workaround that would allow the mc-auto-number-format lists to work inside of <ol> lists, but it had limitations with alignment. I submitted an enhancement request to fix this issue. I may try to fool around with the CSS later to see if I can fix it with a trick later. Here is the summary of my enhancement request, which may work for you if you want to use the <ol> styles for the above mentioned reasons.

OL List by Level Numbering
The continue sequence option does not work properly for ordered lists if other different list types surround the list. For example:

1. Step
2. Step
a. Step
* Bullet
* Bullet
d. Step (set to continue sequence)
7. Step (set to continue sequence)

To fix this issue, we have to go in and specify the reset number. This can cause issues in the future if we add a step somewhere in between the full list and the writer doesn’t notice the inline position where the specific number was set.

There is a workaround using madcap’s mc-auto-number sequencing to create a reset and continue, associating each level with an appropriate chapter or global numbering ID. To do this, we need to remove the <ol> numbering and add the mc-auto-number-format numbering with an associated level ID to the <li> items.

Removing the OL list-style-type

ol { list-style-type: none; }

Add the mc-auto-number format to the li, along with a reset

li { mc-auto-number-format: 'CX:{n+}. ';}
li.reset {mc-auto-number-format: 'CX:{n=1}. ';}

Using CSS rules, use different levels to assign different numbering systems automatically

li ol li{mc-auto-number-format: 'CY:{a+}. ';}
ol.Alpha li{mc-auto-number-format: 'CY:{a+}. ';}
li ol li.reset {mc-auto-number-format: 'CY:{a=1}. ';}

And so on with a 3rd level Roman numeral numbering

li ol li ol li{mc-auto-number-format: 'CZ:{r+}. ';}
ol.Roman li{mc-auto-number-format: 'CZ:{r+}. ';}
li ol li ol li.reset {mc-auto-number-format: 'CZ:{r=1}. ';}

Limitations
The issue with this <ol> workaround is that these following madcap styles do not work for <li> items:

mc-auto-number-position: outside-head;
mc-auto-number-offset: ;

That forces all instances of numbering to be inside of the head, creating an awkward alignment when the series increases a digit:

1. Step
2. Step
3. Step
4. Step
5. Step
6. Step
7. Step
8. Step
9. Step
10. Step (inside head alignment)

So, if MadCap adds these enhancements, you can easily use <ol> lists and have the benefits of both worlds. You just have to let them know that you want it.

[BadMichael]

FWIW: The <tr> and <td> tags in my CSS were the culprit for the unwanted borders as per ChoccieMuffin's suggestions (Thank you!). That said, I'm sticking with ordered lists for steps in my WebHelp project and will use autonumbering only for Notes, Warnings, and Tips paragraphs only.

[ChoccieMuffin]

FWIW: The <tr> and <td> tags in my CSS were the culprit for the unwanted borders as per ChoccieMuffin's suggestions (Thank you!). That said, I'm sticking with ordered lists for steps in my WebHelp project and will use autonumbering only for Notes, Warnings, and Tips paragraphs only.

Glad I could help.

[SteveS]

I disagree that using paragraph steps are superior than ordered lists...

...So, if MadCap adds these enhancements, you can easily use <ol> lists and have the benefits of both worlds. You just have to let them know that you want it.

Madcap can't add enhancements to tags that are controlled standards. The use of CSS should be limited to the industry standards.

Also be aware that CSS numbering applies to the topic. If you are producing print output, or want the numbering to continue on another web page, using autonumbering will help make sure it works properly.

It's horses for courses, hence the reason some writers (myself included) use either method depending on the circumstances.

[KreepLX]

Madcap can't add enhancements to tags that are controlled standards. The use of CSS should be limited to the industry standards.

Are you talking about the same controlled standards that they added to every other tag that has "mc" in front of it? In fact, every "mc" style in the stylesheet editor was something MadCap added to each tag to work with their application, and it will not work outside of their products. The above additions to the CSS have been tested, and you can try it for yourself. They can easily modify the parser to allow the autonumber position outside the head.

Just because it doesn't show in the GUI, doesn't mean it will not work for other tag styles. A parser is a parser. It even works for the <ol> items, but the position is above the list.

Also be aware that CSS numbering applies to the topic. If you are producing print output, or want the numbering to continue on another web page, using autonumbering will help make sure it works properly.

Even the GUI shows the types of numbering system available in Flare (C, G, or S), so you can add any kind of numbering system you want using the "mc-auto-number-format" string.

The <ol> system does not work properly in Flare, and what I presented was an alternative. It's as simple as that.

It's horses for courses, hence the reason some writers (myself included) use either method depending on the circumstances.

Please don't discourage people from trying to achieve methods you don't use. Users have every right to get into the CSS and try new things. I have been working in Flare for a long time now and write all of my CSS in text.

[SteveS]

Don't confuse xml with html/ css.

Anything prefixed with mc is xml and a transformation applied at build time. While the source content will trip up other applications that do not know how to handle the madcap xml, the output is fine.

At no stage did I discourage you (or anyone else) from using different methods. In fact I did point out I use different methods depending on the circumstances.

BE AWARE THIS IS A PEER TO PEER FORUM. I, NOR ANYONE ELSE, ARE MADCAP EMPLOYEES. If you wish to vent about things that irk you, don't make it personal, or raise it with Madcap. We have no input into program specifications.

[KreepLX]

Don't confuse xml with html/ css.

Anything prefixed with mc is xml and a transformation applied at build time. While the source content will trip up other applications that do not know how to handle the madcap xml, the output is fine.

At no stage did I discourage you (or anyone else) from using different methods. In fact I did point out I use different methods depending on the circumstances.

BE AWARE THIS IS A PEER TO PEER FORUM. I, NOR ANYONE ELSE, ARE MADCAP EMPLOYEES. If you wish to vent about things that irk you, don't make it personal, or raise it with Madcap. We have no input into program specifications.

Venting? I presented an alternative fix to the ordered list issue. If people like it, then it influences people to demand to have the ability to use auto number format in ordered lists.

Remember, this is what you said, which contradicts your quote above:

Madcap can't add enhancements to tags that are controlled standards. The use of CSS should be limited to the industry standards.

You can reference industry standards for XML and CSS here:
https://www.w3schools.com/cssref/default.asp

If you look at that reference and see, there is no industry standard for an "mc" anything anywhere, which is a proprietary prefix for MadCap software code. I am curious as to where you got this information that these "mc" strings are some sort of standard. Of course the parser converts it (mostly) for outputs. It works with <h1>, <p>, <ol>, and <li>. The output is usually a <span> formatted to show in the desired way.

Why does it bother you that I told people they could use with with an <li> instead of a <p>? Did you read my entire 1st post?