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: .. _example:

    1. Then you write the link to that label here.
  4. 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).

  5. 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.


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:

1
2
3
sudo apt-get install inkscape
flatpak install inkscape
snap 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: …


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: