Maintaining Proper XML Markup

[diego]

What’s your opinion about keeping the markup as clean and concise as possible? The Flare UI tends to do some unusual things with the markup. For example, imagine you’re writing a step and need to add a screenshot to it. People’s natural reaction is to press the Enter key after the step (instead of a Shift break), which will actually break the list and result in something like the following:
<ol>
<li>Click Save.</li>
</ol>
<p><img src=”IMG URL”/></p>
<ol MadCap:continue="true">
<li> Select a file. </li>
</ol>

In the example above, we have two steps, one of which has a screenshot. There’s an additional <ol>, and the <img> is not only outside of its <li> tag but it also contains extra markup with the <p> tags. I think the proper, concise way would be for all of this to be one list with the <img> tag inside the <li> and without unnecessary <p> tags around it, like so:
<ol>
<li>Click Save.
<br/>
<img src=”IMG URL”/>
</li>
<li>Select a file.</li>
</ol>

(The soft break <br> ensures the image doesn’t display inline. Perhaps the <br/> isn’t even necessary if we set img to display as a block in the CSS when it’s inside a list as well as setting a class for images that do need to be inline.)
I take the time to manually ensure proper markup in the XML. I think it matters because it makes it easier to create CSS rules to adjust alignment and information chunking consistently, without unintended consequences to certain elements. In addition, it creates a minimalist, organized markup, closely resembling that of a standard website. I find that it’s much harder to create alignment rules when the markup is inconsistent or messy.
What’s your take on taking the time to ensure proper markup in the XML?

[MattyQ]

I think the proper, concise way would be for all of this to be one list with the <img> tag inside the <li> and without unnecessary <p> tags around it, like so:
<ol>
<li>Click Save.
<br/>
<img src=”IMG URL”/>
</li>
<li>Select a file.</li>
</ol>

You can already do this within Flare -- no need to approach it manually. To create the code you indicate above, it would just be the following:

1. Insert an ordered list.
2. Type "Click Save."
3. Press Shift+Enter to insert a <br />
4. Insert an image.
5. Press Enter.
6. Type "Select a file."

And you end up with (this is copy and pasted from Flare):

Code: Select all

<ol>
    <li>Click Save.<br /><img src="Resources/Images/Icons/save.svg" /></li>
    <li>Select a file.</li>
</ol>

Which I think is the even more concise. The issue with using the <br />, I feel, is the lack of control. When CSS time comes, you're limited exclusively to indirectly manipulating a <br> tag with the line-height property (since the <br /> is simply a line break).

I think you're better off using the Ctrl+; (semicolon) hotkey to insert paragraphs into the li. Then you're not sacrificing any potential CSS manipulation. So, instead, you'd do:

1. Insert an ordered list.
2. Press Ctrl+; to insert a <p>
3. Type "Click Save."
4. Press Enter to add another p.
5. Insert an image.
6. Press Enter.
7. Press Shift+Tab to return to the list level.
8. Type "Select a file."

It's an extra step or so, but you still end up with pretty nice, clean code:

Code: Select all

<ol>
     <li>
        <p>Click Save.</p>
        <p>
            <img src="Resources/Images/Icons/save.svg" />
        </p>
    </li>
    <li>Select a file.</li>
</ol>

[diego]

I think the proper, concise way would be for all of this to be one list with the <img> tag inside the <li> and without unnecessary <p> tags around it, like so:
<ol>
<li>Click Save.
<br/>
<img src=”IMG URL”/>
</li>
<li>Select a file.</li>
</ol>

You can already do this within Flare -- no need to approach it manually. To create the code you indicate above, it would just be the following:

1. Insert an ordered list.
2. Type "Click Save."
3. Press Shift+Enter to insert a <br />
4. Insert an image.
5. Press Enter.
6. Type "Select a file."

And you end up with (this is copy and pasted from Flare):

Code: Select all

<ol>
    <li>Click Save.<br /><img src="Resources/Images/Icons/save.svg" /></li>
    <li>Select a file.</li>
</ol>

Which I think is the even more concise. The issue with using the <br />, I feel, is the lack of control. When CSS time comes, you're limited exclusively to indirectly manipulating a <br> tag with the line-height property (since the <br /> is simply a line break).

I think you're better off using the Ctrl+; (semicolon) hotkey to insert paragraphs into the li. Then you're not sacrificing any potential CSS manipulation. So, instead, you'd do:

1. Insert an ordered list.
2. Press Ctrl+; to insert a <p>
3. Type "Click Save."
4. Press Enter to add another p.
5. Insert an image.
6. Press Enter.
7. Press Shift+Tab to return to the list level.
8. Type "Select a file."

It's an extra step or so, but you still end up with pretty nice, clean code:

Code: Select all

<ol>
     <li>
        <p>Click Save.</p>
        <p>
            <img src="Resources/Images/Icons/save.svg" />
        </p>
    </li>
    <li>Select a file.</li>
</ol>

Using Crtl+; approach, how would you improve proximity between a screenshot and its corresponding step? If all content is inside a <p> tag in the <li>, setting the margins for <p> in <li> will be easy, but then the space between step <p> and its related screenshot <p> will be the same as the space between the screenshot <p> and the <p> step below (not related to the screenshot). In other words, I'd want to make sure there's close proximity between a <p> step and its corresponding <p> image.

[Nita Beck]

Diego, how about creating a class of <p> that you could apply to the paragraphs containing screenshots within step-by-step procedures? Call it something like p.ImageWithinStep.

[MattyQ]

Like Nita said, probably the best way in Flare is to create a class that you apply to those images.

Additionally, if you absolutely knew that in every instance of an ordered list you wanted the images to be nearer the text, you could do some CSS such as:

Code: Select all

ol > li > p > img /* This is pretty hamfisted and would affect every image that appeared in a paragraph within an ordered list */
{
    margin-top: -0.5em;
}

Or if you only wanted certain lists to have that quality, but didn't want to apply the class to every image, you could create a class for the ordered list instead, such as:

Code: Select all

ol.procedure > li > p > img /* where ".procedure" is the class */
{
    margin-top: -0.5em;
}

These are fairly simple methods -- I imagine there are still more creative ways you could use CSS to do what you're looking for. Naming conventions for the images, for example. If an image contained a certain phrase or word in its name, you could select for that:

Code: Select all

img[src*=procedure] /* where the image must contain the word "procedure" in its name, such as "procedureStep1.png" or "css_procedure.jpg" */
{
    margin-top: -0.5em;
}

To note, if one went with this method, the attribute selector is case sensitive.

These are just a few examples, though.

[diego]

Like Nita said, probably the best way in Flare is to create a class that you apply to those images.

Additionally, if you absolutely knew that in every instance of an ordered list you wanted the images to be nearer the text, you could do some CSS such as:

Code: Select all

ol > li > p > img /* This is pretty hamfisted and would affect every image that appeared in a paragraph within an ordered list */
{
    margin-top: -0.5em;
}

Or if you only wanted certain lists to have that quality, but didn't want to apply the class to every image, you could create a class for the ordered list instead, such as:

Code: Select all

ol.procedure > li > p > img /* where ".procedure" is the class */
{
    margin-top: -0.5em;
}

These are fairly simple methods -- I imagine there are still more creative ways you could use CSS to do what you're looking for. Naming conventions for the images, for example. If an image contained a certain phrase or word in its name, you could select for that:

Code: Select all

img[src*=procedure] /* where the image must contain the word "procedure" in its name, such as "procedureStep1.png" or "css_procedure.jpg" */
{
    margin-top: -0.5em;
}

To note, if one went with this method, the attribute selector is case sensitive.

These are just a few examples, though.

Applying a class to every <p> that wraps an image to get the proximity effect is a good solution, as you have both suggested. As Matty points out, a negative margin to the class would do the trick for proximity. However, There's a bug in Flare that prevents negative margins from working in print outputs (confirmed), which is a huge letdown for this approach. The only other approach I can think of is, in addition to a p class for a paragraph wrapping an image, is a another class for the paragraph that is related to the image, which is this case is the <li> step that's wrapped in a <p>. In the end, I'm now having to apply two different classes to get the intended effect, which is extra work and leans me towards the simpler <br/> approach.

In general, I like to keep screenshots closer to their step or paragraph in comparison to the step or paragraph after it.

[diego]

Negative padding top is a hack, but it works in the PDF.

[MattyQ]

Negative padding top is a hack, but it works in the PDF.

Ugh, that's rough. =( It's good to know there's a way around that bug, though.