Difference between revisions of "Documentation/Dashboard/Help Style Guide"
From Apache OpenOffice Wiki
< Documentation | Dashboard
(→Style inconsistencies (see also issue 54559)) |
(→Style inconsistencies (see also issue 54559)) |
||
Line 127: | Line 127: | ||
* "Variable" normally appears as '''Variable''' | * "Variable" normally appears as '''Variable''' | ||
|- bgcolor="#FFF" | |- bgcolor="#FFF" | ||
− | ! | + | ! Function arguments |
| | | | ||
− | * | + | * Function arguments sometimes appear as <argument>: and sometimes as <'''argument'''>. |
|} | |} | ||
==Dialog descriptions (reference files)== | ==Dialog descriptions (reference files)== |
Revision as of 10:19, 8 October 2007
Contents
Help "Guides" (How-to instructions)
Current Style
A typical guide follows this scheme of paragraph styles:
Style | Function | Example |
---|---|---|
hlp_aux_bookmark | Index entry | <BOOKMARKVALUE>tables;calculating across</BOOKMARKVALUE> |
hlp_head1 | First level heading | Calculating Across Tables |
hlp_paragraph | Introductory feature description, often beginning with "You can..." | You can perform calculations that span across more than one table in a text document. |
hlp_listitem | Step-by-step description | 1. Open a text document, insert two tables, and type numbers in a few cells in both tables.... |
hlp_aux_embed | "Related Topics" section with links to other help files | <EMBED href="text/shared/00/00000004.xhp#related"> |
hlp_aux styles = Styles that are created automatically when you insert a text element by the help authoring menu
Several other paragraph styles can be inserted in this framework:
- hlp_tablehead and hlp_tablecontent for tables
- hlp_tip, hlp_note and hlp_warning for tips, notes and warnings
- hlp_head2,..., hlp_head5 for further heading levels
- hlp_example
- hlp_code for code snippets (variables for ex.)
- hlp_default
- hlp_head
There are also character styles:
- hlp_acronym
- hlp_aux_comment
- hlp_aux_parachanged
- hlp_aux_tag
- hlp_emph
- hlp_keycode
- hlp_literal
- hlp_menuitem
- hlp_path
Style inconsistencies
Headings |
|
---|---|
Tables | Misuse of hlp_paragraph in table content. (ex. Writer index entry "fields;user data"). |
Bullets |
|
Numbered lists |
|
Tips, notes and warnings |
|
Related topics | Different styles in the "Related topics" link list: help_aux_embed and hlp_paragraph. |
Character styles |
|
Order of styles | Normally, How to's are introduced by short feature descriptions. But enter Writer index entry "styles;finding": in the "Navigator" section, the order is inverted. |
Broken semantic entities | Ex: Writer index entry "deleting;footnotes": the sentence with the hand symbol semantically belongs to the bullet point above. But this is not visible in the layout. This sentence should be indented. |
Bad Style
- Bullets (action alternatives) under Numbering (steps in To Do's) look ugly. They should be more indented, so that the bullet is directly under the first letter of the numbered paragraph above. But bullet text that does not refer to a preceding numbered paragraph should not be indented.
- Icons in bullet lists are disturbing the layout (see for example shared index entry "text;copying by drag and drop")
Calc functions
The Calc functions are described in 22 files from text/scalc/01/04060101.xhp up to text/scalc/01/04060185.xhp. In the Calc Help they can be found under the index entry "Calc functions".
Style inconsistencies (see also issue 54559)
Syntax string |
|
---|---|
Example string |
|
Variable string |
|
Function arguments |
|