Help:SVG guidelines

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search

Shortcut: Help:SVG guidelines

This page in a nutshell:
  1. Pure sourcecode-edits are not allowed
  2. Massuploads need a bot-flag and consensus by the community. For SVG-Bugfixing you can ask User_talk:SVGWorkaroundBot
  3. SVG file minimization is often buggy and does generally not justify reuploading even if it makes the file valid

SVG files are generally preferred over bitmap files not only because they scale better, but also because they are easier to edit. The most important thing is that SVG files are rendered correctly, so SVG elements which are not supported by librsvg (MediaWiki's SVG rendering engine) should be avoided. For example, librsvg does not support the SVG textPath (text painted along a path) element. In addition, SVG files should be usable in other SVG environments, so SVG files should avoid uncommon SVG elements such as flowRoot.[1]

Background[edit]

SVG is an abbreviation of scalable vector graphics. SVG is an XML (extensible markup language) file format, so it must follow XML as well as SVG standards. The SVG standard has XML elements that will draw lines, curves, rectangles, circles, text, and other graphic shapes. SVG can specify fill colors, fill patterns, gradient fills, and filter effects such blurring. Font sizes, styles, and families may also be specified.

If an SVG file is viewed in a browser, then the browser has the task of converting the SVG description to a visible image. For the most part, the browser will produce a reasonable image, but there can be some issues. Some SVG files may need specific fonts to show the intended image. If the browser does not have the appropriate font, then the result may be odd: the spacing may be off or the characters may not display. The same problem can happen with HTML. Your browser may or may not have a font for Egyptian hieroglyphs (𓀀𓀐𓀠) or Siddham script (𑖎𑖚𑖕𑖿𑖧𑖲𑖨𑖿𑖎𑖜𑖿𑖧𑖯).

Wikipedia pages do not serve SVG files directly. Instead of sending an SVG file to the browser, the wiki software (called MediaWiki) first converts the SVG file to a PNG bitmap and then sends the PNG file to the browser. The wiki servers do the job of converting the SVG file to an image. That has some benefits. The displayed image will be the same on any platform: it will not depend on which fonts the user has but rather which fonts are on the wiki servers. In addition, the PNG image is often much smaller than the SVG file, so the network bandwidth required to serve the image is smaller.[2]

Where the SVG file is converted to an image is often confusing or frustrating to users. A user can have an image that looks fine on her local system, but it looks much different or even horrible when uploaded to Commons. For example, the SVG file may use a commercial Adobe font such as "Stone Serif". That font is not available on the wiki servers (which use non-commercial / free fonts), so the serif font may be replaced by a sans-serif font — not what the user expected. In addition, the character widths of the substituted font may be much different. A text string may no longer fit in the allotted space and now collides with other features in the image. The user may have carefully lined up several text strings, but that alignment may now be lost.

Similarly, an SVG file that looks great on Commons may look much different when downloaded and displayed on a browser. The SVG may use the font "Liberation Sans"; when that sans-serif font is not available on the local machine, then the serif font "Times New Roman" may be substituted for it, and the different font metrics may produce an unwanted result.

Scalable does not mean linearly scalable[edit]

Although SVG means scalable vector graphics, that does not mean that the scaling is linear for all objects. Geometric objects such as lines, curves, and circles will be scaled linearly. Reducing a circle to 50 percent will reduce the radius to one half. Fonts, however, are scaled differently; they may not be scaled linearly. See PostScript § Font handling.

Text should be easy to read. That is easy to do with big characters and high-resolution displays, but it becomes difficult as the character size gets close to the display resolution. Adobe developed PostScript to have the ability to display readable fonts at small sizes. TrueType and OpenType fonts also have that ability. Consider a fixed-width typewriter font such as "Courier". At a fixed resolution, each character in the font will be an integer number of pixels wide. Say, for example, that each character is 6 pixels wide. Now say the SVG image is scaled down to 95% of its original size. Although the lines, curves, and other distances scale down, the font may stay 6 pixels wide — in other words, the text may stay the same absolute size even though the rest of the image is reduced. Even with the right font, an SVG file will not scale linearly.

The user may see this issue when SVG images are displayed at different sizes. An image that is 300 pixels wide may look fine, but it may not look right at 275 pixels. Some text may start overlapping other parts of the image.

When some users confront this problem, they simply convert the text to artistic curves so it will scale linearly. The better alternative is to understand the problem and leave extra space for the text. Generally, shoehorning some text into a tight space will not work at all resolutions. Leaving more space has other benefits. Not only will the image look right when scaled, it may also look OK when a different font is substituted. With extra room, language translations are simpler.

SVG versions[edit]

There are a few versions of the SVG specification, and those versions impact available features.

SVG 1.0 has many features, but not all of those features were implemented by user agents. In fact, SVG 1.0 expected user agents to implement only a subset of the specification's features. For example, an agent may display basic text strings but may not handle font baseline adjustments. An agent may or may not support text on a path. A mechanism (requiredFeatures attribute) allowed SVG code to test whether certain features such as extended text, filters, or animation are available.

SVG 1.1 (and its second edition) differs little from SVG 1.0. The requiredFeatures strings were changed,[3] but some agents did not give accurate reports of the available features. It is also unwieldy for SVG code to test for features and have alternate ways to draw the desired image. Instead, artists would use widely implemented SVG subsets. W3C developed a notion of which features SVG mobile implementations should support: SVG Tiny and SVG Basic.[4]

SVG 1.2 was a candidate recommendation that was never adopted. SVG 1.2 has new graphics elements, but they are seldom supported. Nevertheless, some user agents have implemented some features of SVG 1.2. For example, previous versions of SVG did not have flowed text (essentially paragraph text that the SVG agent automatically broke into lines). Inkscape implemented SVG 1.2 flowed text, but most other agents have not. Consequently, SVG with flowed text will not display correctly on most SVG agents.

SVG 2.0 brings many changes. It keeps a substantial portion of SVG 1.1, but it has removed some features. The SVG 1.0 tref element was seldom (if ever) implemented, so it has been removed. SVG 2.0 has also dropped support for using internally defined glyphs. SVG 2.0 has also dropped some DOM support. Consequently, a small number of SVG files that would display in SVG 1.1 agents may not display correctly in modern SVG agents. SVG 2.0 has added support for SVG 1.1 compatible flowed text.

For best compatibility, SVG files should use simple SVG 1.1 features. Even then, some agents (such as librsvg used by MediaWiki) do not support SVG elements such as text on a path. Even common SVG agents such as Firefox do not support font baseline shifts.

Different validations[edit]

SVG is an XML format, and one of the goals of XML was to encourage that XML files have valid syntax. There are several benefits of standardization and validation.

XML validity[edit]

The basic level of validity is the file is well-formed XML. Well-formed XML requires that the file contains one root element (e.g., the svg element) and every XML tag (e.g., <tspan>) is matched with a closing tag (e.g., </tspan>). Well-formed XML does not impose other restrictions such as the root must be the svg element, elements must be in a certain order, an element may only be a child of a specific element, or an element may have only a small set of attributes.

MediaWiki does not allow the upload of all valid XML/SVG files.[5] Some XML may be syntactically valid, but MediaWiki may not upload it.

MediaWiki restricts the valid character encodings to a small set listed in $safeXmlEncodings. Those encodings are essentially ASCII, UTF-8, UTF-16, UTF-32, and several Windows encodings. The encodings are declared in the XML processing instruction encoding attribute. The restriction limits uploads to character encodings that MediaWiki understands, and it prevents malicious SVG being hidden in unusual character encodings.

MediaWiki does not allow the upload of files with an xml-stylesheet processing instruction. Such instructions may refer to external files or may modify the XML to have malicious content.

MediaWiki also whitelists the allowable namespaces in an uploaded document. In general, it allows some namespaces from Adobe, Creative Commons, Inkscape, W3C RDF, and W3C SVG. It does not allow uploads that reference the XHTML namespace.

SVG validity[edit]

SVG validity goes beyond well-formed XML because SVG has more constraints that just XML. The root is an svg element. A text element may have title, desc, or tspan elements as children, but it may not have a g element child. Certain elements are permitted to have particular attributes.

These extra constraints may be defined by a document type definition (DTD) file. DTD files were developed before XML namespaces, so DTDs do not handle XML namespaces well. The problem is a DTD treats xlink:href as an attribute name rather than the href name in the xlink namespace. In general, a DTD validator will complain about attributes in unexpected namespaces (such as inkscape:role="line") because the validator sees an unexpected attribute.

More recent XML schema definitions can handle XML namespaces. Two common schemas are W3C XML Schema and RELAX NG.

To do SVG validation, the validation program needs an appropriate SVG DTD or SVG schema. The SVG file may identify a DTD by using the XML DOCTYPE declaration. Similarly, an SVG file may have a schema definition attribute on its svg element (much less common).[6] The validation program may learn what definition to use by guessing, by looking at the HTTP header, or by being told by the user.

Even if an SVG file is valid, MediaWiki may not allow it to be uploaded.[5]

MediaWiki rejects SVG files with DOCTYPE declarations it does not recognize. The declaration must have a SYSTEM keyword, the public identifier must start with -//W3C//, and the system identifier must be one of

In other words, the DOCTYPE must identify one of the standard SVG 1.0 or SVG 1.1 DTDs. This restriction prevents a script injection attack using private DTDs.

MediaWiki also restricts SVG files that have script elements or attributes that may contain scripts, such as the onload attribute.

MediaWiki restricts how SVG files may use URLs. In most cases, a URL reference must be an internal reference to the SVG file rather than an external reference; a elements may use http:// or https:// schemes to refer to external resources; data schemes must be a PNG or JPEG resource.

Librsvg bugs[edit]

Main gallery: Librsvg bugs.

Even if an SVG file is valid, that does not mean an SVG agent such as librsvg will render the file correctly. SVG agents have limitations and bugs. For example, librsvg does not support the textPath element. In addition, librsvg may not have access to some particular fonts, so it cannot display those fonts. For security reasons, librsvg is not allowed to access external files. On top of all of that, `librsvg` has some rendering bugs such as misspacing text strings.

There are tools to detect some of those issues and warn the user about them.

DTD or no DTD[edit]

DTD is short for en:Document type definition.

In SVG 1.1 it's this line:
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

There is imho no simple answer for SVG 1.1 (and SVG 1.0), generally as written on Help:SVG#cite ref-noDTD 5-0, DTD is not required nor is it recommended[7][8][9].

Beyond the specificities of (X)HTML processing, Doctype declarations in XML languages are only useful to declare named entities and to facilitate the validation of documents based on DTDs. This means that in many XML languages, doctype declarations are not necessarily useful.

— https://www.w3.org/QA/2002/04/valid-dtd-list.html#DTD below "Optional doctype declarations"

It is controversal if DTD should be added or removed, and in the end it is not very important

How to add DTD is explained here: de:Benutzer:Marsupilami/Inkscape-FAQ#Wie erstelle ich eine Datei die dem Standard SVG 1.1 entspricht? (German); in short: Add it as second line after the XML declaration, together the beginning of a file would look like this: 

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

SVG 1.2 and SVG 2.0[edit]

For upcoming Versions of SVG DTD is deprecated. SVG 1.2 and SVG 2.0 features are currently unsupported; see Category:Images with SVG 1.2 features, Category:Images with SVG 2.0 features.

Why validation is generally not desired[edit]

If a file is xml-invalid (not only svg-invalid), that would actually be bad, but such files imho cannot be uploaded (any more), because of the xml-parser of MediaWiki checks that and blocks such images (e.g. phab:T279240). If a file contains invalid attributes and/or elements that is often desired, some examples can be found at #Invalid elements that should be kept (grides,guides,labels,layer,...), they are often necessary for editing the file, and only a few of them influence rendering (such as e.g. SVG2.0-features such as vector-effect), and also should imho not be removed because they are ignored anyway if not understood.

Validity is non-objective, it depends on the validator, and

  • all validators will report e.g. line-height="1.25" (common for non-inkscape-files) as error, however the validators do not recognize the identical command style="line-height:1.25 (inkscape uses style="..."), therefore validity should imho not get so much attention as it seems.
  • often just syntactical errors about id tokens are claimed, e.g. starting with a number, containing a space, doublewise specified. Some tools specify useless ids for evereything! Any unreferenced id is obsolete, and formal errors about don't care.

When is optimizing/validating files desired?[edit]

If the file is already uploaded please read: #Optimizing SVGs that have already been uploaded

Remove before uploading[edit]

Before you upload a file for the first time please remove

  • CDATA/pgf-data – a description how to remove CDATA-blocks can be found here: Template:Cdata/doc
  • everything where you don't have the permission (sometimes embedded raster image files)
  • generally raster image files that are hidden/not visible (e.g. images in metadata or retraced Images)
  • all kinds of watermarks, whether they are visible or not

When is optimizing/validating files undesired? [edit]

Shortcut

Useless elements that should be kept[edit]

see Help:Inkscape#Advantages of uploading Inkscape images to Commons

Elements that should not be converted[edit]

  • <rect objects should in general not be converted to path-data, since it changes editing such files, and some older Inkscape version only handle <rect-data but not path-data in flowRoot, which makes converting difficult, see File:Medellin Kartell.svg
  • <style type="text/css", class=" – CSS allows editing of several objects together without grouping

Invalid elements that should be kept[edit]

Invalid elements that should be replaced[edit]

  • <flowRoot, see User:JoKalliauer/RepairFlowRoot#replace notempty flow-text using (Inkscape)
  • id=: a) Spaces can be replaced with "_". b) If the id starts with a number add a letter or a word before. c) If there is multiple times the same id, add a numbering or use data-name.
  • <sodipodi:namedview pagecolor="#ffffff" inkscape:pageopacity="1", might be replaced by <rect width="100%" height="100%" fill="#ffffff"/> or <circle r="1e4" fill="#ffffff"/>

Optimizing SVGs that have already been uploaded[edit]

If a file renders correctly, then it is generally undesirable to reupload it without visible changes. Reducing the precision or quality of an image or removing visible raster data should not be done.

Do not remove metadata that identifies authors and/or licenses.

There are some cases where uploading a new version may be desired:

  • Improving the content (e.g., updating data or improving the layout), but be aware of Commons:Overwriting existing files.
  • Making a workaround for a rendering bug for the current Wikimedia renderer.
  • Making a workaround for a common renderer/editor/checker (e.g., Chrome, Firefox, librsvg, Inkscape, Adobe Illustrator, Commons SVG Checker).
  • The file is not rendered by Wikimedia (e.g., due to timeout or improper rendering).
  • The file is used for educational use (e.g., SVG examples).
  • Improving the file so that it is easier for others to edit (e.g., replace path text with translatable text).
  • Adding machine-readable metadata (e.g., adding author and license information).
  • Adding more translations to a multilingual file. (Converting a monolingual file to a multilingual file may or may not be desirable.)
  • Replacing a Fake SVG with a real SVG is desired when the file is used.
  • Removing undesired watermarks or timestamps – but only when they are visible. In many cases, it may be appropriate to move the watermark/timestamp data to a metadata element.

There are some cases where uploading a new version is tolerated: (some might be controversial or case-dependent)

SVG sourcecode edits without visual change[edit]

Important: An edit should always lead to at least an externally visible or effective change ; In addition to a substantive change, for example, a typo correction, a PDfix or a typographic refinement, provided that it has no taste or cosmetic background. A pure syntax modernization or source code formatting does not justify a new article version and persistent database load. Also, no edits should be executed whose sole purpose is to resolve redirects .
translator: Google Translate of de.wikipedia help page (de:Wikipedia:Kleine Änderungen)

Mass-uploading of 'optimized' files, just to make file valid or reduce the code, is in general undesired, since reuploading

  1. needs some disk-space.
  2. tickles users watchlist and sends e-mail notifications (quote of Glrx >>More significant is tickling editor's watch lists. That's a big consideration in the restriction on robot editing of WP articles. A robot can make a trivial change to an article, and that can cause a hundred people to look at the updated article. That's a cost in man-hours.<<).
  3. needs rendering-time (if you read phab:T40010 or phab:T226318 or meta:SVG benchmarks, rendering-time is a serious issue, otherwise wikimedia would not use the buggy librsvg-Renderer).

Generally every reupload should contain a visible change (with some exceptions). If you just want to rerender a new thumbnail please check Help:Purge (?action=purge). Dummy edits should generally not be done to the file (except for changing metadata), only to the description page.

Using Optimizers[edit]

Generally it is always file dependent, but this options should be chosen to minimize bugs created by the optimizer.

How to optimize[edit]

Optimizing can be done (see https://css-tricks.com/tools-for-optimizing-svg/ for more options)

  1. Toolforge (uses scour and svgcleaner): https://svgworkaroundbot.toolforge.org/
  2. If you know how to edit a svg with a text editor: see User:Quibik/Cleaning up SVG files manually#Removing unnecessary content
  3. If you know how to use a terminal: There are three common svg-optimizers:
  4. Inkscape (free software; uses scour): Save file as Optimized SVG (.svg), see Help:Inkscape#Inkscape SVG vs. Plain SVG
  5. Inkscape, reduce the number of nodes: Mark the path to reduce nodes and press Ctrl & l
  6. Adobe Illustrator: Export the SVG with the option "Minify"[12] and if available disable “preserve illustrator editing capability” (this line has to be proved by someone with Adobe Illustrator)
  7. For everyone who has not installed anything and doesn't know how to use a text editor: https://jakearchibald.github.io/svgomg/ (uses svgo)
  8. https://css-tricks.com/tools-for-optimizing-svg/
  9. ...

scour[edit]

scour-project logo

--keep-unreferenced-defs --set-precision=6 --indent=space --nindent=1 --renderer-workaround --disable-style-to-xml --set-c-precision=6 --protect-ids-noninkscape --disable-simplify-colors--keep-editor-data

svgcleaner[edit]

svgcleaner logo

--indent 1 --resolve-use no --convert-shapes no --group-by-style no --join-arcto-flags no --join-style-attributes no --remove-comments no --remove-declarations no --remove-invisible-elements no --remove-metadata no --remove-nonsvg-attributes no --remove-nonsvg-elements no --remove-text-attributes no --remove-title no --remove-unreferenced-ids no --trim-ids no --ungroup-groups no --list-separator comma

svgo[edit]

svgo logo

--disable=removeMetadata[13] --disable=removeHiddenElems[13] --disable=removeUnknownsAndDefaults[14] --disable=convertPathData[15][16][17][18] --disable=removeXMLProcInst[19][20] --disable=cleanupIDs[21][22] --disable=cleanupNumericValues[23] --disable=convertShapeToPath[24] --disable=inlineStyles[25][26] --disable=minifyStyles[27] --disable=removeComments[28] --disable=removeEditorsNSData[29] --disable=removeRasterImages[30] --disable=removeTitle[31] --disable=removeDoctype[32] --disable=collapseGroups[33][34] --disable=removeStyleElement[35] --disable=removeOffCanvasPaths[36] --disable=removeEmptyContainers[37][38] --disable=removeElementsByAttr[39] --disable=convertStyleToAttrs[40] --disable=convertTransform[41][42][43][44] --disable=cleanupNumericValues[45] --disable=cleanupListOfValues[46] --disable=reusePaths[47]

Precision/benchmark files[edit]

Different files need a different minimum number of precision.

Other tools[edit]

Optimizing PNG[edit]

Lossless[edit]

Optimizing JPEG[edit]

Lossless[edit]

  • jpegcrop, the default Entropy Coding Method is Arithmetic, which is hardly supported, and should be changed e.g. to Huffmann optimized
  • jpegoptim, utility to optimize jpeg files. Provides lossless optimization (based on optimizing the Huffman tables) and "lossy" optimization based on setting maximum quality factor.

Lossy[edit]

There are many tools, this seems to be convincing (filesize/quality):

Optimizing PDF[edit]

Lossy[edit]

There are many tools, this seems to be convincing (filesize/quality):

See also[edit]

References[edit]

  1. ↑ flowRoot was part of the 2004 SVG 1.2 draft (https://www.w3.org/TR/2004/WD-SVG12-20041027/flow.html); it never achieved wide acceptance.
  2. ↑ The server-side conversion also has disadvantages: interaction and animations are lost.
  3. ↑ https://www.w3.org/TR/SVG11/feature.html
  4. ↑ https://www.w3.org/TR/SVGTiny/
  5. ↑ a b See https://github.com/wikimedia/mediawiki/blob/master/includes/upload/UploadBase.php
  6. ↑ The attribute is xsi:schemaLocation. MediaWiki blocks uploads that reference the xsi namespace.
  7. ↑ W3C – valid DTD list – Optional doctype declarations
  8. ↑ Don't include a DOCTYPE declaration
  9. ↑ W3C – It is not recommended that a DOCTYPE declaration be included in SVG documents.
  10. ↑ User_talk:TSamuel#"compressing"_svg-files
  11. ↑ Special:Diff/649229530
  12. ↑ https://helpx.adobe.com/cy_en/illustrator/how-to/export-svg.html
  13. ↑ a b #Invalid elements that should be kept
  14. ↑ #Invalid elements that should be replaced; (removes Flowtext)
  15. ↑ https://github.com/svg/svgo/issues/880
  16. ↑ phab:T217990
  17. ↑ https://github.com/svg/svgo/issues/1487
  18. ↑ https://github.com/svg/svgo/issues/1493
  19. ↑ phab:T327446
  20. ↑ Commons_SVG_Checker (WARNING: XML declaration not found and is strongly recommended)
  21. ↑ #Invalid elements that should be replaced (id=)
  22. ↑ https://github.com/svg/svgo/issues/1195
  23. ↑ https://github.com/svg/svgo/issues/1080
  24. ↑ #Elements that should not be converted (rect should often not be converted to path)
  25. ↑ #Elements that should not be converted (CSS should in general not be converted)
  26. ↑ https://github.com/svg/svgo/issues/1486
  27. ↑ https://github.com/svg/svgo/issues/888
  28. ↑ #Useless elements that should be kept (comments explain things in the source code)
  29. ↑ https://github.com/svg/svgo/issues/1096; keep grid and guide
  30. ↑ #Optimizing SVGs that have already been uploaded (You should not change the appearance of the picture, see File:Oxygen15.04.1-computer-laptop.svg)
  31. ↑ #Useless elements that should be kept; titles are used to describe/name the file.
  32. ↑ #Useless elements that should be kept; there are different opinions about it, but it is necessary for https://validator.w3.org/.
  33. ↑ #Useless elements that should be kept (Groups are used to group elements.)
  34. ↑ https://github.com/svg/svgo/issues/1057
  35. ↑ https://github.com/svg/svgo/issues/946
  36. ↑ https://github.com/svg/svgo/issues/1732
  37. ↑ https://github.com/svg/svgo/issues/1194
  38. ↑ https://github.com/svg/svgo/issues/1618
  39. ↑ https://github.com/svg/svgo/issues/945
  40. ↑ https://github.com/svg/svgo/issues/1735
  41. ↑ https://github.com/svg/svgo/issues/988
  42. ↑ https://github.com/svg/svgo/issues/1021
  43. ↑ https://github.com/svg/svgo/issues/1222
  44. ↑ https://github.com/svg/svgo/issues/1268
  45. ↑ https://github.com/svg/svgo/issues/1080
  46. ↑ https://github.com/svg/svgo/issues/1402
  47. ↑ https://github.com/svg/svgo/issues/1733
Retrieved from "https://commons.wikimedia.org/w/index.php?title=Help:SVG_guidelines&oldid=739117956"