New Styles versus Local Formatting

[brians]

I'm a long-time FrameMaker/WWP user and I'm in the midst of a competitive analysis of Flare 4.0. I have 20 years worth of FrameMaker content (strictly formatted, no overrides, non-structured) that I am in the process of mapping to CSS styles for use in Flare. I am confused about the best method for creating corresponding CSS styles versus modifying existing styles with what appear to be local formatting overrides (which I know are not recommended, but appear to be widely implemented in these forums).

For example, if I want to implement four Body tags with four level of indents, do I create the four unique styles (p.Body1, pBody2, ...) or do I create one tag and use the indent text option from the Flare tool bar. The same applies to lists of all types, which I have configured using complex selectors like:

ul
{
list-style-type: circle;
}

ul ul
{
list-style-type: square;
}

Using the indent/outdent option from the Flare tool bar seems to be a local override, although it appears to be the preferred method of indenting on this forum. Why is this method better than creating a unique style (with embedded indent settings) for each level of indented list (for example, BullList1, BullList2, etc)? My goal is to create pristine XML which is easily transferable to other projects and products, so I'd like to implement the best procedures now before I get too deeply involved.

Thanks in advance for helping me get this straight in my head. I appreciate your help.

-Brian

[doc_guy]

Hi Brian,

Welcome to the forums!

I recommend you make all stylistic changes to the style sheet and create classes for any changes you want to make locally; the same process you were using in Frame. For the body tags, I'd definitely do the style in the style sheet and apply the class in the documents.

As for your second question, when you are working with bulleted lists, the "indent" button on the XML editor formatting bar isn't technically doing a local formatting override. It actually is adding a new <ul> block as a child element of the parent <ul> block. You can see this when you look at the blocks in the XML editor:



In this case, the child list was created by clicking the indent button on the formatting tool bar. Because this is a child <ul> of a parent <ul>, the complex selector you mentioned would style this properly.

Does that make sense?

[KevinDAmery]

Hi, Brian,

I think I understand where your confusion is coming from. When working with lists, the indent button doesn't apply a local formatting over-ride per se: instead, it creates a new set of list tags inside of the preceding element (i.e. nests a list inside the preceding list item). The code ends up looking like this:

Code: Select all

        <ul>
            <li>List level 1</li>
            <p>Nested Paragraph</p>
            <li class="Tip">Tip List level 1
                   <ul>
                           <li>List Level 2</li>
                           <li><MadCap:snippetText src="Resources/Snippets/Contained.flsnp" /></li>
                           <li>Tip List Level 2</li>
                           <p class="Tip">Nested Paragraph 2</p>
                   </ul>
            </li>
        </ul>

(I also have some classes in this example, but that's because I manually applied them at another stage - you will note though that nowhere do you see any inline styles applied.)

Basically, the idea here is to ensure that lists that appear as subordinate items to the reader are also subordinate items in the xml structure. You could, of course, achieve the same appearance on the page / screen by ending the first list, creating a second list with a class the indents it, closing that list, then creating a third list to finish off the "first" list, but while that would look the same to the reader it would not maintain the subordinate relationship in the xml structure.

HTH. If anything isn't clear, feel free to ask and we'll try to clarify.

[LTinker68]

For example, if I want to implement four Body tags with four level of indents, do I create the four unique styles (p.Body1, pBody2, ...) or do I create one tag and use the indent text option from the Flare tool bar.

I've never used FM, but I wanted to point out that "four Body tags" does not mean the same thing in FM as it does in Flare (or HTML). Word, for instance, sometimes has a paragraph style called body, and since you wrote p.Body1 in your example, then I'm guessing FM does the same. However, in HTML (and Flare), the <body> tag is the main content tag in a topic.

I just wanted to point out the difference in terminology, since there will be different effects if you change styles on the <body> tag versus changing styles on a custom class called p.Body1.

[doc_guy]

Yeah. Thanks for pointing out that distinction, Lisa. It actually tripped me up at first, then I looked at the code sample. Then I perpetuated it by calling it body as well in my post.

Good think Lisa is here to keep us honest.

[KevinDAmery]

Another difference I just remembered would also be helpful to remember. Frame and Word users "know" not to use the icons in the toolbar to create things like lists because if you use those tools you end up with a one-off style (and in the case of Word it's a flaky one-off to boot). Instead, they define list styles in their paragraph styles pallets and select them directly from there.

Flare, however, is different. In Flare, you can't apply a list style directly to a paragraph from the styles list - list styles won't even be present in the styles list if you have a standard paragraph selected. Instead, you do use the tools on the toolbar to apply a list type.

Sounds like blasphemy, right? Well, not to worry: all the list icons do is apply the appropriate xml list tags to the selected items. So if your cursor is in a p tag and you click on the numbered list icon, your code will change from:

Code: Select all

<p>Text goes here</p>

to

Code: Select all

<ol>
     <li>Text goes here</li>
</ol>

So, no evil inline formatting to worry about. You can then apply any list based classes you want to the list items from the styles list.

The text format icons are similar, but not quite as safe from a best practices point of view. For example, the B icon applies <b> tags to the selected text. This is valid xml, of course, but it isn't as controllable as using <span> tags with a span class (since <b> tags are the same no matter what you do, whereas with a span class you can modify it to whatever you want using your css). So for character formatting, I would still recommend using classes from your style list rather than the toolbar icons.

[brians]

Thanks to all for your responses. I understand that lists are "different" and I'll just have to adjust my FrameMaker mentality to allow selecting formatting options from the tool bar. However, the implementation seems awkward, specifically because I keep running into two unexpected windows when I try to manually indent some list items.

1. The error message "Current selection cannot be grouped, i.e. found no tag type that can contain the selected items".

2. The Create Group window, which wants me to select a tag (like blockquote or div) for the new group.

What is causing these errors and how can I work around them to implement the required indentation.

Thank you.

-Brian

[LTinker68]

1. The error message "Current selection cannot be grouped, i.e. found no tag type that can contain the selected items".

Most likely you selected part of one list and part of another list (or part of one <p> tag and part of another <p> tag) without selecting all of both and it can't group partial items. If you want to use the indent button, don't select any text first -- just left-click somewhere on the row to put the cursor there then click the indent icon.

2. The Create Group window, which wants me to select a tag (like blockquote or div) for the new group.

There are several ways that you can "group" items on a page. And by "group", Flare means put them inside the same container tag, so that if you want to move all of the items in the group at once, all you have to do is move the container tag. There are several types of container tags in HTML. Blockquote by default will also indent the group. DIV doesn't indent by default (although you can set it to) and has additional options not available to the blockquote tag, such as the option to "layer" or overlap the DIV over other items on the page. If you create a custom DIV class then you can select the DIV class when you group the items.

What is causing these errors and how can I work around them to implement the required indentation.

The first one is simply telling you that you didn't properly select all the items so it can't group them. The second isn't an error -- it's a feature. It's giving you a list of container tags to choose from.

[KevinDAmery]

Also, you aren't hitting the Tab key by any chance are you? The tab key brings up the group window.

(It doesn't add a tab character like it would in Frame or Word because html and xml don't support tabs.)

[brians]

Thanks again, the support here is excellent. MadCap 1, Quadralay 0.

It does seem like I'm re-inventing the wheel as I customize styles for my output. I'm assuming that many other users have similar requirements (for example, for custom note, caution, and warning styles). Are there any pre-built or templatized CSS files that provide additional functionality beyond what is currently available in the included style.css file?

Thanks,

-Brian

[lacastle]

There are a lot of good samples in these forums for custom div tags. For example:

http://forums.madcapsoftware.com/viewto ... it=warning
http://forums.madcapsoftware.com/viewto ... t=note+box

[doc_guy]

If the custom DIV tag is overkill for you, you can just create a special class of <p> to deal with notes/warnings/etc.

Here are two of the classes I use. Feel free to use/modify as you wish:

Code: Select all

p.Note
{
	font-size: 12.0pt;
	padding: 5px;
	font-style: italic;
	background-color: #ffffe0;
	border: dotted 1px #ff8c00;
	margin-bottom: 10pt;
	margin-top: 10pt;
	mc-auto-number-format: '{b}NOTE: {/b} ';
}

p.Tip
{
	font-size: 12.0pt;
	padding: 5px;
	border: dashed 1px #698f35;
	background-color: #abe857;
	margin-bottom: 10pt;
	margin-top: 10pt;
	mc-auto-number-format: '{b}TIP: {/b} ';
}

@media print
{
	p.Note
	{
		background-color: #ffffff;
		border: none 0px #ffffff;
		font-family: 'Times New Roman', serif;
		margin-bottom: 12pt;
		padding: 0;
		line-height: 4px;
		color: #2e5077;
		margin-left: 15px;
		margin-right: 15px;
	}


	p.Tip
	{
		font-family: 'Times New Roman', serif;
		background-color: #ffffff;
		border: none 0px #ffffff;
		padding: 0;
		text-indent: 0;
		color: #84b540;
		line-height: 4px;
		margin-left: 15px;
		margin-right: 15px;
	}
}

Which gives you this in online:


And this in print:

[KevinDAmery]

Actually, Brian, here's probably the quickest way for you to get a CSS that looks like you want it: copy the CSS you're currently using from your webworks exports into the Flare project and map the incoming styles to it. You may have to do some additional mapping afterwards (the import process doesn't always let you map everything) but the advantage is that presumably you already have your CSS set up the way you want it. If you use the CSS you already have, you shouldn't have to design very much to get your Flare output to look the way you want it.

(Not to suggest that Flare can't produce a decent CSS file - it can. But if you already have a CSS you're happy with, why reinvent it? When I started using Flare I used the CSS from our corporate website as a starting point and immediately had help output that matched our branding, so there's no reason you can't do something similar.)

[NorthEast]

You may have to do some additional mapping afterwards (the import process doesn't always let you map everything)

I've converted a number of FM/WWP projects to Flare, and what to do with lists was probably the main sticking point.

If you've tried importing FM projects into Flare, then you'll notice that you can only map FM styles to paragraph tags. This means that you can't map your FM list styles directly to HTML list tags (ol, ul, li).

However, there are two different ways to use lists in Flare:
- Use the standard HTML list tags (ol, ul, li), which is what you get when you click on the list icons.
- Use Flare's autonumber formats, which you can use to set up your own list numbering formats on paragraph tags.

So, if you set up some paragraph tags with autonumber formatting, then you could map your FM list styles directly to these, with no extra effort required.

If you need/want to use standard the HTML list tags, then you'll need to do some manual editing after the import process. You map the FM list styles to paragraph tags (maybe set up some dummy p tags so you can tell the difference between your 'real' paragraphs and what were lists), and then manually set these up as lists in Flare.