Preserve formatting of inline HTML pasted into Flare topic?

[Phlawm53]

------
Might anyone please explain how to get Flare (11) to preserve (as in not destroy) the formatting of a syntax-highlighted code sample pasted into Flare as inline HTML?

BACKGROUND
The problem arises because JavaScript syntax highlighters won't work in PDF, Flare or otherwise: JavaScript-based highlighters run at the time an HTML page is loaded by a browser. PDFs can't run the scripts, ergo no JavaScript-based syntax highlighting will appear in PDFs.

The way around that seems to be to use a tool such as http://hilite.me/ or Pygments (http://pygments.org/) to wrap a code sample in inline HTML that produces the highlighting. So far, so good -- because the syntax highlighting is presented as inline HTML, the highlighted code sample is viewable in a PDF.

THE PROBLEM
IF I open a Flare topic file in Flare's text editor AND paste the inline HTML into it, THEN Flare's text editor destructively reformats it. The result is that the inline code sample no longer contains the correct indentation or line breaks -- Flare's text editor has taken it upon itself to destructively reformat them.

THE KEY POINT is that I've demonstrated to myself that it's Flare's text editor that's screwing up the inline HTML: IF I use an external text editor to paste the inline code into a Flare topic file, AND view that topic file in a browser before Flare's text editor has had an opportunity to mangle it, THEN the inline HTML presentation is preserved. It's only after I open that same topic in Flare's text editor that Flare destroys the presentation of the nicely formatted and syntax-highlighted code sample. (See EDIT: A BIT MORE INFO, below, for information about Flare's GUI topic editor vis-a-vis this problem.)

SO, has anyone figured out how to force Flare to leave the pasted-in HTML alone? I've tried everything I can think of. That includes pasting the inline HTML into a Flare Snippet in the hope that maybe that would prevent Flare's text editor from destructively reformatting it.

I'm hoping the answer will be simple (DOH!) and I'm just overlooking it...

EDIT: A BIT MORE INFO
I opened a Flare topic file that I hand-edited outside of Flare, and that displayed the inline HTML properly in a Web browser, in Flare's GUI text editor. Both Flare's GUI text editor AND an HTML5 preview of the topic did NOT properly display the inline HTML.

I then re-opened that file in an external text editor. I was surprised to see that Flare's GUI Topic Editor had not destructively reformatted the HTML. So it seems there are two problems:

• Flare's internal text editor aggressively malforms a syntax-highlighted code sample pasted into a Flare topic file as inline HTML.
• Flare is unable to process the inline HTML even if Flare's internal text editor has not been given a chance to destructively reformat the inline HTML.

By the by, a Flare 2017 user tried pasting inline HTML into one of that version's Flare topic files. The problem existed in V2017 as well. So upgrading isn't the solution to this particular problem...

Cheers & thanks for your help,
Riley
SFO

[Phlawm53]

------
OK, it appears I have a preliminary fix for this problem.

To recap, both http://hilite.me/ or Pygments (http://pygments.org/) use inline HTML to style each line of code in a code sample. Both of those tools wrap each line in SPAN tags. SPAN tags are inline elements. While Web browsers display each of those SPAN-wrapped lines on separate lines, Flare gets confused: It displays the inline-HTML as a single very long line.

The fix seems to be to append <br /> tags to the SPAN-wrapped lines. REGEX find == /(<\/span>)($)/gm. REGEX replace == $1<br />$2. Flare will then put each syntax-highlighted line where it belongs. (NOTE that the Flare text-editor's REGEX find/replace has a confirmed bug. In REGEX replace statements that contain escaped characters such as \n\r, Flare's text editor inserts the literal characters rather than the escaped newline character codes. So one may want to use a "real" programmer's text editor to process the inline-HTML...)

Flare will still grumble about the border-width:.1em .1em .1em .8em; rule embedded in hilitie.me's inline styling. But that doesn't prevent Flare from displaying the highlighted code in both online and PDF Targets.

HOWEVER in the PDF Target, long lines are broken in ugly ways. So one may need to adjust styles such as font-size or pre-process code samples with long lines in one or another way to prevent this.

ALSO, at this point I'm inclined to think that Pygments rather than hihlite.me may be the better solution going forward. One could create a script that uses Pygments to batch process a bunch of code samples. One could then run a second script that appends the <br /> tags to the SPAN-wrapped lines in Pygments' output.

To be continued...

Cheers & hope this helps,
Riley
SFO

[cdschroeder]

Just wanted to pop in and say I'm watching your progress with great interest. We just started using Prism to highlight code examples in our top nav output. But of course, the first question I received was "why isn't the PDF updated too??"

[Psider]

Could the pre tag be set to white-space: nowrap somehow? That would force the basic code to a single line, but split it when you add a br tag.

[moshe]

I am also listening to this thread with interest, and exasperated by the Flare editor. I am hoping to find time to get syntax highlighting working in Flare output.

In the meantime, this might be of use to one of you:

I found that <pre> in Flare doesn’t work like I want it to. It preserves the whitespace, but doesn’t preserve things like the open- and close-brackets, etc., which are converted to the character codes. I found that CDATA (Character Data) sections preserve the actual characters. CDATA sections tell the parser that there is no markup in the characters contained within the CDATA section. CDATA sections, however, do not preserve whitespace.

By combining <pre> with CDATA, it seems that I can preserve both the actual characters and the whitespace!

Code: Select all

<pre>
<![CDATA[
…code…
]]>
</pre>

For example, this content in the Flare code editor:

Code: Select all

<pre>
<![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<CatapultGlossary>
	<GlossaryEntry>
		<Terms>
			<Term>My Term</Term>
		</Terms>
		<Definition>My definition</Definition>
	</GlossaryEntry>
</CatapultGlossary>		
]]>
</pre>

Produces the following in the WYSIWYG editor:

pre-CDATA.png

Hope this helps,
Moshe

[NorthEast]

moshe- Good suggestion about CDATA, so maybe post it as a separate tip?

But for Riley, presumably using CDATA wouldn't work, as he's wanting to paste code that includes additional syntax highlighting, rather than just the raw code.

[Phlawm53]

I am also listening to this thread with interest, and exasperated by the Flare editor. I am hoping to find time to get syntax highlighting working in Flare output.

Moshe:

Join the growing number of us who have submitted Enhancement Requests to Madcap on the issue of Flare's execrable text editor:

https://www.madcapsoftware.com/feedback ... quest.aspx

My thought is that rather than re-invent the programmer's text editor wheel, Madcap should find one or two open-source programmer's text editors and develop Flare plugins for them. We Flare users get a text editor that doesn't waste our time and destroy our work; Madcap earns itself some open-source contribution points.

But for Riley, presumably using CDATA wouldn't work, as he's wanting to paste code that includes additional syntax highlighting, rather than just the raw code.

I did explore using CDATA. But as Dave commented, the tags that produced the syntax highlighting were no longer seen as tags but as literal text.

What is working (so far) is using a "real" third-party programmer's text editor to hand-edit my code samples outside of Flare. That works as long as I don't make the mistake of opening the topic in Flare's text editor.

Remember that for me the issue exists because I want to include syntax-highlighted code samples in Flare PDF Targets. For that I need to use inline rather than JavaScript-based highlighting. So I've spent some time figuring out the work flow for the command-line instance of Pygments.

In the context of this discussion, Pygments can produce two helpful forms of output:

• A single-file HTML output which contains both inline CSS and syntax-highlighted code
• A CSS file that contains the CSS that's otherwise at the top of the Pygments' single-file output

Long story short is that Flare's PDF engine doesn't work with Pygments' single file output per bullet item one, above. But if one uses Pygments to gen an external CSS file, then references that CSS file from a Flare topic containing code syntax-highlighted by Pygments, it works. (Actually one can generate the single-file version of Pygment's output and cut-and-paste the inline CSS into a separate file.)

HOWEVER: Flare's GUI XML Editor (a.k.a. topic editor) sometimes has problems displaying the formatted text. IF that happens, one needs to Build it as an online or PDF Target to see the highlighting. AND per my earlier comment in this thread, don't forget to do the REGEX find/replace that appends <br/> tags to the end of each line terminated by a SPAN tag.

At this point I'm also putting my nicely PRE-formatted code samples in Snippets. I create an empty Snippet in Flare, then hand-edit it entirely outside of Flare. My thought (perhaps more of a superstition?) is that if I do that I'm keeping the code samples' formatting out of the hands of Flare's time-wasting, work-destroying internal text editor.

Cheers & hope this helps,
Riley
SFO

[Phlawm53]

Could the pre tag be set to white-space: nowrap somehow? That would force the basic code to a single line, but split it when you add a br tag.

Any other issues notwithstanding, Flare's PDF engine doesn't handle white-space: nowrap;. See this Forum post for more information:

viewtopic.php?f=10&t=28863

That thread is a bit convoluted but in the end illustrates the problem.

Cheers & hope this helps,
Riley
SFO

[armplinker]

Don’t forget to use madcap:snippetBlock, not madcap:snippetText, to incorporate these formatted snippets.
By default for whatever reason Flare pastes them all as madcap:snippetText
which annihilates the formatting. Would be nice if it confirmed the type on paste...

[kmacdowe]

I too am wrestling with the issues discussed in this thread. I paste highlighted code from Visual Studio into Word and them import the Word doc into Flare using the default settings (I think). This results in highlighting that it retained in both HTML and PDF output. The topic code is very verbose but the syntax highlighting seems to work, so far.

[Phlawm53]

I too am wrestling with the issues discussed in this thread. I paste highlighted code from Visual Studio into Word and them import the Word doc into Flare using the default settings (I think). This results in highlighting that it retained in both HTML and PDF output. The topic code is very verbose but the syntax highlighting seems to work, so far.

Interesting that for once Word provides a sort of solution rather than being a problem...

Cheers,
RBV
SFO