Style inconsistencies

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	Missing heading levels: After heading level 1 follows heading level 3. (ex.: Draw index entry "groups;entering"). Missing headings. (ex: Writer index entry "text;hiding": the first How to has no heading.) Writer index entry "right pages": hlp_head2 is not defined correctly. Heading sub-levels (To do...) sometimes have colons. Inconsistent wording in headings: To do..., -ing form, imperative, noun. Unnecessary headings, ex.: Writer index entry "form letters": hlp_head2 repeats the contents of hlp_head1, and no other hlp_head2 follows. Unformatted headings (ex.: Calc index entry "tables;view": headings are formatted as simple hlp_paragraph). Inconsistent use of capitals in subheadings (compare Shared index entry "mobile device filters" to Calc index entry "formats;conditional"). In Math some How To headings are formulated in FAQ style.
Tables	Misuse of hlp_paragraph in table content. (ex. Writer index entry "fields;user data").
Bullets	Different styles for bullet paragraphs (hlp_listitem and hlp_paragraph) produce inconsistent spacing between paragraphs. (ex.: Writer index entry "deleting;footnotes"). Misuse of bullets (ex.: Writer index entry "automatic spellcheck": there is no logical connection between the bullet paragraphs. In other cases as Writer index entry "styles;finding", there are single bullets without being in a list). Steps with bullets instead of numbers (ex.: shared index entry "page formats;maximizing"). Missing bullets (ex.: Calc index entry "cells;protecting": the options in steps 3 and 5 should have bullets).
Numbered lists	Text referring to a list item is formatted as hlp_paragraph instead of hlp_listitem. The connection to the list item is not visible. (ex.: Writer index entry "defining;conditions"). Result formatted like a step (ex.: Calc index entry "cells;referencing by drag and drop"). Step without number formatted as hlp_paragraph (ex.: shared index entry "spadmin"). Numbered action alternatives, should be bullets (ex.: shared index entry "start parameters"). Numbered list of steps put into a table (ex.: shared index entry "changes;recording").
Tips, notes and warnings	There is no obvious difference between the use of tips and notes. Often I cannot see any distinction to normal paragraph text either. Missing warning symbol (ex.: Calc index entry "csv files;spreadsheets"). Note in the "Related Topics" section (ex.: shared index entry "docking;windows").
Related topics	Different styles in the "Related topics" link list: help_aux_embed and hlp_paragraph.
Character styles	Misuse of hlp_emph for menu items. Unformattet menu items (ex. View-toolbars-drawing: Calc index entry "accessibility; StarOffice Calc shortcuts"), buttons (ex. OK: Calc index entry "layout;spreadsheets), icon names (ex.: shared index entry "buttons;toolbars") and toolbar names (ex.: link in shared index entry "aging filter"). Shortcut keys are sometimes bold (Calc index entry "accessibility; StarOffice Calc shortcuts") and sometimes not bold (Calc index entry "text completion on/off"). "Navigator" sometimes is bold sometimes not (compare Writer index entry "moving;headings" to shared index entry "Navigator;contents as lists"). Tabs normally are formatted in bold but not always ("Contents" tab: shared index entry "certificates").
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	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".

Style Inconsistencies (see also issue 54559)

string "Syntax"	"Syntax" normally appears as Syntax, but in the mathematical functions you can find also Syntax:
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:
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.
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).
Example syntax	Examples sometimes begin with the equal sign, and sometimes not. Results are sometimes bold, and sometimes not. (ex. Text functions)
Missing example	JIS function lacks an example as well as some analysis functions (part 1).