Sample Chapter Title (h1)

This documentation uses ‘reStructured Text’ (reST) as its markup language. The below document outlines most of the elements used in this guide.

If you have never used reST before, please familiarize yourself with its syntax (links to cheatsheets below), or diligently copy-paste what you see here or in other parts of the documentation. Note that spaces (and how many there are) are always relevant. Without them, the automatical document creator does not understand what you mean, and may give unexpected results. Backticks (this one: `, not apostrophes: ‘) are used frequently in delimiting different elements.

Second level heading (h2)

It’s best to have this document opened as the finished web page, and as the source text in parallel. That way you can see the syntax, and how it will look when the documentation has been auto-created.

This is text in a paragraph. Separate paragraphs by an empty line. This is printed bold, and this is in italics. This is for code and other small commandline commands that are used inline.

Third level heading (h3)

Links to cheatsheets in a list:

Fourth level heading (h4)

A numbered list with useful links:

  1. Inkscape Website

    This is a paragraph in a list

  2. An internal link to another book chapter uses its file name (without the ‘.rst’): Link to 3D Boxes

  3. If you want to link to another section in this manual (this can be in any file, or in this one), you must put a so called label there (with underscore).

  1. Then you write the link to that label (no underscore) here.

  1. If you want to refer to a section that starts with a heading, you do not need to use a label. You can just directly refer to it like this: Third level heading (h3).

  2. A download link, e.g. for an example file that users can play with, will look like this: Link to Glyph A file


Images can be used within a sentence or line, or as a larger image with a description.

An image within a sentence can be something like this icon Icon for Selector tool. You decide on a name for the image that you put into the text. Then, you specify its properties in a separate block. It’s best to put these blocks at the bottom of the document (scroll down to the end to see it). This type of image can be described as an ‘inline image’.


All images that show a part of the Inkscape interface should be formatted like this and have the class ‘screenshot’, a caption and an alt attribute. Screenshots should be in the png file format and the relevant area should be as large as possible:

This text will be shown if the image cannot be loaded

This is a caption for the image. Text should wrap around the caption. You can add a ‘target’ line above, if you want to link to something.

This text will be shown if the image cannot be loaded

You can also use a two-column container, and the figures …

This text will be shown if the image cannot be loaded

… will fit on one or two columns, depending on the display width.


Images that are used for mere decoration look like this. You can use png images. If you want to use an SVG image, you must also provide a pdf with the same content and give it the same name. Then, you would need to replace the file extension by an asterisk in the page source.

_images/vector-format.png

Available classes:

  • for alignment: left, center, right

  • for size: small, medium, large


If you want to tell the user how to get somewhere using the menu, use the menu selection markup, e.g. Edit ‣ Preferences ‣ Input/Output ‣ Autosave


For a label in the interface, use the gui label markup, e.g. Enable gradient editing.


If you want to tell the user which key to press, use the keyboard shortcut markup, e.g. Ctrl + C.


For referencing a specific file on the user’s computer, use the markup for files, e.g. ~/.config/inkscape/preferences.xml


If you need to quote someone, or another document, do this by indenting by 4 spaces:

Inkscape is professional quality vector graphics software which runs on Windows, Mac OS X and GNU/Linux. It is used by design professionals and hobbyists worldwide, for creating a wide variety of graphics such as illustrations, icons, logos, diagrams, maps and web graphics. Inkscape uses the W3C open standard SVG (Scalable Vector Graphics) as its native format, and is free and open-source software.

—Inkscape Website


We can have different styles of admonition boxes:

Attention

Watch out for this!

Caution

Be careful!

Warning

Drawing can be addictive.

Danger

Don’t break Inkscape!

Error

Now you have it.

Hint

The status line in Inkscape is very useful.

Important

  • Start your computer.

  • Login.

  • Start Inkscape.

  • Select the rectangle tool.

Tip

Give the user a tip to have an easier time

with

things

in

Inkscape

Note

This is a note. You can add more contents below. Really.

And, by the way…

You can make up your own admonitions titles, too. However, you cannot choose their color.


Referring to terms in the glossary is a good way to help users have quick access to the help they need, e.g. you can use Path: (if you want to keep the exact spelling) or path (if you want to change the spelling, e.g. for plural, or to not use capitalization).


In case you ever want to put in a longer code block:

1sudo apt-get install inkscape
2flatpak install inkscape
3snap install inkscape

Dashes and other typography:

Please follow English typography guidelines for dashes. See https://en.wikipedia.org/wiki/Dash

En dash: –

Em dash: —

Ellipsis: …


We have inline formatting enabled to accommodate writing systems without spaces (e.g. Chinese, Japanese and Korean systems), so please keep in mind that some characters need to be escaped, namely underscores (_), asterisks (*) and pipe (|) characters. For example, if you want to use a literal asterisk in math equations:

Attention

In the Align and Distribute dialog, there are 2 rows with 6 alignment options in a row, which makes 6*2=12 alignment options in total.

In the example above, you should type 6\*2=12 to preserve the asterisk. Note that you only need to escape these characters when there is no surrounding markup. For code blocks and markup in the format :<markup>:`text`, there is no need to escape them.

1Long code blocks like this one do not need character
2escaping: _ * |. Other types of text blocks all require
3escaping.

The following won’t be visible in this location, but it will appear in any place where you write its ‘anchor’. Use the asterisk instead of the file ending, if there is both an svg and a pdf of the image file available. This should be the case for all icons of the Inkscape interface, as there is a complete set of them in the icons directory: