Fixing Bullet Lists and Numbered Lists in Flare (or any HTML)

If you import content into MadCap Flare from another format, you may find your bullet lists are not quite right. Indents slightly wrong, nested bullet lists a bit off, etc. Here's how you can fix the code and get your bullets back where they need to be.

Bullet Lists as Tables? No, You Don't Want That

With large projects, Flare does not appear to handle invalid code too well (Flare 8, anyway). When I first started working with Flare, I experienced many crashes, sometimes as frequent as 2 or 3 per hour. Tidying up the HTML and incorrect unordered lists (ULs) seemed to rectify this problem.Flare's FrameMaker import creates bullet lists that look fine to the naked eye, but delve into the code and you'll see all is not quite as it should be. Sure, they look okay, but it means that the td element will control the appearance of the bullets. Correct HTML would mean the <ul> is used, not <td>.Why should you use the correct coding? How about:

• Using ul is correct HTML and avoids formatting conflicts that can arise when you want to use td for tables (that's why td stands for table definition and not unordered list).
• Using tables for layout is ‘old school’ HTML. Using ULs and OLs is technically correct and results in ‘cleaner’ files (tables require more code as each cell has to be defined).
• Who knows how tables will be handled by devices in the future? ULs and OLs are designed specifically for bullet lists and numbered lists.

Correct HTML for Bullet Lists and Numbered Lists

If you are unfamiliar with the HTML for lists, the explanation below will hopefully help you understand how they are created. If you already know about ordered lists (numbered lists) and unordered lists (bullet lists), skip this part and go directly to Find and Fix Problems with Bullet and Number Lists.

<ul> creates a bullet list. <li> creates a list item (bullet point).</li> closes a list item.</ul> marks the end of a bullet list, but if you use <ul> again before you close a bullet list, you create a nested list (a list within a list). Each time you use <ul> without closing the previous <ul>, you create another nested level. Every nested bullet list needs to be closed separately with a </ul>.Similarly, if you want to have indented text after a list item, do not close the list item and use a <p> for the text, just like a normal paragraph. Close the text with a </p>, and then close the list item with a </li>.The HTML standard does not allow a <

>inside an <ul>, but <ul> is allowed in an <li> or an <ol>.The same rules apply for numbered lists, except that you use<ol> and </ol>.Example:<ol> <li>This is point 1.</li> <li>This is point 2.This is a line of text to provide extra information about point 2.</li> <li>This is point 3<ol> <li>This is point i.This is a line of text to provide extra information about point i.</li> <li>This is point ii.</li> <li>.This is point iii.</li></ol></li> <li>.This is point 4.</li></ol>The code above produces:

1. This is point 1.
2. This is point 2.This is a line of text to provide extra information about point 2.
3. This is point 3.
4. This is point i.This is a line of text to provide extra information about point i.
5. This is point ii
6. This is point iii
7. This is point 4.

It may just be me, but I much prefer to fix existing bullet lists and number lists in plain old code. It is just easier to follow. However, if I’m writing new content and need a list, I use the list tools in Flare’s content editor, and the Make New Paragraph feature for indented text in a bullet list or number list.

How to Find and Fix <ol> and <ul> Problems

If you have a large online help project, finding all of the list errors can be a bit of a pain. If your lists are in table elements, you have to find and fix them manually. To do this, you can use Flare’s search feature to look in the code for the <td> elements, but if you have lots of genuine tables, that could soon become tiresome.Finding and fixing the <p> used inside <li> errors is a little bit easier, but still not straight-forward. The simplest way I found was to:

1. In Flare, build the project.Towards the end of the project build process, Flare starts reporting errors.
2. Save the error log file, and then open it in a text editor. The errors you need are listed towards the bottom of the file. The important thing to realise is that Flare reports the errors at the point where it encountered them, but this isn’t necessarily where the errors are. The files listed in the errors are actually files that Flare opened, but could not build because they link out to other files that contain HTML errors.
3. Open each of the files listed in Flare’s error report.
4. In each of the files, look for hyperlinks to other files (target files).
5. Open each target file and run it through the online W3C validation service. W3C will give you information about the errors in the file. Some of them are unavoidable, so don’t expect 100% clean, W3C validated files. The errors you need to pay attention to are the ones that say ‘ul or ol not allowed here’,’ ul ol or li open or closed expected here’ etc.
6. Open the target file in a text editor and correct the HTML manually (you need to display it in the XML Editor to do this). You might find it easier to open a copy of the target in a web browser as a visual indication of the structure. I found it easier to enter the correct code if I first looked at how the incorrect code was displayed in a browser.Note that I didn’t tell you to open the target file in Flare’s XML Editor. That’s because if you have lots of <p>in <li> errors, Flare may crash or freeze for extended periods.
7. Check the files you modified again in the W3C Validator. If there are no UL, OL or LI related errors, your lists should be fine. From a technical stand-point, anyway.When you open the corrected files in Flare, they should display correctly and not cause any performance issues.

The same approach can be used to fix <p> inside <li> elements in numbered lists (ordered lists) too.