3 Replies Latest reply on Aug 4, 2008 12:21 PM by (Martin_R._Smith)

    Faithful Import of Code Examples

      Using import-by-reference and text-insets it insert code examples into a FM document seems a slam-dunk natural use of these features. However, I've found them very difficult and tedious to use because of the following shortcomings in FM:<br /><br />1. Conditional text settings are lost when the code is re-imported (already filed as a defect).<br /><br />2. Code must be imported using the "Treat Each Line as a Paragraph" option in order to avoid wrapping all the code together like an English language paragraph.<br /><br />3. Smart Quotes (if on) does the wrong thing to code examples.<br /><br />Treating each line as a paragraph has two serious ill effects.<br /><br />First, depending on your "Code" paragraph style it will insert whitespace between lines unless the paragraph style says not to - in which case, you have to stick an empty paragraph between the last code line and the next paragraph - an ugly blurring of the distinction between content and presentation.<br /><br />Second, you can specify a high setting for orphan lines which will tend to keep them on the same page - unless each line is its own paragraph - forcing the author to manage this by hand.<br /><br />Smart quotes is a desirable feature in the body of a document but should never be applied to a code sample. This (and the loss of condition text) forces the author to not use automatic update. Instead the author must:<br /><br />1. Turn Smart Quotes off.<br />2. Manually update all the references.<br />3. Turn Smart Quotes back on.<br />4. Fix broken conditional text for all references that actually changed.<br />5. Look for and fix any unacceptable orphan lines.<br /><br />Nasty!<br /><br />What FM needs is a fix for conditional text settings and a "Faithful Import" paragraph style preference <default off> that tells FM to:<br /><br />1. Not apply Smart Quotes - or any other feature that changes the code.<br />2. Honor the line breaks within the imported text but only treat the last one as an end-of-paragraph. This will fix the between lines of code and prevent orphan lines.<br /><br />Without these fixes, I really do not see how import can be used to solve what must be one of the most common problems.
        • 1. Re: Faithful Import of Code Examples
          Art Campbell Level 3
          I haven't specifically tried it with and without Smart Quotes on/off, but importing code snippets by reference works fine for me when I import and specify that the source file formatting be preserved rather than overridden by the destination file... and, of course, when it _is_ properly formatted. For example, with SQ turned off.

          That being said, I usually convert a code sample into a single column table w/o lines so I can better set it off from surrounding text and (by adding a column) use autonumbering to number the lines.

          • 2. Re: Faithful Import of Code Examples
            Level 1
            We have a solution to importing code into frame data... We create a MIF file of the code and then you can cut/paste this into your document... if you send me a code example and a MIF file of your template I can set it up to process and create nice code listings in your own style.
            This solution will soon be available online on our website - www.mifmasters.com (our table creation tool is already online - for CSV to MIF conversions...)
            Hope this helps!
            • 3. Re: Faithful Import of Code Examples
              Level 1
              Typically, I import source code examples into FrameMaker as PDF files. I generate the PDFs directly from a source code editor, TextPad being a personal favorite. This has the advantage of not only preserving the spacing in the code, but syntax-based highlighting as well.


              Martin R. Smith