Formatting of Programming Code Examples

This forum is for all Flare related Tips and Tricks.
Have a tip or trick you use while working in Flare? Share it here.
Post Reply
stealth94rt
Propeller Head
Posts: 41
Joined: Thu Feb 02, 2006 2:10 pm

Formatting of Programming Code Examples

Post by stealth94rt »

We are currently running trials with Flare 2.5 versus Frame/ePPro. We have quite a few projects that were developed in various veriosn of RoboHelp. Many of the software topics include programming code samples. These were formatted using the <pre></pre> tags in RoboHelp. Where indents were needed, spaces were used to create the indented lines. Now, here's the problem:

When we bring these projects/topics into Flare 2.5, the code samples do not remain properly formatted. Flare ignores the spaces at the beginning of each line, so all lines appear left-justified, even though the entire block of code is surrounded by a starting and ending <pre> tag. (When viewed in Flare's simple Text Editor, the code still appears perfectly formatted.) From some experiments, it appears that the only way to get Flare to NOT ignore the spaces, is to put a <pre> tag at the beginning of each line and a </pre> tag at the end of each line. However, even doing that, it ignores any lines that have the preformatted tags with just a space between them.

Unfortunately, we have 1000s of lines of code, and it would be a grueling task to hand insert a preformatted tag for every line. Is there a fix or workaround for this problem?

Thanks for any assistance on this.
gwadmin
Propeller Head
Posts: 41
Joined: Thu Feb 16, 2006 8:37 am
Location: Boston, MA

Post by gwadmin »

Hi -- try using <pre xml:space=\"preserve\"> at the beginning of the code
stealth94rt
Propeller Head
Posts: 41
Joined: Thu Feb 02, 2006 2:10 pm

using <pre xml:space=\"preserve\">...

Post by stealth94rt »

Thank you for responding to my post.

When I first tried the using the <pre xml:space=\"preserve\"> tag, it appeared that it did not work, as the code example viewed in Flare's XML editor was not formatted correctly (all the spaces at the beginnings of lines were gone, making it appear incorrectly formatted).

However, if the page is viewed in the \"preview\" window, or compiled into a CHM and viewed, the code block with the <pre xml:space=\"preserve\"> tag is correctly formatted. So, it appears that part of the problem may be Flare's XML editor display of the code. This would make it difficult to \"see\" (while working on a project) which code has been correctly formatted versus code that needs to be touched up. You would have to view every page with code in the \"preview\" window to check it.

I would be interested in knowing how others are preserving the formatting of programming code examples in their Flare projects.
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

indents and the <pre> tag

Post by mattf »

Hi stealth and gwadmin,
I added xml:space=\"preserve\" to my <pre> tags and it solved the problems I was having about indentation for WebHelp output, but in printed (MyMSWord) output, Word slams all the lines up flush left. So this workaround is not ultimately a viable solution for me. Also, it's a pain to have to go into the text editor and add this snippet to each tag. Also, as stealth pointed out, you can't see what's what in the project, only in the output.

I had solved this originally by creating <p> subclasses called p.codeSampleIndent01, p.codeSampleIndent02, etc. up to 12, and gave each one an increasing indent. But in cases where I'm duplicating huge chunks of code this is a big time-sink. I would rather have the <pre> tag behave properly in all outputs.

Has anyone figured out a better way?

Matt
Matt F
You learn something new every day if you're not careful.
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

bug submitted - pre tag fouled in Flare editor and in print

Post by mattf »

I've submitted an official bug report asking that the Flare editor display the indentations correctly and that they be rendered correctly in printed output.
Matt F
You learn something new every day if you're not careful.
stealth94rt
Propeller Head
Posts: 41
Joined: Thu Feb 02, 2006 2:10 pm

Post by stealth94rt »

Matt:

Sorry that I didn't get back to you earlier on this. I have also been talking with the Madcap folks, via email, about this issue, as it was said to be \"fixed\" in Flare v3.0.

Obviously, we are still having problems -- I was beginning to think it was just me. Therefore it was probably good that you submitted the bug report (it will help emphasise the problem).

Regards,
Larry
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Post by mattf »

I haven't done exhaustive controlled testing, like with mice and stuff, but I think what was \"fixed\" is that you no longer have to add the xml:space=\"preserve\" snippet into the code. Adding it doesn't seem to make any difference in v3 (in my earlier post I thought it was making a difference, but it turns out I just hadn't tried using <pre> styles in a long time.) What seems NOT fixed is that the editor still shows everything flush left, even though the built output is correct (you noted this originally), and that the printed (MyPrintedManual) output is all flush left and seems to have trouble with line height.

I might play with this more as time allows and report back later.

Matt
Matt F
You learn something new every day if you're not careful.
BobMerrill
Propeller Head
Posts: 45
Joined: Tue Nov 07, 2006 10:17 am
Contact:

Re: Formatting of Programming Code Examples

Post by BobMerrill »

I've been fighting this and complaining about it since Version 1. I still find the XML editor barely useable a wicked squirrelly, (technical term) especially keyboard control of the text cursor. (Hey, we're all keyboardists here, no?)

The other part of this that is problematic is what happens when you paste code into a pre-formatted block. (some other interesting behaviors when copying or pasting as well - too numerous to come up with steps to drive...)

Sorry. This is something I deal with all day, every day. A more robust editor would be worth WAY more to me than any additional fancy features.

Cheers,

Bob
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: Formatting of Programming Code Examples

Post by SteveS »

Don't forget to add a feature/ bug report - the noisiest squeek gets oiled! (Or so my grandmother used to say) :D
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
livetoski
Sr. Propeller Head
Posts: 135
Joined: Thu Aug 30, 2007 7:10 am
Location: Ottawa

Re: Formatting of Programming Code Examples

Post by livetoski »

wicked squirrelly!! Yes yes yes.

I am spending all my time figuring out how to do such simple things like have a nice-looking table, and in the midst of it all still having to cope with the wicked squirrelly-ness of the XML editor. I am a writer, and I'd like to spend my time researching and writing. I don't like fixing the code every time the XML editor refuses to work as an editor. Why can't I just plant my cursor and, you know, TYPE into a table cell or COPY without the entire screen getting gobbled by the mouse.

Oh for the neatness and completeness of FrameMaker. I feel like the victim of a hoax...
BobMerrill
Propeller Head
Posts: 45
Joined: Tue Nov 07, 2006 10:17 am
Contact:

Re: Formatting of Programming Code Examples

Post by BobMerrill »

I feel like the victim of a hoax...
When I generate WebHelp, I feel like it's worth the price of admission. It works great in Safari, a most notable achievement.

When I use the XML editor, or when I generate printed output, I kind of feel ripped off. RH's editor, while squirrely (squirly? squrly?) and notorious for generating ugly code, was at least usable, and was very useful for adding links to topics via drag-and-drop.

I'm just hoping that MadCap can put some priority on fundamental usability of the editor before they plunge headlong into new feature sets. I'm getting pretty tired of ponying up many hundreds of dollars everytime I want to see if there are any improvements to the editor.

Bob
livetoski
Sr. Propeller Head
Posts: 135
Joined: Thu Aug 30, 2007 7:10 am
Location: Ottawa

Re: Formatting of Programming Code Examples

Post by livetoski »

Yes, generating is a treat. And we can customize our output much better than before.

Our first major release is coming up. We've been carrying two methods of hosting our documentation for the past 6 months (someone forced us to host all our online help through SharePoint, don't ever let this happen to you, it was a disaster, as anyone who understands online help could see).

Things should be better soon, although I don't think we can do anything about the buggyness of the xml editor. I realize why some of the buggyness occurs in the XML Editor, but it drives me nutty. Why shouldn't I be able to highlight text and PASTE Over it, instead of having to delete the text first. This tool is hard on those of us with tendon issues, lots and lots of extra clicks.
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: Formatting of Programming Code Examples

Post by LTinker68 »

BobMerrill wrote:RH's editor... was very useful for adding links to topics via drag-and-drop.
You can do this in Flare. Left-click on the topic in the Content Explorer to select it, then drag it to the open topic in the XML Editor. The cursor will turn into a little curved arrow showing where the link will be inserted. When you have it where you want, release the mouse, and the Insert Hyperlink screen will appear. If you leave the screen with the default options, then it'll use the topic's title (generally the first heading in your topic) as the hyperlinked text. Or, when the Insert Hyperlink screen is visible, you can enter different text for the hyperlink, set it to open in a popup or new window, select a different class, etc.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: Formatting of Programming Code Examples

Post by LTinker68 »

livetoski wrote:Why shouldn't I be able to highlight text and PASTE Over it, instead of having to delete the text first. This tool is hard on those of us with tendon issues, lots and lots of extra clicks.
AndyR, one of this forum's MVPs, has a great blog post on the different appearances of the cursor in the XML Editor. What's most likely happening to you is that you're selecting a tag instead of the text between the tags. The specific article in Andy's blog is at http://techwritetips.wordpress.com/category/navigation/.
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
livetoski
Sr. Propeller Head
Posts: 135
Joined: Thu Aug 30, 2007 7:10 am
Location: Ottawa

Re: Formatting of Programming Code Examples

Post by livetoski »

That's interesting. Thanks. I'd like to be able to select the text that I want to select. Select, copy or cut and paste quick as a wink.

It's when I try to copy more than one line in a paragraph, all of a sudden the heading above and tables and everything but the text I am selecting is highlighted. I have to carefully select and arrow down to do more than one line in a paragraph or use the paragraph tag in the left, but I can't select more than one paragraph at a time. So I may as well select with teh mouse, switch to the keyboard and switch back to the mouse to scroll and drop the text, and cross my fingers that the text pastes over and doesn't just get added to the selected content. Ah, you seem to be a fan and perhaps I will get comfortable soon. Linda
BobMerrill
Propeller Head
Posts: 45
Joined: Tue Nov 07, 2006 10:17 am
Contact:

Re: Formatting of Programming Code Examples

Post by BobMerrill »

I'd like to be able to select the text that I want to select. Select, copy or cut and paste quick as a wink.
I'm with ya. And I want to do it with my keyboard, not with a mouse. Using these *standard* keystrokes:

Shift-left/right arrow - select/deselect 1 character
Shift-up/down arrow - select/deselect 1 line
Ctrl-left/right arrow - move one word left/right
Ctrl-shift-left/right arrow - select/deselect by word
Ctrl-up/down arrow - move up/down one paragraph
Ctrl-shift-up/down arrow - select/deselect by paragraph

Right now even if you want to use your keyboard, there are times when the arrow keys will do absolutely nothing. If you arrow through a section with some kind of formatting, you are arrowing through all these invisible characters (yes I know, they are tags) but you have to pay very close attention to the cursor or you get all messed up and select stuff you don't want, and might not even know you are selecting.

I hate Word, but one thing for sure - using the set of keystrokes above, I can *fly*...

Am I whining again?

Bob
livetoski
Sr. Propeller Head
Posts: 135
Joined: Thu Aug 30, 2007 7:10 am
Location: Ottawa

Re: Formatting of Programming Code Examples

Post by livetoski »

Totally. I completely agree. I am relieved by the whining, I am glad it's not just me.
KevinDAmery
Propellus Maximus
Posts: 1985
Joined: Tue Jan 23, 2007 8:18 am
Location: Darn, I knew I was around here somewhere...

Re: Formatting of Programming Code Examples

Post by KevinDAmery »

FWIW, what I found after using the XML editor for a while was I could either avoid the squirrelieness (sic) or recognize it and quickly work around it so that I was able to bang stuff out pretty quickly. Since then, I've gotten used to the foibles (sort of like how you get used to the cupboards that squeak when you open them after a while--you still don't like it, but it doesn't drive you batty anymore).
Until next time....
Image
Kevin Amery
Certified MAD for Flare
BobMerrill
Propeller Head
Posts: 45
Joined: Tue Nov 07, 2006 10:17 am
Contact:

Re: Formatting of Programming Code Examples

Post by BobMerrill »

Flare 4 basically makes this problem go away, at least if you are more concerned about the appearance than the underlying HTML.

When you paste code into the XML editor with Flare 4, a dialog appears, giving you a ton of options, one of which includes enclosing each line ending in newline character with a <p>...</p> tag.

There are enough options there that you can get more or less what you want. That makes one of my angst sources go away. A few others taken care of in Flare 4 - the PDF stuff is a huge leap forward toward true single-sourcing.

Best,

Bob
Post Reply