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 125: | Line 125: | ||
! Function syntax | ! Function syntax | ||
| | | | ||
− | * Sometimes there is a space | + | * Sometimes there is a space after the colon that separates the arguments, sometimes not. |
* Sometimes there is an unnecessary space before or after the opening bracket. | * Sometimes there is an unnecessary space before or after the opening bracket. | ||
* Sometimes argument names begin with capital, sometimes not. | * Sometimes argument names begin with capital, sometimes not. | ||
− | |||
|- bgcolor="#FFF" | |- bgcolor="#FFF" | ||
! Function arguments | ! Function arguments |
Revision as of 07:57, 9 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)
string "Syntax" |
|
---|---|
string "Example" |
|
Function syntax |
|
Function arguments |
|