Difference between revisions of "Documentation/Dashboard/Help Style Guide"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Help "Guides" (How-to instructions))
(Style inconsistencies (see also [http://www.openoffice.org/issues/show_bug.cgi?id=54559 issue 54559]))
Line 50: Line 50:
  
 
Most of the Calc functions are described in the 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".
 
Most of the Calc functions are described in the 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 [http://www.openoffice.org/issues/show_bug.cgi?id=54559 issue 54559])===
 
 
{| cellpadding="5" cellspacing="1" style="background-color: #666; margin-left: 3em;"
 
|- bgcolor="#FFF"
 
! string "Syntax"
 
|
 
* "Syntax" normally appears as '''Syntax''', but in the mathematical functions you can find also '''Syntax:'''
 
|- bgcolor="#FFF"
 
! string "Example"
 
|
 
* "Example" normally appears as '''Example''' but in the mathematical functions and in some individual cases in Analysis functions (Part 2) and spreadsheet functions you can find also '''Example:'''
 
|- bgcolor="#FFF"
 
! Syntax definition
 
|
 
* Sometimes there is a space after the semicolon that separates the arguments, sometimes not.
 
* Sometimes there is an unnecessary space before or after the opening bracket.
 
* Sometimes argument names begin with capital, sometimes not.
 
|- bgcolor="#FFF"
 
! Function arguments
 
|
 
* Function arguments sometimes appear as <argument> with or without a colon or semicolon, but mostly as <'''argument'''>.
 
* Function arguments are sometimes explained in different style that resembles the introductory function description (see for ex. the mathematical functions).
 
* Function arguments are not explained (ex.: GESTEP function).
 
|- bgcolor="#FFF"
 
! Example syntax
 
|
 
* Examples sometimes begin with the equal sign, and sometimes not.
 
* Results are sometimes bold, and sometimes not. (ex. Text functions)
 
|- bgcolor="#FFF"
 
! Missing example
 
|
 
* JIS function lacks an example as well as some analysis functions (part 1).
 
|}
 

Revision as of 13:15, 27 November 2007

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

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 Function description Returns TRUE if a cell is a formula cell.
hlp_head3 Third level heading Syntax
hlp_code Syntax definition 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.

Most of the Calc functions are described in the 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".

Personal tools