Formatting of Programming Code Examples
-
- Propeller Head
- Posts: 41
- Joined: Thu Feb 02, 2006 2:10 pm
Formatting of Programming Code Examples
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.
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.
-
- Propeller Head
- Posts: 41
- Joined: Thu Feb 02, 2006 2:10 pm
using <pre xml:space=\"preserve\">...
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.
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.
indents and the <pre> tag
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
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.
You learn something new every day if you're not careful.
bug submitted - pre tag fouled in Flare editor and in print
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.
You learn something new every day if you're not careful.
-
- Propeller Head
- Posts: 41
- Joined: Thu Feb 02, 2006 2:10 pm
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
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
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
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.
You learn something new every day if you're not careful.
-
- Propeller Head
- Posts: 45
- Joined: Tue Nov 07, 2006 10:17 am
- Contact:
Re: Formatting of Programming Code Examples
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
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
-
- Senior Propellus Maximus
- Posts: 2089
- 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
Don't forget to add a feature/ bug report - the noisiest squeek gets oiled! (Or so my grandmother used to say)
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
Re: Formatting of Programming Code Examples
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...
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...
-
- Propeller Head
- Posts: 45
- Joined: Tue Nov 07, 2006 10:17 am
- Contact:
Re: Formatting of Programming Code Examples
When I generate WebHelp, I feel like it's worth the price of admission. It works great in Safari, a most notable achievement.I feel like the victim of a hoax...
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
Re: Formatting of Programming Code Examples
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.
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.
Re: Formatting of Programming Code Examples
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.BobMerrill wrote:RH's editor... was very useful for adding links to topics via drag-and-drop.
Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
Re: Formatting of Programming Code Examples
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/.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.
Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
Re: Formatting of Programming Code Examples
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
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
-
- Propeller Head
- Posts: 45
- Joined: Tue Nov 07, 2006 10:17 am
- Contact:
Re: Formatting of Programming Code Examples
I'm with ya. And I want to do it with my keyboard, not with a mouse. Using these *standard* keystrokes: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.
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
Re: Formatting of Programming Code Examples
Totally. I completely agree. I am relieved by the whining, I am glad it's not just me.
-
- 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
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....
Kevin Amery
Certified MAD for Flare
Kevin Amery
Certified MAD for Flare
-
- Propeller Head
- Posts: 45
- Joined: Tue Nov 07, 2006 10:17 am
- Contact:
Re: Formatting of Programming Code Examples
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
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