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

From Apache OpenOffice Wiki
Jump to: navigation, search
(Calc functions)
(Calc functions)
Line 8: Line 8:
  
 
{| cellpadding="3" cellspacing="1" style="background-color: #666; margin-left: 3em;"  
 
{| cellpadding="3" cellspacing="1" style="background-color: #666; margin-left: 3em;"  
|- bgcolor="#DDDD"
+
|- bgcolor="#DDD"
 
! Style !! Function !! Example  
 
! Style !! Function !! Example  
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
| hidden text||Index entry|| <BOOKMARKVALUE>DATE function</BOOKMARKVALUE>
 
| hidden text||Index entry|| <BOOKMARKVALUE>DATE function</BOOKMARKVALUE>
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||
 
||
 
* hlp_head2
 
* hlp_head2
Line 19: Line 19:
 
* capital letters
 
* capital letters
 
||Second level heading|| <div style=" font-weight: bold; font-size: 140%; "> DATE </div>
 
||Second level heading|| <div style=" font-weight: bold; font-size: 140%; "> DATE </div>
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
| hlp_paragraph||Function description || This function converts a date written as year, month, day to an internal serial number and displays it in the cell's formatting. The default format of a cell containing the DATE function is the date format, but you can format the cells with the 0 number format, which displays the internal serial number of the date as a number.
 
| hlp_paragraph||Function description || This function converts a date written as year, month, day to an internal serial number and displays it in the cell's formatting. The default format of a cell containing the DATE function is the date format, but you can format the cells with the 0 number format, which displays the internal serial number of the date as a number.
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||
 
||
 
* hlp_head3
 
* hlp_head3
Line 28: Line 28:
 
* without colon
 
* without colon
 
||Third level heading|| <div style=" font-weight: bold; font-size: 130%; "> Syntax </div>
 
||Third level heading|| <div style=" font-weight: bold; font-size: 130%; "> Syntax </div>
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||
 
||
 
* hlp_code
 
* hlp_code
Line 37: Line 37:
 
* mandatory quotes must be entered in the syntax code
 
* mandatory quotes must be entered in the syntax code
 
||Syntax definition || DATE(Year; Month; Day)  
 
||Syntax definition || DATE(Year; Month; Day)  
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||  
 
||  
 
* hlp_paragraph
 
* hlp_paragraph
Line 43: Line 43:
 
* argument is bold without colon
 
* argument is bold without colon
 
||Explanation of function arguments || '''Year''' is an integer between 1583 and 9956 or 0 and 99. In '''Tools - Options - StarOffice - General''' you can set from which year a two-digit number entry is recognized as 20xx.
 
||Explanation of function arguments || '''Year''' is an integer between 1583 and 9956 or 0 and 99. In '''Tools - Options - StarOffice - General''' you can set from which year a two-digit number entry is recognized as 20xx.
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||  
 
||  
 
* hlp_head3
 
* hlp_head3
Line 50: Line 50:
 
*without colon
 
*without colon
 
||Third level heading||  <div style=" font-weight: bold; font-size: 130%; "> Example </div>
 
||Third level heading||  <div style=" font-weight: bold; font-size: 130%; "> Example </div>
|- bgcolor="#FFFF"
+
|- bgcolor="#FFF"
 
||
 
||
 
* hlp_paragraph
 
* hlp_paragraph

Revision as of 10:26, 6 February 2008

Help "Guides" (How-to instructions)

Calc functions

A typical help text for a Calc function should follow this scheme of paragraph styles:

Style Function Example
hidden text Index entry <BOOKMARKVALUE>DATE function</BOOKMARKVALUE>
  • hlp_head2
  • 16p
  • bold
  • capital letters
Second level heading
DATE
hlp_paragraph Function description This function converts a date written as year, month, day to an internal serial number and displays it in the cell's formatting. The default format of a cell containing the DATE function is the date format, but you can format the cells with the 0 number format, which displays the internal serial number of the date as a number.
  • hlp_head3
  • 14p
  • bold
  • without colon
Third level heading
Syntax
  • hlp_code
  • no blank before and after parentheses
  • arguments are separated by semicolon and blank
  • arguments begin with a capital letter
  • arguments that consist of more than one word are contracted (ex.: DegreesFreedom)
  • mandatory quotes must be entered in the syntax code
Syntax definition DATE(Year; Month; Day)
  • hlp_paragraph
  • 10p
  • argument is bold without colon
Explanation of function arguments Year is an integer between 1583 and 9956 or 0 and 99. In Tools - Options - StarOffice - General you can set from which year a two-digit number entry is recognized as 20xx.
  • hlp_head3
  • 14p
  • bold
  • without colon
Third level heading
Example
  • hlp_paragraph
  • starting with an equal sign
  • character style hlp_input for example text and entries
  • without blanks
  • results are not bold
  • no quotes, except if they are literal
  • use the new character style hlp_input for data that have to be entered literally and for examples
Example =DATE(00;1;31) yields 1/31/00 if the cell format setting is MM/DD/YY.


Distribution of Function Descriptions in the Help (see also issue 71289)

  • One file for every Calc function: Every Calc function should be presented as a self-contained entity as we have it already for some functions like DATE, HOUR, YEAR and some others.
  • One function list for every function category (main_{categoryname}.xhp): The individual Calc functions should be bundled in a category file. These category files should contain a list of the related functions, each with a short description (that can be taken from the Calc function file) and a link to the corresponding Calc function file.
  • One list of categories (main_functions.xhp): Overview of all categories with links to the categories pages. Therefore it would be better to name it main_categories.xhp.

Checklist for the Completeness of Function Descriptions

Here are some hints related to the contents that should be considered in every function description although they are sometimes missing in the actual help files.

  • Think global when you give examples. The english documentation is an international one.
  • Give unambiguous examples.
  • Mention differences to Excel.
  • Advise of argument types that are silently converted.
  • Advise of general settings that influence the result.
  • Mention the mathematical formula, which is used to calculate the result.
  • Advise of incorrect arguments that generate no error.
  • Tell the user, if named ranges, named formulas, labels or named data ranges are not resolved to their content or are forbidden.
  • Tell the user if internal underflow or overflow is not automatically detected. Tell about the accuracy if possible.
Personal tools