Subversion Repositories Scribus


Rev 13559 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

<head><TITLE>Render Frames</TITLE></head>
<p>Since version 1.3.5 Scribus contains a powerful new feature called
Render Frames. Originally planned as a means to insert formulas into
Scribus documents, the inventor, Hermann Kraus, has enabled the
creation of almost any kind of special typesetting, like formulas,
musical notation or chess notation, from within Scribus. The trick here is that Scribus uses other programs in the background. It imports their output into a special frame type called <b>Render Frames</b>.</p>
<p>While this feature is extremely versatile, you must not forget
that the use of it requires knowledge of the markup codes
required by a particular program. These commands are beyond the scope
of the Scribus documentation.</p>
<h1>Creating a Render Frame</h1>
<p>To create a Render Frame, click on the Render Frame icon in the
menu bar, use <i>Insert &gt; Render Frame</i>, or press D on the
<table width="100%"><tr><td align="center"><img src="images/rf2.png"/></td></tr></table>
<p>The cursor will then turn into a frame symbol with an L inside:</p>
<table width="100%"><tr><td align="center"><img src="images/DrawLatexFrame.png"/></td></tr></table>
<p>The next step is to click-drag the frame and let up, just like you would do
with a text frame. By default, Scribus will display a welcome
message, which indicates that at least the configuration for LaTeX is
correct. What you see below is the output from LaTeX, rendered in Scribus.
The welcome message will be displayed in the language of the user
interface as set in <i>File &gt; Preferences</i>. If no translation
of the message is available, you will see the English version:</p>
<table width="100%"><tr><td align="center"><img src="images/rf3.png"/></td></tr></table>
screenshot above has been made with the default resolution of 72 dpi,
which, obviously, isn't enough for printing. You can easily change
the resolution as you'll learn below.</p>
<h1>Editing Render Frames</h1>
you right-click on a Render Frame, the context menu shows an entry
called "Edit Source:"</p>
<table width="100%"><tr><td align="center"><img src="images/rf4.png"/></td></tr></table>
<p>Selecting it brings up the "heart" of the Render Frame, the
<table width="100%"><tr><td align="center"><img src="images/rf5.png"/></td></tr></table>
<p>In Scribus 1.3.5, the editor is preconfigured to use LaTeX,
Lilypond, gnuplot, dot/GraphViz and POV-Ray.</p>
<p>To the left you see a field with the caption "Enter Code."
Here you can insert the markup code for the output you want from the
external program. For preconfigured renderers Scribus is shipped with some simple code snippets that will enable you to test if the respective programs are installed and configured properly. As you can see, the editor provides syntax
<p>The "Update" button beneath the text field will update the
content of the Render Frame, so that you can visually check the
results of changes you made to the markup text without closing the editor. "Revert" will
revert any change you made to the text. Please be aware that once you started editing the text, it's no longer possible to change the markup renderer, e.g., if you started editing LaTeX sourcecode, you cannot switch to Lilypond anymore.</p>
<p>To the right you see a row of tabs. These are not available for
all preconfigured markup languages, so sometimes the editor only shows the
"Options" tab.
<p>In the "Options" tab, the first entry is "Resolution." Its
default setting is "Automatic," thus, 72 dpi as explained above.
You can easily change the resolution of the output to something more
suitable for printing.</p>
<p>"Program" shows the list of supported programs. The editor
will list all programs that are configured in <I>File &gt;
Preferences&gt; External Tools</I>.</p>
<p>If you check "Use Preamble," the editor will automatically use
the preamble and the postamble as specified in the XML configuration
files. See below for more details.</p>
<p>"Program Messages" shows the messages that would otherwise be
displayed in a command-line interpreter. They are "intercepted"
by Scribus, just like the final output, and they are often useful to
find out what went wrong if the rendering failed.</p>
<p>If you click on "Run external editor," Scribus will start the
editor as specified in <i>File &gt; Preferences</i>,
and "Kill Program" will stop the external program. This can be
useful when the external program stumbles across an error you made in
your markup that causes the external program to fail or even crash.</p>
<h1>Preconfigured Programs</h1>
<table width="100%"><tr><td align="center"><img src="images/rf6.png"/></td></tr></table>
<p>The first LaTeX tab is called
"Fonts/Headers." In the upper drop-down list you can set the font
used for a Render Frame that uses LaTeX. By default, only four fonts
are listed, but you can easily add more by editing the LaTeX XML
configuration file as described in detail below: Just add another font under <code>&lt;list name=&quot;font&quot;
default=&quot;&quot;&gt;</code> in the file. Please note that the font list
for LaTeX (and many other markup programs) is completely different
from the fonts available to you in Scribus and other programs, as
LaTeX uses its own fonts and needs to be configured to use the Type&nbsp;1, TrueType and OpenType fonts available to you in programs like
Scribus or For more information about LaTeX font configuration see the <a href="">LaTeX Font Selection Guide (PDF)</a>.</p>
<p>The next drop-down list allows
for changing the default font size. If you are used to LaTeX, you
will already know that this is the setting for the base font. Other
necessary font sizes, e.g. for superscript and subscript are
determined by LaTeX. You will also note that the editor lists only a
selection of base font sizes. Again, you can easily add other sizes
under <code>&lt;list name=&quot;fontsize&quot; default=&quot;11pt&quot;&gt;</code>
in the LaTeX XML configuration file. Since there are almost no limits
as to the possibilities you have for the configuration of a LaTeX
file, you will appreciate the option to select different XML
configuration files in <i>File &gt; Preferences &gt; External
<p>The text field "Additional
Headers" allows for the insertion of additional headers to the
preamble of the LaTeX markup, which will be stored within the Scribus sla
<p>Finally, you find different tabs
with symbols and characters that can be created by LaTeX:</p>
<table width="100%"><tr><td align="center"><img src="images/rf7.png"/></td></tr></table>
insert a single symbol into your markup code, you can either select
the symbol and click "Insert Symbol" or double-click on the icon
in the field.</p>
<p>For more information see the <a href="">official LaTeX website</a>.</p>


<table width="100%"><tr><td align="center"><img src="images/lilyp.png"/></td></tr></table>

There are no additional options for Lilypond available.
<p>For more information see the <a href="">official Lilypond website</a>.</p>


<table width="100%"><tr><td align="center"><img src="images/plot1.png"/></td></tr></table>
The gnuplot options are very basic. Under <i>Ranges</i> you can enter the start and end digits for the x- and the y-axis. The default is an asterisk, which will result in gnuplot creating the digits automatically, according to the values set in the markup text.
<table width="100%"><tr><td align="center"><img src="images/plot2.png"/></td></tr></table>
The tab called <i>Labels</i> serves as an assistant to determine some visual aspects of a graph:

<li><i>Title</i> will create a title for your graph, which will be placed at the top of the rendered image.</li>
<li><i>X-Label</i> and <i>Y-Label</i> will create captions for the x- and y-axis.</li>
<li><i>Grid</i> and <i>Grid layer</i> work similiar to the guides/page grid settings in Scribus, except that the grid in the graph will become part of the rendered image. You can choose between no grid at all, the major grid ("Major ticks only") and major plus minor grid ("Major and minor ticks"). Just like in Scribus you can also decide to have the grid rendered in the background or in the foreground.</li>
<li><i>Zero axis</i> will create a dotted line to indicate either the x- or the y-axis, or both. Note that using any grid will make the setting of any zero axis unnecessary, as both use the same colour. If you want to use a different line style for grid and the axes, you have to do this in the markup text. Likewise, adding a z-axis requires the editing of the graph's source code.</li>

<p>For more information see the <a href="">official gnuplot website</a>.</p>


There are no additional options for dot/Graphviz available.

<p>For more information see the <a href="">official Graphviz website</a>.</p>


<table width="100%"><tr><td align="center"><img src="images/povray.png"/></td></tr></table>
<p>The editor offers only one tab for the rendering of POV-Ray files, namley "Rendering Options:" </p>
<li><i>Quality</i> provides the same seven quality levels as the POV-Ray command-line interface, and the editor uses the same default level ("Compute media and radiosity"). Otherwise, the quality levels are listed in an ascending order, "Just show quick colors" providing the lowest quality.</li>
<li><i>Antialiasing</i> is a technique to "smoothen" edges in a rendered image. It can dramatically improve the quality of an image, but using it may result in much longer rendering times. The options <i>Antialiasing Threshold</i> and <i>Antialiasing Depth</i> are explained in detail in the POV-Ray documentation, but the default values should suffice in most cases.</li></ul>

<p>For more information see the <a href="">official POV-Ray website</a>.</p>

<p>Once you have created the markup
to your satisfaction, you can click the "OK" button.</p>
<p>If you made a mistake, and the
external program cannot render your markup, Scribus displays an error
<table width="100%"><tr><td align="center"><img src="images/rf8.png"/></td></tr></table>
<p>A blue X in the Render Frame along with an error message will
then indicate that no content could be rendered:</p>
<table width="100%"><tr><td align="center"><img src="images/rf-error2.png"/></td></tr></table>
<h2>Additional Notes</h2>
<p>If you look at the context menu
for Render Frames, you will get the impression that they are image
frames. In a sense, that's correct, as you can change the preview
settings for Render Frames or update the content. There is, however,
a major difference: As said above, the markup text ist stored within
a Scribus file, and the rendered content is always created "on the
fly." Each time you open a Scribus file that contains a Render
Frame, Scribus will run the respective program that's necessary to
render the content and create a temporary image file which will then
be loaded into the frame. This is why Render Frames aren't listed in
<i>Extras &gt; Manage Images</i>.</p>
<p>This behaviour has some
consequences. While you can use a Scribus file with images on another
computer by using <i>File &gt; Collect for Output</i>
and copying the resulting archive to another machine, Render Frames
require the presence of the used <i>software</i>
on this machine. Moreover, the feature might not work between
different operating systems, because the command-line options can be
<p>Another limitation is that you can't apply any image effects to Render Frames.</p>

<p>To make Render Frames work, you need to have the required programs
installed on your computer. By default, Scribus supports five
programs, namely LaTeX, Lilypond, gnuplot, dot/Graphviz and Lilypond. On Linux,
your package manager will take care about the installation and the
dependencies of the software. On other platforms you might need to
install the programs separately and edit some configuration files.</p>
<p>If you open the tab "External Tools" in <i>File &gt;
Preferences</i>, you see the configuration options for Render Frames
at the bottom of the dialog:</p>
<table width="100%"><tr><td align="center"><img src="images/rf1.png"/></td></tr></table>

<p>Under "Configurations," Scribus shows the default configuration files. Each program you want to use from within Scribus needs a separate configuration file. To add a new program to your Render Frames, you have to create an XML file with some required settings. Below you see an abridged and commented gnuplot configuration file, which will serve as an example:</p>

<p><code>&lt;editorsettings description="Gnuplot" icon="gnuplot.png"&gt;</code> This line sets the description of the program, as well as the icon for the drop-down list in the Render Frame Editor. It must be stored in the same directory as the XML file. You can use  PNG, XPM and SVG icons.</p>
<p><code>&lt;executable command="gnuplot"&gt;</code> This is the command-line call of the program. You can only use software that can work on the command-line. Also, the program needs to be able to create output in either PNG, PDF or EPS format. By default, Scribus uses the command-line options for Linux/UNIX systems.</p>
<p><code>&lt;imagefile extension=".png"/&gt;</code> Here you tell the editor which file format it has to expect from the external program.</p>
<p><code>&lt;highlighter&gt; &lt;/highlighter&gt;</code> This part is mainly interesting for programmers, as it allows for the creation of indvidual syntax highlighting schemes by using Regular Expressions. For further information see: <a href=""></a> and <a href=""></a>.</p>
<p><code>&lt;empty-frame-text&gt;</code> Here you can enter sample text in the
markup language of the program you want to use, for instance:</p>
<p><code>plot sin(x), (cos(x))**2</code></p>
</p><code>&lt;preamble&gt;</code> If the markup language you
want to use requires a preamble, you can enter it here. It will not
be displayed in the editor.</p>
<p><code>&lt;postamble&gt;</code> If the markup language you
want to use requires a postamble, you can enter it here. It will not
be displayed in the editor.</p>
<p><code>&lt;tab type="settings"&gt;</code> Here's where translations to existing GUI strings as well as new tabs or other UI elements can be added via simple XML entries, for example:</p>

<p>To add a new configuration file, click on the "Add..."
button, which will bring up a file dialog. Select your file and click
"Open." The file will then be added to your Render Frame
<p>By moving entries of XML configuration files in the list up or
down, you can change the order of entries in the editor's drop down
list. If you want to use a different XML configuration file for a
particular markup language (for example, if you need another default
preamble for LaTeX frames in a project), you can change the path to
the alternative file by clicking on "Change ..." or simply add a new configuration file with an appropriate name, like "MyLateX".</p>
<br>If you prefer another editor for your markup, for example if you can't live without Emacs or vi, or if the editor window is simply too small for you, you can override the built-in Scribus Render Frame Editor by using
another editor like vi or Kate. Just insert the path to the
executable file in the text field "External Editor." The external editor won't override the Render Frame editor: As soon as
you save your markup from the external editor, Scribus "intercepts"
the data and renders the output into the frame or will display error messages in the "Program Messages" field. The interception also
means that any change to the markup text won't be saved anywhere but
in your Scribus file. If you haven't specified an external editor in <i>Preferences &lt; Tools</i>, Scribus will display an error message:</p>
<table width="100%"><tr><td align="center"><img src="images/rf-error3.png"/></td></tr></table>
<p>In addition, you have the option to start with an empty frame. By checking
"Force DPI," Scribus will render the output of every Render Frame with the resolution
set in the spinbox to the right. It's set to 72 dpi by default for
performance reasons. If you want to produce a document for
professional printing, you will want to choose a higher resolution.</p>