Yelp Icons

This page details the icons that are need in Yelp and gnome-doc-utils to make DocBook and Mallard documentation hot. In addition to beautiful colorful graphics, we should have high contrast and high contrast inverse of all the icons (with the exception of the watermarks, which should just be turned off for high contrast rendering).

Admonition Icons

DocBook and Mallard both have some form of admonitions -- parenthetical information set off from the normal text. For an example, see the BeanStalk mockup. DocBook provides the following types of admonitions:

• caution -- A note of caution

• important -- An admonition set off from the text

• note -- A message set off from the text

• tip -- A suggestion to the user, set off from the text

• warning -- An admonition set off from the text

There doesn't seem to be any agreed-upon distinction between caution and warning, and Mallard only contains one of them. The same icon can probably be used for both.

In addition, Mallard provides the following admonition:

• bug -- A note about a known bug the user may encounter

Here are some design pointers:

• They should have the same general style, and feel like they belong together.
• They should be no larger than 48x48. I could be convinced to use smaller graphics.
• They should look nice when converted to grayscale and when printed on low-resolution devices.
• They should have minimal visual noise, so as not to distract from the reading.

The following table shows the icons currently used by Yelp, Fedora, and Norm's DocBook stylesheets. I've also added a row for the currently accepted new icons.

Navigation Icons

Navigation links help you move about pages in a document. Using icons on these links reinforces the relationship of the link to the current page. The following navigation links are common:

• previous -- The page or section immediately before this one in linear order.

• next -- The page or section immediately after this one in linear order.

• up -- The parent section which contains this page or section.

• top -- The top-level page for the document.

See the navigation links in the header and footer of the BeanStalk mockup for an example.

Some design notes:

• They should have the same general style, and feel like they belong together.
• They should be a size that's suitable for sitting alongside text. Obviously, readers' font sizes will vary, but 22x22 works well for most people.
• They should not be confused with the back and forward icons.
• Print quality is of relatively little importance, since navigation links should be suppressed in print output, where they're useless.

Watermarks

I'm a sucker for watermarks. Currently, Yelp adds watermarks on block quotes, and it has the ability to add watermarks on code blocks and screen elements. The BeanStalk mockup has examples of block quote watermarks and code block watermarks.

Yelp allows translators to specify an image to use for a block quote watermark. It provides images of different quote characters, currently U+00AB, U+00BB, U+201C, U+201D, and U+201E. I'm generally happy with these watermarks, and I don't think they need to be replaced. (I am, however, open to being convinced otherwise.)

Yelp is able to use different code block watermarks for different types of code, if images are available. This would allow us to use different watermarks for C, C++, Python, XML, etc. I don't currently have any syntax-specific watermarks, but I'd sure like some.

Screen elements are basically what you would type in and get back out at a shell. A watermarkified version of the terminal icon could make a nice watermark for screen elements.

Some design notes:

• The code block and screen watermarks should hang down from the top right corner. They will generally be surrounded by a border, so it's OK if they end abruptly on the top and right.

• The exception to the above is RTL languages, where the watermark may hang down from the top left corner. For some watermarks, it's probably sufficient to just mirror the images. But some watermarks may need a custom-made RTL version.

• Watermarks should be fairly light and contain little or no color. The lightness should be accomplished with transparency, so that the same watermark will work on different background colors.
• Watermarks need to have minimal visual noise so as not to distract from the text.
• Watermarks should be suppressed when printing, so print quality is relatively unimportant.

Status Markers

Mallard contains document status information, which we display prominently for writers and editors, but suppress for regular readers. We will likely shoehorn this mechanism back into DocBook. For an example of how version information might be rendered (without fancy icons), see the example Mallard rendering. The following statuses are currently defined:

• stub -- Little or no content has been written.

• incomplete -- Some content has been written, but more is needed.

• draft -- All content has been written, but may need revisions.

• review -- All content has been written and revised, and reviews are needed.

• final -- The document is deemed complete.

Here are some design pointers:

• They should have the same general style, and feel like they belong together.
• They should be easy to distinguish from each other at a glance.
• 24x24 is probably a good size.
• Print quality is of relatively little importance.