Difference between revisions of "Documentation/Dashboard/Help Style Guide"
From Apache OpenOffice Wiki
< Documentation | Dashboard
(→Current Style) |
(→Current Style) |
||
Line 123: | Line 123: | ||
| hlp_head2||Second level heading|| '''ISFORMULA''' | | hlp_head2||Second level heading|| '''ISFORMULA''' | ||
|- bgcolor="#FFF" | |- bgcolor="#FFF" | ||
− | | hlp_paragraph|| | + | | hlp_paragraph||Feature description || Returns TRUE if a cell is a formula cell. |
|- bgcolor="#FFF" | |- bgcolor="#FFF" | ||
| hlp_head3||Third level heading|| '''Syntax''' | | hlp_head3||Third level heading|| '''Syntax''' |
Revision as of 08:23, 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
Current Style
A typical help text for a Calc function follows this scheme of paragraph styles:
Style | Function | Example |
---|---|---|
hlp_aux_bookmark | Index entry | <BOOKMARKVALUE>ISFORMULA function</BOOKMARKVALUE> |
hlp_head2 | Second level heading | ISFORMULA |
hlp_paragraph | Feature description | Returns TRUE if a cell is a formula cell. |
hlp_head3 | Third level heading | Syntax |
hlp_code | Syntax code | ISFORMULA(reference) |
hlp_paragraph | Explanation of function arguments | Reference indicates the reference to a cell in which a test will be performed to determine if it contains a formula. |
hlp_head3 | Third level heading | Example |
hlp_paragraph | Example | ISFORMULA(C4) returns FALSE if the cell C4 contains the number 5. |
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 |
|