Formatting Vaadin Documentation with AsciiDoc
This document briefly describes basic styling of Vaadin AsciiDoc documentation.
|The content here is still preliminary. Old but mostly valid instructions are given in the AsciiDoc Reference for Vaadin Documentation (PDF).|
Images include screenshots and diagrams.
They must always have a caption and an ID, unless inside a step-by-step list.
The ID must follow the ID hierarchy of the containing section.
It must be prefixed with
Images must always be referenced from text.
The result is shown in <<figure.contributing.formatting.image.example>>. [[figure.contributing.formatting.image.example]] .An example of an image image::img/mymodule-example.png[width=70%, scaledwidth=100%]
It would render as:
Images should be located under img sub-folder.
The caption may not be in title case.
References to images use the caption text in the reference. However, it is used differently in Vaadin Docs and the print edition.
In Vaadin Docs, it is shown as is in the link.
In print or PDF version, the reference includes "Figure x.x <caption>", with the chapter number and figure number in the chapter.
The result is shown in Figure 1.1, "An example of an image".
Requirements for Illustrations
Illustrations have the following requirements:
- Always use white background
Paper is white.
When taking screenshots, use a white background when necessary. Make sure the white background does not get transparent when taking screenshots.
- Do not use transparency in images
PNG and GIF images allow transparency. While they may show fine in the website, in PDF the transparent parts are rendered as black. This makes them very ugly.
- Use high resolution for screenshots
Otherwise, the pixels will show up ugly when the images are scaled. You can use the browser zoom feature to enlarge Vaadin UIs. Scale the images as described in Image Scaling.
- Minimize screenshot content
Space is prescious escpecially in the print edition.
Select only the relevant area for the screenshot. Sometimes, adding some cut context may clarify the screenshot. Some views or dialog windows can be overly complex or large. You should consider simplifying them with an image editor. You can use Photoshop or Gimp or whatever.
- Fonts must not be too small
The text column in the print edition is 82 mm (3.23 inches) wide. Height of the normal font is 2 mm or 6 points (1/72"). That means around 1/40th of the text column width. Text in diagrams should not be much smaller than this. If text is less than half of this, it is unreadable.
For example, if an image is 800 pixels wide and scaled as 100%, the normal font should be 20 pixels high. Text would have to be at least 10 pixels high, and anything smaller would anyhow be blurry.
Images are displayed in at least three formats: Vaadin Docs website, pocket-book sized print edition, and large size PDF. There could also be an additional ePub format. All images need to be scaled for all these resolutions.
AsciiDoc has two scaling parameters:
This parameter is used for the HTML web edition in Vaadin Docs. The images are automatically limited to the maximum width of the text area.
This parameter is used for the print and PDF editions. It is used as is for the pocket-size edition. For the large PDF edition, it is multiplied by 0.8, as otherwise the images intended for the print edition would get too large.