SVGExport 1.06 (24-Sep-03)

Name:     ArtWorks SVG Exporter
Purpose:  ArtWorks module for SVG export
Author:   Martin Wrthner
Requires: RISC OS 3.5 or higher, ArtWorks 2
Status:    2003 Martin Wrthner; all rights reserved; see [6] below
          spr2png  Darren Salt, 1998-2003
WWW:      http://www.mw-software.com/

Welcome to the SVGExport module.

This module allows you to export ArtWorks documents as SVG files.

SVG is a platform-independent vector graphics format that was designed by the
W3C (the World Wide Web Consortium). It is an official internet standard and
based on the powerful XML standard for defining data structures for information
interchange.

In contrast to most other graphics file formats used on the internet, SVG is
vector-based, so shapes, text and images in your document are retained as
individual, editable objects. Shapes are defined using mathematical
descriptions (lines and curves), so can be rendered at any resolution.

There is a free SVGViewer plug-in for MS Internet Explorer (Windows and Mac)
and Netscape (Windows, Mac and Linux) produced by Adobe, one of the members of
the SVG design consortium. It can be downloaded from http://www.adobe.com/ This
viewer is the most comprehensive known implementation of the SVG format.

Various Windows and Mac applications are able to import SVG files, including
CorelDraw (10 and above - NOT Corel 9 because the beta SVG import filter for
Corel 9 implements an early version of the SVG standard that does not cope with
the files exported using SVGExport) and Adobe Illustrator.

There is an SVG viewer for RISC OS (written by Justin Fletcher, published by
Warm Silence Software). Unfortunately, the current release version (2.15) is
based on the same early version of the SVG draft as the Corel 9 filter. Hence,
it is very limited and likely to not display anything at all when loading a
file exported using SVGExport. Version 2.18 (currently beta) is much improved
and is able to display flat filled shapes and some text but does not support a
lot of the more advanced features, such as bitmaps, linear and radial fills,
pattern-fills, replications, text on a path, transparency, etc.

The SVG format is very complex, so it is likely that software vendors who claim
to support SVG have not implemented all of it. If you suspect that the
SVGExport module exports incorrect SVG code, please check with Adobe's
SVGViewer first before reporting the problem to me.

1) Using the SVGExport module
-----------------------------
After installing this module, you will find an additional entry "SVG..." in the
"File => Export" submenu of the main document menu. Choose this entry to open
the SVG export dialogue box. Alternatively, the keyboard shortcut Ctrl-Shift-S
opens this dialogue box as well.

1.1) The SVG export dialogue box

The SVG export dialogue box works in a similar way to other export dialogue
boxes. For instance, if you have BMExport (the bitmap export module) as well,
you will find this dialogue box very similar. There are various options to be
set up. Then, you may enter a file name for the SVG file in the input field
beneath the SVG icon, then drag the icon to a Filer window. Alternatively, fill
in a full path to save to and click on the OK button.

The dialogue box offer various options:

Version
-------
SVGExport only uses features that are present in the SVG 1.0 specification, so
it is recommended to select "SVG 1.0". In the unlikely event that some user
agent into which import the SVG file insists on seeing an SVG 1.1 file, you can
try selecting "SVG 1.1" instead. Since the SVG 1.1 specification is very recent
(14 Jan 2003), most user agents probably prefer SVG 1.0 files.

Area
----
This option only affects the overall page size as declared in the SVG file. If
you select "Page", then this is the page as defined in your ArtWorks document.
If you select "Drawing", then this is the area covered by exported objects
(i.e., either the Selection if the "Selection only" option is on or all objects
on exported layers if the "Selection only" option is off).

Layers
------
The default behaviour is to only export visible foreground layers. The option
"Include background layers" allows you to include background layers as well
(background layers are those below the bottom horizontal line in the layer
menu, and they are redrawn shaded). The option "Include invisible layers"
allows you to include invisible layers (invisible layers show an empty circle
in front of the layer name in the layers menu).

Export bitmaps
--------------
If "Export bitmaps" is on, then sprites and JPEGs are saved alongside the
exported SVG file and the SVG file contains the appropriate code to load and
render these images. Sprites are always exported in PNG format (converted using
Darren Salt's excellent spr2png utility that is included with SVGExport with
the author's kind permission).

If "Use sprite names as file names" is on, then the sprite's name as displayed
in the Sprite Pool is used as the file name (suffixed with "/png"). Otherwise,
the exported sprites are called "spr000/png", "spr001/png", etc. JPEGs are
always exported with names "jpg000/jpg", "jpg001/jpg", etc. If such a file
exists already, you are asked whether you want to overwrite it unless the
"Overwrite files without prompt" option (see below) is on.

Of course, bitmaps can only be saved alongside the SVG file if you export to a
storage medium, such as a hard disc or a network. If you directly save to
another application, then the bitmaps cannot be saved and you will see the
error message "Could not save bitmaps, because the export destination was not a
storage medium".

If "Export bitmaps" is off, then sprites and JPEGs in the ArtWorks file are
simply ignored.

Export pattern-fills as shapes
------------------------------
If "Export pattern-fills as shapes" is on, then all pattern-fills are
represented using shapes, similar to the way it is done in Draw export. If this
option is off, then the pattern-fill is exported as an SVG pattern, which
leads to considerably smaller files in the same way as pattern-fills in
ArtWorks use a lot less space than the shape representation in exported Draw
files.

This option is useful if the target application does not support SVG patterns
(e.g., the RISC OS SVG viewer) or if the SVG pattern looks different from the
pattern-fill in ArtWorks. Exporting pattern-fills as shapes ensures that the
fill looks the same in the target application, but at the expense of much
larger SVG files. It also means that the dynamic fill is replaced by static
objects, so you cannot subsequently edit the filled object in the target
application.

If "Export pattern-fills as shapes" is on, then this means that pattern-filled
text is always exported as shapes, irrespective of the setting of the "Export
text as shapes" option.

Expand replications statically
------------------------------
If "Expand replications statically" is on, then replicate objects (created
using the Replicate module) are exported by including several copies of the
replicated object. Otherwise, only one copy of the object is exported and
referenced several times.

This option is useful if the target application does not support the <use>
element of SVG that allows one object to be referenced several times.

Export text as shapes
---------------------
If "Export text as shapes" is on, then all text is exported as shapes. This
option makes sure that the text looks exactly the same as in ArtWorks but it is
no longer editable and the size of the file will be considerably bigger than
that of the same file with editable text.

Font name mapping
-----------------
This option enables mapping from RISC OS font names to font names on other
platforms. The only circumstance in which it makes sense to switch this option
off is when the exported SVG document is only to be used under RISC OS, which
is not very likely.

You will find a lot more details about font name mapping in section 1.2 "Text
export" below.

Font property mapping
---------------------
This option enables the mapping of certain parts of font names, e.g., "Bold" or
"Italic" to font properties in the SVG file (font-weight="bold" or
font-style="italic"). This is recommended for a small set of standard font name
extensions ("Medium", "Bold", "Italic", "Oblique"), which is what happens when
the "Standard" radio button is selected. In this case, other extensions, like
"Demi" or "Condensed" are left as part of the mapped font name, which enables
the target application to select the exact equivalent font, if present. If the
"Full" button is selected, then a lot more extensions are mapped ("Demi",
"DemiBold", "Cond", "Condensed", etc.), but this is unlikely to select the
exact equivalent font on the target platform. You are recommended to use the
"Standard" option unless you understand exactly how the SVG font selection
mechanism works.

You will find a lot more details about font property mapping in section 1.2
"Text export" below.

Overwrite files without prompt
------------------------------
This option applies to both the main SVG file and to sprite or JPEG files that
are exported. If this option is on, then you are not asked before an existing
file is overwritten.

Particular care must be taken when exporting various ArtWorks files as SVG
files to the same directory as the file names chosen for JPEG images (and for
sprites, if "Use sprite names as file names" is off) are always the same.

Selection only
--------------
If this option is on, only currently selected objects are exported, else all
objects are exported. In both cases, only objects on exported layers are
considered (see "Layers" above).

Choosing the right options
--------------------------
There is no general rule which options to choose. The default set of options is
the most useful combination of options in the general case. However, depending
on the target application you may want to put more emphasis on editability or
on exact preservation of the appearance of the ArtWorks illustration. For
instance, the appearance of text will be preserved exactly when "Export text as
shapes" is on, but it will no longer be editable. Switching off "Export text as
shapes" exports editable text but its appearance may differ if the target
application does not have the required font.

If file size is an issue, then you should certainly switch "Export text as
shapes", "Export pattern-fills as shapes" and "Expand replicates statically"
off.

If the target application offers very basic SVG support only, then just the
opposite (i.e., switching "Export text as shapes", "Export pattern-fills as
shapes" and "Expand replicates statically" on) is most likely to give good
results.

1.2) Text export

Text export is the most complex task when transferring vector graphics files
between applications, or even operating system platforms.

To sum it up: There is only one way to make absolutely sure that the text will
look the same way as it did in your original ArtWorks file: Using the "Export
text as shapes" option. This will cause each character to be represented by a
path (defined using lines and curves), so this will render correctly on all
platforms, without the need for the font used to create the text.

Of course, using the "Export text as shapes" option means that the text can no
longer be edited, and it will make the SVG file rather large because a sequence
of lines and curves is needed for every character instead of just exporting the
character itself.

Therefore, you are often likely to want to export text as editable text, i.e.,
switch the "Export text as shapes" option  off. However, in this case, you need
to be aware of the limitations of text export. Please note that these are NOT
limitations of SVGExport but they arise from the fact that not all the
necessary information needed for a successful export is available to the
exporter. In order to export correctly, the exporter would have to know the
exact characteristics of both the RISC OS fonts used AND of the fonts on the
target platform. Unfortunately, not even the necessary information about the
RISC OS fonts used can be obtained, not even to mention the characteristics of
the fonts on the target platform.

Therefore, you need to tell SVGExport about your own fonts and about the way
they are to be mapped to the fonts on the target platform.

If the fonts you use have an encoding supported by SVGExport (Latin1 or
EFFLatin1), if this encoding is declared correctly in the font map (see below),
and you have an equivalent font on the target platform to which the font is
mapped, then text will come out exactly as in ArtWorks, even including all
special characters, such as , the Euro sign etc.

1.2.1) Fonts and encodings

The information required is the "Encoding" of the font, i.e., which glyphs are
at which place in the font. A "glyph" is just another name for a shape that is
drawn for a particular character, e.g., the shape of the letter "A" or an arrow
pointing right.

The fundamental difference is whether a font is a "symbol" font or a "language"
font. In a "symbol" font the arrangement of glyphs in the font is arbitrary, so
you need an exactly equivalent font on the target system to correctly display
the symbols. In a "language" font, the characters are laid out according to an
encoding. If such text is to be exported, its encoding has to be known,
otherwise there is little chance that the same characters are displayed on
other platforms. Some fonts under RISC OS announce their encoding properly,
e.g., the ROM fonts and some professionally designed fonts, e.g., reasonably
new ones by EFF, but many do not.

Therefore, SVGExport does not try and read the font encoding information
offered by the OS because it would only be available for a small subset of all
fonts. It is often correct to assume that a font is laid out according to an
encoding called Acorn Latin1, which is the most commonly used encoding under
RISC OS. So, in case of doubt, SVGExport will use this encoding and translate
the text accordingly. Unfortunately, this will go wrong if the font is a symbol
font, and therefore, you need to tell SVGExport which of your fonts are symbol
fonts that should be left untranslated.

EFF fonts have offered a few extra characters for a long time, so they are laid
out according to an encoding called EFFLatin1 as opposed to Acorn Latin1. Under
RISC OS 4, some of the character positions have been taken for the ROM fonts,
but unfortunately, with a different layout, so for those characters, the
difference between Latin1 and EFFLatin1 is important.

So, assuming you have the same fonts on the target platform, and the RISC OS
font has Latin1 encoding, you need not do anything. If, however, the RISC OS
font is a symbol font or if it has EFFLatin1 encoding, then you need to add the
font to the user font map file to avoid text being exported incorrectly.

1.2.2) Font mapping

If you export text as text (as opposed to switching the "Export text as shapes"
option on), then the file needs to contain information about which font should
be used to render the text. Normally, you should switch the "Font name mapping"
and "Font property mapping" options on, otherwise the RISC OS font name is
placed in the file, without any translation taking place, which is rarely
useful because the target application and the target operating system platform
are unlikely to be able to interpret RISC OS font names, not to mention being
able to present an appropriate replacement font.

Therefore, you will find that it is necessary to map the RISC OS font names to
the font names used on the target platform. Unfortunately, there is no
platform-independent naming scheme for fonts, and besides, SVGExport has no
idea of knowing whether the target platform on which you eventually use the
file has an appropriate font installed at all.

You have various options when mapping fonts and you can define your own
font mappings. The mapping is defined inside !SVGExport in the file
!ArtWorks.Auto.!SVGExport.FontMap. This file is not user-editable but you
can create a file called FontMap2, in which you can add additional entries
which override entries in FontMap.

The FontMap file contains mappings of font families (e.g., "Trinity") or
specific fonts (e.g., "Trinity.Medium.Italic") to font families as used in the
SVG file. The format of the file is documented in the file itself.

When trying to map a RISC OS name, the exporter searches the mapping files
(FontMap2 first, if present, then FontMap) and locates the first matching
entry. Any entry in the mapping file is matched if the entry's name is a prefix
of the RISC OS font name to be mapped, e.g., an entry "Trinity" is a matching
entry when mapping the font "Trinity.Bold" or an entry "Trinity.Bold" can used
to map "Trinity.Bold.Italic". The remainder of the RISC OS font name (i.e., the
part that is not matched) is then used to map font properties if "Font property
mapping" is switched on.

For example, if the file contains the line "Swiss.Cond:EFFLatin1:Arial Narrow",
then "Swiss.Cond.Bold" is mapped to "Arial Narrow" with weight "bold". In this
case, the "Cond" part of the RISC OS font name is not interpreted because it is
already "consumed" by being specified in the mapping. If however, you only have
the mapping "Swiss" to "Arial", then both "Cond" and "Bold" are interpreted, so
if the "Full" property mapping is used, "Swiss.Cond.Bold" is mapped to "Arial"
with stretch "condensed" and weight "bold".

You can have specific and generic mappings for the same font in the mapping
file, but you need to place the more specific entries first, otherwise only the
generic mapping is found. So, an entry "Swiss.Cond.Bold" needs to be before an
entry "Swiss", otherwise it is never found.

2) Limitations
--------------
There are a few limitations, some of which are caused by limitations in the SVG
format itself.

Limitations caused by the SVG format itself:
- All colours are exported as unnamed RGB colours - unfortunately, SVG does not
  support CMYK or HSV colours
- SVG only supports "mix" transparency, so other transparency types ("bleach"
  and "stained glass") are exported as "mix" transparency
- Lines with differing start and end caps (butt, round, square) are exported
  with the start cap for both ends. Such lines cannot be created in ArtWorks,
  but they may be imported from Draw. Triangular start and end caps work OK
  because they are represented as arrowheads, so, e.g., a line with a round
  start cap and a triangular end cap, or the other way round, works fine.
- Font aspects (i.e., text with an X:Y size aspect other than 100%) cannot be
  represented accurately in SVG because SVG has no notion of font aspects.
  Currently, font aspects are ignored completely, so all text is exported as if
  it had an X:Y aspect of 100%
- SVG does not have any notion of flowing text, so text areas are broken down
  into individual words, each positioned on its own in order to represent
  the original layout. Each text area is exported as a single text object in
  SVG, so the text can still be selected in SVGViewer as if it was continuous
  text.

Limitations in SVGExport:
- Kerning and tracking are ignored when exporting editable text
- Skewed basic shapes (ellipses, rectangles and rounded rectangles) lose their
  identity when exported - they are exported as shapes
- Skewed text is exported correctly, but any fancy fills (linear, radial or
  pattern fills) of such text are incorrectly skewed
- Pattern fills with a lot of overlap (i.e., where neighbouring pattern
  elements overlap) can sometimes appear clipped when exported as SVG patterns
  (i.e., with the "Export patterns as shapes" option off)

If you find any additional problems, please let me know.

General notes:
- All object properties are exported using the so-called "presentation
  attributes" in SVG. The "style" attribute is not used, so the resulting SVG
  file is not "stylable SVG" as defined by the SVG standard.
- The exported SVG file has ISO-Latin1 encoding and characters that are not
  available in this encoding are exported using Unicode escapes - this relies
  on the font encoding being declared correctly for the font in question.

3) History
----------
Version 1.06 (24-Sep-03):
- removed some debugging code

Version 1.04 (07-May-03):
- works without requiring the 32-bit CLib on 26-bit systems by running a 26-bit
  spr2png under RISC OS < 5.00

Version 1.03 (02-Apr-03):
- corrected scaling of exported sprites - the scaling used to be correct only
  when the window scaling was set to 100%!

Version 1.02b (03-Mar-03):
- corrected path name of FontMap file specified in this file

Version 1.02 (03-Mar-03):
- made "Drawing" the default rather than "Page" to avoid confusion with
  browsers (e.g., Internet Explorer) not showing scroll bars with Adobe's SVG
  Viewer, so a page with some drawing in the bottom half only appears empty
  until panned using Alt-drag

Version 1.01 (28-Feb-03):
- removed layer name export as it caused more trouble than it was worth
  (in particular with the Apple4 file)

Version 1.00 (27-Feb-03):
- round and square line ends are exported correctly
- enveloped polygons and text corrected
- files with many graduated fills or patterns are exported correctly
- irritating spurious error message "Could not save bitmaps because destination
  is not a storage medium" is no longer reported after each export with bitmaps
- layer names are exported as "id" attributes (importers are unlikely to be
  able to make use of them though)
- exported SVG files are smaller due to having more default attributes at the
  layer level
- first release version

Version 0.18 (13-Feb-03):
- first released beta version


5) Contacting me
----------------
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/


6) Copyright
------------
The ArtWorks SVGExport module, related documentation and files are  Copyright
2003 by Martin Wrthner. All rights reserved. The software and documentation
may not, in  whole or part, be copied or transmitted by any means without the
explicit written consent of the copyright owner. Unless you have purchased a
site licence for this  software, it may be used on only one stand-alone
computer system at any time.

In order to use this software, you need a licence from the copyright owner. If
you do not have such a licence, you must delete this software, the SVGExport
module and its related files, now.

This software includes spr2png  Darren Salt, 1998-2003, which has been
included with the author's kind permission.
