These are sketches for a new help format, to make writing help easier for Gnome applications.
Principles
- Encourage individual pages on single topics.
- Have the fewest elements practical.
- Where an element works the same way as an XHTML 1.0 element, use the same name.
- Where an element works differently from an XHTML element, use a different name.
Contents
Navigation: help, title, keywords
Lists: ol, ul, li, dl, ql, dt, dd
Tables: table, thead, tbody, tr, th, td
Other structure: h, blockquote, p, if, div
Formatting: code, label, blockcode, em, strong, b, i
Interactivity: link, button
Multimedia: object
Example page
Elements
help
The help element has two attributes:
id -- a globally-unique identifier for the page. For example, id="org.gnome.foobrowser.printing.margins".
parent -- one or more comma-separated help page id values, representing the pages that this page is a child of. The page will be presented in the list of child pages from all pages represented by the parent values.
keywords
Contains a comma-separated list of words and strings that people are likely to search for when wanting help provided by the current page. Include common synonyms and misspellings of the terms being discussed.
Example: <keywords>desktop, wallpaper, wall paper, background, theme</keywords>
link
The link element is designed for fault-tolerant links between documents. It has two attributes:
to (optional) -- the URL of the page being linked to.
search (compulsory) -- a search string. A help viewer should present results for this search string if a link is activated either with the to attribute not present, or with the resource represented by the to attribute being unavailable for any reason.
Example: <link to="ghelp:gnome.org.desktop.files.opening" search="how to open files">how to open files</link>