Documentation/Maemo Documentation Guidelines/General writing conventions

m (removing reduntant linebreaks)
(wikify slightly)
 
(3 intermediate revisions not shown)
Line 1: Line 1:
-
= General writing conventions =
 
-
 
This section describes the general writing conventions for Maemo documentation. The writing conventions are based on ''Nokia Brand Book'' <ref name=r6>Nokia Brand Book. http://brandbook.nokia.com</ref> and ''Nokia A-Z Marketing Language Guide'' <ref name=r5>Nokia A-Z Marketing Language Guide. http://brandbook.nokia.com</ref>.
This section describes the general writing conventions for Maemo documentation. The writing conventions are based on ''Nokia Brand Book'' <ref name=r6>Nokia Brand Book. http://brandbook.nokia.com</ref> and ''Nokia A-Z Marketing Language Guide'' <ref name=r5>Nokia A-Z Marketing Language Guide. http://brandbook.nokia.com</ref>.
-
= Language to be used =
+
== Language to be used ==
Maemo documents are written in UK English.
Maemo documents are written in UK English.
Line 9: Line 7:
If you need to check the spelling of some specific words, use Collins English Dictionary. For more information, use the ''Collins English Dictionary'' <ref name=r2>Collins English Dictionary. http://www.collinslanguage.com</ref>.
If you need to check the spelling of some specific words, use Collins English Dictionary. For more information, use the ''Collins English Dictionary'' <ref name=r2>Collins English Dictionary. http://www.collinslanguage.com</ref>.
-
= Headings =
+
== Headings ==
Maemo documents use the five heading styles and levels described in table 3.1.
Maemo documents use the five heading styles and levels described in table 3.1.
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
-
|+ '''Table 3.1:''' Heading styles and levels
+
|+ Table 3.1: Heading styles and levels
|-
|-
-
! width="300" align="LEFT" valign="TOP" | '''Heading Style'''
+
! Heading Style
-
! width="75" align="LEFT" valign="TOP" | '''Level'''
+
! Level
-
! width="75" align="LEFT" valign="TOP" | '''Numbering'''
+
! Numbering
|-
|-
-
| width="300" align="LEFT" valign="TOP" | <code>\chapter{Chapter title}</code>
+
| <code>\chapter{Chapter title}</code>
-
| width="75" align="LEFT" valign="TOP" | 0
+
| 0
-
| width="75" align="LEFT" valign="TOP" | (a)
+
| (a)
|-
|-
-
| width="300" align="LEFT" valign="TOP" | <code>\section{Section title}</code>
+
| <code>\section{Section title}</code>
-
| width="75" align="LEFT" valign="TOP" | 1
+
| 1
-
| width="75" align="LEFT" valign="TOP" | (a.b)
+
| (a.b)
|-
|-
-
| width="300" align="LEFT" valign="TOP" | <code>\subsection{Subsection title}</code>
+
| <code>\subsection{Subsection title}</code>
-
| width="75" align="LEFT" valign="TOP" | 2
+
| 2
-
| width="75" align="LEFT" valign="TOP" | (a.b.c)
+
| (a.b.c)
|-
|-
-
| width="300" align="LEFT" valign="TOP" | <code>\subsubsection{Subsubsection title}</code>
+
| <code>\subsubsection{Subsubsection title}</code>
-
| width="75" align="LEFT" valign="TOP" | 3
+
| 3
-
| width="75" align="LEFT" valign="TOP" | (a.b.c.d)
+
| (a.b.c.d)
|-
|-
-
| width="300" align="LEFT" valign="TOP" | <code>\textbf{Paragraph title}</code>
+
| <code>\textbf{Paragraph title}</code>
-
| width="75" align="LEFT" valign="TOP" | 4
+
| 4
-
| width="75" align="LEFT" valign="TOP" | (a.b.c.d.e)
+
| (a.b.c.d.e)
|}
|}
Line 47: Line 45:
Level 3 subsubsections (a.b.c.d) are the lowest level included in the table of contents.
Level 3 subsubsections (a.b.c.d) are the lowest level included in the table of contents.
-
If the purpose is NOT to have a section number and NOT to include section to the table of contents, add an asterisk (<span><font face="monospace"><nowiki>*</nowiki></font></span>) to the end of the header tag. For example, <code>\subsection*{Example title}</code> creates a level 2 heading without numbering and without adding it into the table of contents.
+
If the purpose is NOT to have a section number and NOT to include section to the table of contents, add an asterisk (<code>*</code>) to the end of the header tag. For example, <code>\subsection*{Example title}</code> creates a level 2 heading without numbering and without adding it into the table of contents.
It is also possible to create level 4 paragraphs (a.b.c.d.e) but no lower than that. A level 4 paragraph has the following special features by default:
It is also possible to create level 4 paragraphs (a.b.c.d.e) but no lower than that. A level 4 paragraph has the following special features by default:
Line 57: Line 55:
For more information, see chapter [[#Creating cross-references and links]].
For more information, see chapter [[#Creating cross-references and links]].
-
= Lists =
+
== Lists ==
List types can be divided into three categories:
List types can be divided into three categories:
Line 70: Line 68:
Keep lists simple. Do not include code examples or other complex items like tables or figures as a part of a list item. Avoid using nested list.
Keep lists simple. Do not include code examples or other complex items like tables or figures as a part of a list item. Avoid using nested list.
-
= Tables =
+
== Tables ==
Keep tables as simple as possible. Use figures instead of complex tables.
Keep tables as simple as possible. Use figures instead of complex tables.
Line 76: Line 74:
Do not create complex structures, such as table cells including other elements than text. Avoid using multi-column cells for other purposes than creating subheadings for the table. If complex tables are needed create them outside LaTeX as images.
Do not create complex structures, such as table cells including other elements than text. Avoid using multi-column cells for other purposes than creating subheadings for the table. If complex tables are needed create them outside LaTeX as images.
-
Basic instructions for table creation in LaTeX can be found from [http://en.wikibooks.org/wiki/LaTeX/Tables WikiBooks LaTex/Tables].
+
Basic instructions for table creation in LaTeX can be found from [[wikibooks:LaTeX/Tables|WikiBooks LaTex/Tables]].
Each table must have a title that can be referenced.
Each table must have a title that can be referenced.
-
= Figures =
+
== Figures ==
When creating figures, it is recommended to use free graphics tools like [http://www.inkscape.org/ InkScape] or [http://www.gimp.org/ Gimp].
When creating figures, it is recommended to use free graphics tools like [http://www.inkscape.org/ InkScape] or [http://www.gimp.org/ Gimp].
Line 86: Line 84:
Provide figures in a high resolution format. If needed, high resolution figures are scaled down for HTML and PDF usage.
Provide figures in a high resolution format. If needed, high resolution figures are scaled down for HTML and PDF usage.
-
{|
+
{{ambox|text=Screenshots can be low resolution if high resolution figures cannot be created.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  Screenshots can be low resolution if high resolution figures cannot be created.
+
-
|}
+
For books and printing houses, resolution must be high enough. The recommendation is 300 dpi.
For books and printing houses, resolution must be high enough. The recommendation is 300 dpi.
Line 96: Line 90:
Use either PNG or JPEG format. PNG is recommended.
Use either PNG or JPEG format. PNG is recommended.
-
EPS format is not allowed in figures, because it cannot be used in PDF and HTML documents. For more information, see [http://en.wikibooks.org/wiki/LaTeX/Importing_Graphics WikiBooks LaTex/Importing Graphics].
+
EPS format is not allowed in figures, because it cannot be used in PDF and HTML documents. For more information, see [[wikibooks:LaTeX/Importing_Graphics|WikiBooks LaTex/Importing Graphics]].
-
Basic instructions for figure creation in LaTeX can be found from [http://en.wikibooks.org/wiki/LaTeX/Floats,_Figures_and_Captions WikiBooks LaTex/Floats, figures and Captions].
+
Basic instructions for figure creation in LaTeX can be found from [[wikibooks:LaTeX/Floats,_Figures_and_Captions|WikiBooks LaTex/Floats, figures and Captions]].
Each figure, including screen shots, must have a title that can be referenced.
Each figure, including screen shots, must have a title that can be referenced.
-
= Highlighting important text =
+
== Highlighting important text ==
-
Use ''Italics'' to highlight important words in base text, apart from command line examples and function or file names. Do not use '''Bold''', or <span><font face="monospace">TextRaw</font></span> for highlighting.
+
Use ''Italics'' to highlight important words in base text, apart from command line examples and function or file names. Do not use '''Bold''', or <code>TextRaw</code> for highlighting.
Do not use ''Italics'' for the following items:
Do not use ''Italics'' for the following items:
Line 111: Line 105:
* product or component names (capitalize first letters instead of using formatting)
* product or component names (capitalize first letters instead of using formatting)
* paragraph titles (use '''Bold''' instead)
* paragraph titles (use '''Bold''' instead)
-
* example code and file names (use <span><font face="monospace">TextRaw</font></span> instead)
+
* example code and file names (use <code>TextRaw</code> instead)
Use Italics (at least) for the following items:
Use Italics (at least) for the following items:
Line 119: Line 113:
* For more information on highlighting a whole sentence or chapter, see chapters [[#Highlighting example code]] and [[#Creating notes]]
* For more information on highlighting a whole sentence or chapter, see chapters [[#Highlighting example code]] and [[#Creating notes]]
-
= Highlighting example code =
+
== Highlighting example code ==
-
Use <span><font face="monospace">TextRaw</font></span> or <code>Verbatim</code> to highlight command line examples and function or file names in base text. Do NOT use ''Italics'' for these. The difference between these two is that <span><font face="monospace">TextRaw</font></span> allows normal LaTeX commands inside text will be ignored and handled as plain text.
+
Use <code>TextRaw</code> or <code>Verbatim</code> to highlight command line examples and function or file names in base text. Do NOT use ''Italics'' for these. The difference between these two is that <code>TextRaw</code> allows normal LaTeX commands inside text will be ignored and handled as plain text.
-
Use <span><font face="monospace">TextRaw</font></span> or <code>Verbatim</code> to highlight the following items:
+
Use <code>TextRaw</code> or <code>Verbatim</code> to highlight the following items:
* paths and file names
* paths and file names
Line 132: Line 126:
* domain names and IP addresses
* domain names and IP addresses
-
Use <span><font face="monospace">TextRaw</font></span> for source code examples. Names need to be written exactly as in source code, for example, <span><font face="monospace">ThumbButton</font></span>, <span><font face="monospace">SmallFont</font></span>, <span><font face="monospace">PANGO_SCALE_SMALL</font></span>, and <span><font face="monospace">ButtonTextColor</font></span>.
+
Use <code>TextRaw</code> for source code examples. Names need to be written exactly as in source code, for example, <code>ThumbButton</code>, <code>SmallFont</code>, <code>PANGO_SCALE_SMALL</code>, and <code>ButtonTextColor</code>.
-
Use <span><font face="monospace">TextRaw</font></span> for command line examples and file names, for example, <span><font face="monospace">sources.list</font></span>, <span><font face="monospace">/opt/bin/share</font></span>, and <span><font face="monospace">apt-get install maemo-python-env</font></span>.
+
Use <code>TextRaw</code> for command line examples and file names, for example, <code>sources.list</code>, <code>/opt/bin/share</code>, and <code>apt-get install maemo-python-env</code>.
Use references to the source code names in the following way:
Use references to the source code names in the following way:
-
* For user to be able to cancel operation without saving modified data you need to add <span><font face="monospace">ThumbButton</font></span> for your dialog.
+
* For user to be able to cancel operation without saving modified data you need to add <code>ThumbButton</code> for your dialog.
For more information, see chapters [[#Highlighting important text]], [[#Code listings]], and [[#Command line and screen output examples]].
For more information, see chapters [[#Highlighting important text]], [[#Code listings]], and [[#Command line and screen output examples]].
-
= Highlighting UI element names =
+
== Highlighting UI element names ==
-
Use '''Bold''' font to highlight user interface component caption names in text. For example, if you need to refer to a UI button with the caption '''Cancel''' use the caption '''Cancel''' as the element name and use '''Bold''' to highlight the name. Do NOT use ''Italics'', <span><font face="monospace">TextRaw</font></span> or <code>Verbatim</code> for highlighting UI element names.
+
Use '''Bold''' font to highlight user interface component caption names in text. For example, if you need to refer to a UI button with the caption '''Cancel''' use the caption '''Cancel''' as the element name and use '''Bold''' to highlight the name. Do NOT use ''Italics'', <code>TextRaw</code> or <code>Verbatim</code> for highlighting UI element names.
-
Use <span><font face="monospace">TextRaw</font></span> or <code>Verbatim</code> only for referring to source code name of the UI element.
+
Use <code>TextRaw</code> or <code>Verbatim</code> only for referring to source code name of the UI element.
Use references to the UI element names in the following way:
Use references to the UI element names in the following way:
Line 154: Line 148:
For more information, see chapters [[#Highlighting important text]], [[#Code listings]], and [[#Command line and screen output examples]].
For more information, see chapters [[#Highlighting important text]], [[#Code listings]], and [[#Command line and screen output examples]].
-
= Creating notes =
+
== Creating notes ==
-
Notes are used in documentation to make the reader pay attention to important issues that have to be taken into consideration. Do not add a note as a part of the body text. Instead, create each note on a separate row using NoteBox:
+
Notes are used in documentation to make the reader pay attention to important issues that have to be taken into consideration. Do not add a note as a part of the body text. Instead, create each note on a separate row using <code>NoteBox</code>:
-
{|
+
{{ambox|text=This is an example of a note.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  This is an example of a note.
+
-
|}
+
-
Before using a NoteBox consider whether using ''Italics'' is enough to highlight the issue in the base text. Use NoteBox only for very important issues and avoid ending a section with it.
+
Before using a <code>NoteBox</code> consider whether using ''Italics'' is enough to highlight the issue in the base text. Use <code>NoteBox</code> only for very important issues and avoid ending a section with it.
-
= Creating cross-references and links =
+
== Creating cross-references and links ==
All Maemo documents must use the same LaTeX bibliography database. References added to the document from the bibliography database are added to the bibliography list automatically.
All Maemo documents must use the same LaTeX bibliography database. References added to the document from the bibliography database are added to the bibliography list automatically.
Line 203: Line 193:
Use Maemo bibliography database for references to other documents.
Use Maemo bibliography database for references to other documents.
-
= Trademarks =
+
== Trademarks ==
To check the correct spelling of common Nokia trademarks and product names, see chapter [[#Product names]].
To check the correct spelling of common Nokia trademarks and product names, see chapter [[#Product names]].
-
= Acronyms =
+
== Acronyms ==
To check the correct spelling of common Nokia trademarks and product names, see chapter [[#Product names]].
To check the correct spelling of common Nokia trademarks and product names, see chapter [[#Product names]].
-
= Clear and concise language =
+
== Clear and concise language ==
Use clear and concise language. Use the imperative in instructions, and avoid using the passive voice or empty expressions, if possible. See examples about how to use clear language expressions in table 3.2.
Use clear and concise language. Use the imperative in instructions, and avoid using the passive voice or empty expressions, if possible. See examples about how to use clear language expressions in table 3.2.
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
-
|+ '''Table 3.2:''' Examples for clear language
+
|+ Table 3.2: Examples for clear language
|-
|-
-
! width="100" align="LEFT" valign="TOP" | '''Problem'''
+
! Problem
-
! width="100" align="LEFT" valign="TOP" | '''Incorrect'''
+
! Incorrect
-
! width="250" align="LEFT" valign="TOP" | '''Correct'''
+
! Correct
|-
|-
-
| width="100" align="LEFT" valign="TOP" | There is/are as an empty expression.
+
| There is/are as an empty expression.
-
| width="100" align="LEFT" valign="TOP" | There is a possibility to do X.
+
| There is a possibility to do X.
-
| width="250" align="LEFT" valign="TOP" | You can do X.
+
| You can do X.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | It is as an empty expression.
+
| It is as an empty expression.
-
| width="100" align="LEFT" valign="TOP" | It is possible to install X.
+
| It is possible to install X.
-
| width="250" align="LEFT" valign="TOP" | You can install X.
+
| You can install X.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Have/has as passive voice or an empty verb.
+
| Have/has as passive voice or an empty verb.
-
| width="100" align="LEFT" valign="TOP" | X has the option of including Y.
+
| X has the option of including Y.
-
| width="250" align="LEFT" valign="TOP" | X can include Y.
+
| X can include Y.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Be/are/been as passive voice.
+
| Be/are/been as passive voice.
-
| width="100" align="LEFT" valign="TOP" | This is done by installing X.
+
| This is done by installing X.
-
| width="250" align="LEFT" valign="TOP" | For this, install X.
+
| For this, install X.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Using the future tense.
+
| Using the future tense.
-
| width="100" align="LEFT" valign="TOP" | A window will open.
+
| A window will open.
-
| width="250" align="LEFT" valign="TOP" | A window opens. Instead of the future tense (will), use the present tense.
+
| A window opens. Instead of the future tense (will), use the present tense.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Providing options to the reader.
+
| Providing options to the reader.
-
| width="100" align="LEFT" valign="TOP" | You can do this or that.
+
| You can do this or that.
-
| width="250" align="LEFT" valign="TOP" | Do this. To be as clear as possible and to avoid any ambiguity, do not give the user several options about what they can do. Be as direct as possible.
+
| Do this. To be as clear as possible and to avoid any ambiguity, do not give the user several options about what they can do. Be as direct as possible.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Redundant politeness.
+
| Redundant politeness.
-
| width="100" align="LEFT" valign="TOP" | Please.
+
| Please.
-
| width="250" align="LEFT" valign="TOP" | Please is an empty expression that can usually be omitted.
+
| Please is an empty expression that can usually be omitted.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Gender-specific language.
+
| Gender-specific language.
-
| width="100" align="LEFT" valign="TOP" | He/she.
+
| He/she.
-
| width="250" align="LEFT" valign="TOP" | Instead of the gender-specific terms he or she, use the more neutral they.
+
| Instead of the gender-specific terms he or she, use the more neutral they.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Conditional.
+
| Conditional.
-
| width="100" align="LEFT" valign="TOP" | Would.
+
| Would.
-
| width="250" align="LEFT" valign="TOP" | Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
+
| Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | Conditional.
+
| Conditional.
-
| width="100" align="LEFT" valign="TOP" | May/might.
+
| May/might.
-
| width="250" align="LEFT" valign="TOP" | Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
+
| Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
|}
|}
-
= Conjunctions =
+
== Conjunctions ==
Use properly the conjunctions given in table 3.3.
Use properly the conjunctions given in table 3.3.
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
-
|+ '''Table 3.3:''' Proper usage of conjunctions
+
|+ Table 3.3: Proper usage of conjunctions
|-
|-
-
! width="100" align="LEFT" valign="TOP" | '''Incorrect'''
+
! Incorrect
-
! width="350" align="LEFT" valign="TOP" | '''Correct'''
+
! Correct
|-
|-
-
| width="100" align="LEFT" valign="TOP" | since
+
| since
-
| width="350" align="LEFT" valign="TOP" | because
+
| because
|-
|-
-
| width="100" align="LEFT" valign="TOP" | as
+
| as
-
| width="350" align="LEFT" valign="TOP" | because (except when used as synonymous to like)
+
| because (except when used as synonymous to like)
|-
|-
-
| width="100" align="LEFT" valign="TOP" | when
+
| when
-
| width="350" align="LEFT" valign="TOP" | because (not instead of if)
+
| because (not instead of if)
|}
|}
-
= Shortkeys =
+
== Shortkeys ==
-
Use <span><font face="monospace">CTRL+C</font></span> to refer to pressing the control and c keys together. Use the same <span><font face="monospace">TextRaw</font></span> text formatting for all Shortkeys in base text as for command line examples inside text.
+
Use <span><font face="monospace">CTRL+C</font></span> to refer to pressing the control and c keys together. Use the same <code>TextRaw</code> text formatting for all Shortkeys in base text as for command line examples inside text.
-
= Abbreviations =
+
== Abbreviations ==
To avoid sounding too casual, do not use apostrophes to mark possession or to form plural nouns. For more details, see table 3.4.
To avoid sounding too casual, do not use apostrophes to mark possession or to form plural nouns. For more details, see table 3.4.
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
-
|+ '''Table 3.4:''' Proper usage of abbvreviations
+
|+ Table 3.4: Proper usage of abbvreviations
|-
|-
-
! width="100" align="LEFT" valign="TOP" | '''Incorrect'''
+
! Incorrect
-
! width="350" align="LEFT" valign="TOP" | '''Correct'''
+
! Correct
|-
|-
-
| width="100" align="LEFT" valign="TOP" | <nowiki>*'ll</nowiki>
+
| <nowiki>*'ll</nowiki>
-
| width="350" align="LEFT" valign="TOP" | instead of the future tense, use the present tense.
+
| instead of the future tense, use the present tense.
|-
|-
-
| width="100" align="LEFT" valign="TOP" | <nowiki>*'re</nowiki>
+
| <nowiki>*'re</nowiki>
-
| width="350" align="LEFT" valign="TOP" | write a two separate words, for example there are
+
| write a two separate words, for example there are
|-
|-
-
| width="100" align="LEFT" valign="TOP" | <nowiki>*'s</nowiki>
+
| <nowiki>*'s</nowiki>
-
| width="350" align="LEFT" valign="TOP" | instead of device's platform, write device platform or use the preposition of to form the possessive: the platform of the device
+
| instead of device's platform, write device platform or use the preposition of to form the possessive: the platform of the device
|}
|}
-
= Code listings =
+
== Code listings ==
Separate source code example listings that are not part of the base text must fulfill the following requirements:
Separate source code example listings that are not part of the base text must fulfill the following requirements:
Line 319: Line 309:
* If the example code used is longer than 50 lines it is recommended (but not required) to include also copyright and licensing information in the beginning of the example code.
* If the example code used is longer than 50 lines it is recommended (but not required) to include also copyright and licensing information in the beginning of the example code.
-
{|
+
{{ambox|text=Each code example in a Garage project copyrighted by Nokia must use MIT-style licence to allow the free use of the example code.}}
-
|-
+
-
| [[Image:dialog-information.png]]
+
-
| '''Note:'''  Each code example in a Garage project copyrighted by Nokia must use MIT-style licence to allow the free use of the example code.
+
-
|}
+
Source code example types supported for listings are C/C++, CSS, HTML, Java, JavaScript, Latex, Pascal, Perl, PHP, Postscript, Python, Ruby, SQL, Tcl, Properties files, Makefile, XML, Log files, Ini files, Shell scripts and more.
Source code example types supported for listings are C/C++, CSS, HTML, Java, JavaScript, Latex, Pascal, Perl, PHP, Postscript, Python, Ruby, SQL, Tcl, Properties files, Makefile, XML, Log files, Ini files, Shell scripts and more.
Line 331: Line 317:
Example code below describes how to create...
Example code below describes how to create...
-
<code><nowiki>
+
<source lang="c">
-
/*
+
/*
-
* example_source.c, an example source code for kernel module
+
* example_source.c, an example source code for kernel module
-
*
+
*
-
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
+
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
-
*
+
*
-
* This maemo code example is licensed under a MIT-style license,
+
* This maemo code example is licensed under a MIT-style license,
-
* that can be found in the file called "COPYING".
+
* that can be found in the file called "COPYING".
-
*
+
*
-
*/
+
*/
-
#include &lt;linux/module.h&gt; /* needed by all kernel modules */
+
#include <linux/module.h> /* needed by all kernel modules */
-
#include &lt;linux/init.h&gt;   /* needed for custom init/exit functions */
+
#include <linux/init.h>   /* needed for custom init/exit functions */
-
#include &lt;linux/kernel.h&gt; /* needed for KERN_ALERT macro */
+
#include <linux/kernel.h> /* needed for KERN_ALERT macro */
-
/* Special macro to indicate license (to avoid tainting the kernel) */
+
/* Special macro to indicate license (to avoid tainting the kernel) */
-
MODULE_LICENSE("Dual MIT/GPL");
+
MODULE_LICENSE("Dual MIT/GPL");
-
static int hello_init(void) {
+
static int hello_init(void) {
-
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
+
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
-
return 0;
+
return 0;
-
}
+
}
-
static void hello_exit(void)
+
static void hello_exit(void)
-
{
+
{
-
printk(KERN_INFO "Goodbye, world\n");
+
printk(KERN_INFO "Goodbye, world\n");
-
}
+
}
-
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
+
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
-
module_init(hello_init);
+
module_init(hello_init);
-
module_exit(hello_exit);
+
module_exit(hello_exit);
-
</nowiki></code>
+
</source>
Example given above is the simplest way to implement...
Example given above is the simplest way to implement...
Line 368: Line 354:
Avoid ending a section with a listing box.
Avoid ending a section with a listing box.
-
= Command line and screen output examples =
+
== Command line and screen output examples ==
Separate command line and screen output examples that are not part of base text and are not source code examples must fulfill the following requirements:
Separate command line and screen output examples that are not part of base text and are not source code examples must fulfill the following requirements:
-
* Example needs to be inside a GrayBox that separates it from the base text.
+
* Example needs to be inside a <code>GrayBox</code> that separates it from the base text.
* Example box does NOT have a title and CANNOT be referenced.
* Example box does NOT have a title and CANNOT be referenced.
* Example does NOT get automatic source highlighting.
* Example does NOT get automatic source highlighting.
* Example box should be connectied to the surrounding base text.
* Example box should be connectied to the surrounding base text.
-
The following is an example of how a command line example within a GrayBox can be connected to the surrounding text (notice that an empty line must be given before GrayBox).
+
The following is an example of how a command line example within a <code>GrayBox</code> can be connected to the surrounding text (notice that an empty line must be given before <code>GrayBox</code>).
Following commands show how to...
Following commands show how to...
Line 386: Line 372:
Commands given above can be used also in...
Commands given above can be used also in...
-
Avoid ending a section with a GrayBox.
+
Avoid ending a section with a <code>GrayBox</code>.
-
= Product names =
+
== Product names ==
The following is an initial list of Maemo product names in alphabetic order:
The following is an initial list of Maemo product names in alphabetic order:
Line 395: Line 381:
* Chinook
* Chinook
* Debian
* Debian
-
* Diablo
+
* [[Open development/Maemo roadmap/Diablo|Diablo]]
-
* Fremantle
+
* [[Open development/Maemo roadmap/Fremantle|Fremantle]]
* Gregale
* Gregale
-
* Harmattan
+
* [[Open development/Maemo roadmap/Harmattan|Harmattan]]
* Maemo
* Maemo
* maemo.org
* maemo.org
Line 414: Line 400:
* MaemoPad
* MaemoPad
* Mistral
* Mistral
-
* N800
+
* [[Nokia N800|N800]]
-
* N810
+
* [[Nokia N810|N810]]
-
* N810 WiMAX Edition
+
* [[Nokia N810WME|N810 WiMAX Edition]]
-
* N900
+
* [[Nokia N900|N900]]
-
* Nokia 770
+
* [[Nokia 770]]
* Scirocco
* Scirocco
* Scratchbox
* Scratchbox
Line 424: Line 410:
The following table 3.5 presents the correct way to spell some product names:
The following table 3.5 presents the correct way to spell some product names:
-
{| border="1" cellpadding="3"
+
{| class="wikitable"
|+ '''Table 3.5:''' Proper usage of product names
|+ '''Table 3.5:''' Proper usage of product names
|-
|-
-
! width="200" align="LEFT" valign="TOP" | '''Incorrect'''
+
! Incorrect
-
! width="250" align="LEFT" valign="TOP" | '''Correct'''
+
! Correct
|-
|-
-
| width="200" align="LEFT" valign="TOP" | Maemo SDK(+)
+
| Maemo SDK(+)
-
| width="250" align="LEFT" valign="TOP" | Maemo SDK
+
| Maemo SDK
|-
|-
-
| width="200" align="LEFT" valign="TOP" | the Maemo SDK
+
| the Maemo SDK
-
| width="250" align="LEFT" valign="TOP" | Maemo SDK
+
| Maemo SDK
|-
|-
-
| width="200" align="LEFT" valign="TOP" | sbox
+
| sbox
-
| width="250" align="LEFT" valign="TOP" | Scratchbox
+
| Scratchbox
|-
|-
-
| width="200" align="LEFT" valign="TOP" | Maemo Virtual Image
+
| Maemo Virtual Image
-
| width="250" align="LEFT" valign="TOP" | Maemo SDK Virtual Image
+
| Maemo SDK Virtual Image
|-
|-
-
| width="200" align="LEFT" valign="TOP" | N810 Wimax
+
| N810 Wimax
-
| width="250" align="LEFT" valign="TOP" | N810 WiMAX Edition
+
| N810 WiMAX Edition
|}
|}
== References ==
== References ==
 +
<references />
<references />
 +
 +
[[Category:Documentation]]

Latest revision as of 12:56, 10 November 2010

This section describes the general writing conventions for Maemo documentation. The writing conventions are based on Nokia Brand Book [1] and Nokia A-Z Marketing Language Guide [2].

Contents

[edit] Language to be used

Maemo documents are written in UK English.

If you need to check the spelling of some specific words, use Collins English Dictionary. For more information, use the Collins English Dictionary [3].

[edit] Headings

Maemo documents use the five heading styles and levels described in table 3.1.

Table 3.1: Heading styles and levels
Heading Style Level Numbering
\chapter{Chapter title} 0 (a)
\section{Section title} 1 (a.b)
\subsection{Subsection title} 2 (a.b.c)
\subsubsection{Subsubsection title} 3 (a.b.c.d)
\textbf{Paragraph title} 4 (a.b.c.d.e)

Each level 0 chapter (a) must start from a separate page.

Each level 1 section (a.b) must have a generic "a.1 Introduction" section (as the first section). In the introductive section, add links to example applications used and API docs referred to in the section.

Level 3 subsubsections (a.b.c.d) are the lowest level included in the table of contents.

If the purpose is NOT to have a section number and NOT to include section to the table of contents, add an asterisk (*) to the end of the header tag. For example, \subsection*{Example title} creates a level 2 heading without numbering and without adding it into the table of contents.

It is also possible to create level 4 paragraphs (a.b.c.d.e) but no lower than that. A level 4 paragraph has the following special features by default:

  • it is not included in the table of contents
  • it does not use section numbering
  • it cannot be referenced from the base text

For more information, see chapter #Creating cross-references and links.

[edit] Lists

List types can be divided into three categories:

Unordered lists
are also known as bullet lists. Use unordered lists when the specific order of the list items is not relevant.
Ordered lists
are also known as numbered lists. Use ordered lists when the order of the list items is relevant.
Step lists
are a subcategory of ordered lists, but used specifically for providing instructions on how to complete a procedure. Introduce each step list with an introductory sentence, using the syntax: To <do> <something>.

Keep lists simple. Do not include code examples or other complex items like tables or figures as a part of a list item. Avoid using nested list.

[edit] Tables

Keep tables as simple as possible. Use figures instead of complex tables.

Do not create complex structures, such as table cells including other elements than text. Avoid using multi-column cells for other purposes than creating subheadings for the table. If complex tables are needed create them outside LaTeX as images.

Basic instructions for table creation in LaTeX can be found from WikiBooks LaTex/Tables.

Each table must have a title that can be referenced.

[edit] Figures

When creating figures, it is recommended to use free graphics tools like InkScape or Gimp.

Provide figures in a high resolution format. If needed, high resolution figures are scaled down for HTML and PDF usage.

Image:Ambox_notice.png
Screenshots can be low resolution if high resolution figures cannot be created.

For books and printing houses, resolution must be high enough. The recommendation is 300 dpi.

Use either PNG or JPEG format. PNG is recommended.

EPS format is not allowed in figures, because it cannot be used in PDF and HTML documents. For more information, see WikiBooks LaTex/Importing Graphics.

Basic instructions for figure creation in LaTeX can be found from WikiBooks LaTex/Floats, figures and Captions.

Each figure, including screen shots, must have a title that can be referenced.

[edit] Highlighting important text

Use Italics to highlight important words in base text, apart from command line examples and function or file names. Do not use Bold, or TextRaw for highlighting.

Do not use Italics for the following items:

  • sentences or chapters
  • product or component names (capitalize first letters instead of using formatting)
  • paragraph titles (use Bold instead)
  • example code and file names (use TextRaw instead)

Use Italics (at least) for the following items:

  • important words that need special attention from the reader
  • document names (with reference to Maemo Bibliography database)
  • For more information on highlighting a whole sentence or chapter, see chapters #Highlighting example code and #Creating notes

[edit] Highlighting example code

Use TextRaw or Verbatim to highlight command line examples and function or file names in base text. Do NOT use Italics for these. The difference between these two is that TextRaw allows normal LaTeX commands inside text will be ignored and handled as plain text.

Use TextRaw or Verbatim to highlight the following items:

  • paths and file names
  • source code examples
  • command line examples
  • screen output examples
  • environment variables
  • domain names and IP addresses

Use TextRaw for source code examples. Names need to be written exactly as in source code, for example, ThumbButton, SmallFont, PANGO_SCALE_SMALL, and ButtonTextColor.

Use TextRaw for command line examples and file names, for example, sources.list, /opt/bin/share, and apt-get install maemo-python-env.

Use references to the source code names in the following way:

  • For user to be able to cancel operation without saving modified data you need to add ThumbButton for your dialog.

For more information, see chapters #Highlighting important text, #Code listings, and #Command line and screen output examples.

[edit] Highlighting UI element names

Use Bold font to highlight user interface component caption names in text. For example, if you need to refer to a UI button with the caption Cancel use the caption Cancel as the element name and use Bold to highlight the name. Do NOT use Italics, TextRaw or Verbatim for highlighting UI element names.

Use TextRaw or Verbatim only for referring to source code name of the UI element.

Use references to the UI element names in the following way:

  • To cancel operation without saving modified data, press button Cancel in dialog.

For more information, see chapters #Highlighting important text, #Code listings, and #Command line and screen output examples.

[edit] Creating notes

Notes are used in documentation to make the reader pay attention to important issues that have to be taken into consideration. Do not add a note as a part of the body text. Instead, create each note on a separate row using NoteBox:

Image:Ambox_notice.png
This is an example of a note.

Before using a NoteBox consider whether using Italics is enough to highlight the issue in the base text. Use NoteBox only for very important issues and avoid ending a section with it.

[edit] Creating cross-references and links

All Maemo documents must use the same LaTeX bibliography database. References added to the document from the bibliography database are added to the bibliography list automatically.

Use Maemo bibliography database references in the following way:

  • For more information on Nokia Brand, see document Nokia Brand Book [1].

To allow level 1 sections (a.b) to be reused in several different documents:

  • Do not link between level 1 sections (a.b) within a document. For example, do not make links from level 1 section (x.y) to subsections, tables, or figures located in another level 1 section (x.z).
  • Linking within level 1 section (x.y) is allowed.

Each level 1 section (a.b) must have a generic, introductive section (a.1 Introduction). The introductive section should contain:

  • A short introduction text about the purpose of the section.
  • Links to all example applications used in the section. The only allowed example links are to the Maemo examples project in Garage.
  • Links to all API docs referenced in the section. Links out of maemo.org are allowed for API docs.

If section Y referenced from the text is in the same level 1 section (a.b) as the text itself, create a section number link to section Y.

Use cross-references with section number link between sections in the following way:

  • For more information on topic X, see chapter #Creating cross-references and links.
  • For more information on topic X, see figure [/node3.html#fig:documentation_guidelines-introduction-n900 1.1].
  • For more information on topic X, see table 3.2.

If section Y referenced from the text is not in the same level 1 section (a.b) as the text itself, create a textual reference instead by using the chapter name in quotes. Do not use chapter numbers in textual references.

Use textual references between two level 1 sections (a.b) in the following way:

  • For more information on references, see chapter "How to write text references".
  • For more information on references, see figure "How to write text references".
  • For more information on references, see table "How to write text references".

Use Maemo bibliography database for references to other documents.

[edit] Trademarks

To check the correct spelling of common Nokia trademarks and product names, see chapter #Product names.

[edit] Acronyms

To check the correct spelling of common Nokia trademarks and product names, see chapter #Product names.

[edit] Clear and concise language

Use clear and concise language. Use the imperative in instructions, and avoid using the passive voice or empty expressions, if possible. See examples about how to use clear language expressions in table 3.2.

Table 3.2: Examples for clear language
Problem Incorrect Correct
There is/are as an empty expression. There is a possibility to do X. You can do X.
It is as an empty expression. It is possible to install X. You can install X.
Have/has as passive voice or an empty verb. X has the option of including Y. X can include Y.
Be/are/been as passive voice. This is done by installing X. For this, install X.
Using the future tense. A window will open. A window opens. Instead of the future tense (will), use the present tense.
Providing options to the reader. You can do this or that. Do this. To be as clear as possible and to avoid any ambiguity, do not give the user several options about what they can do. Be as direct as possible.
Redundant politeness. Please. Please is an empty expression that can usually be omitted.
Gender-specific language. He/she. Instead of the gender-specific terms he or she, use the more neutral they.
Conditional. Would. Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
Conditional. May/might. Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.

[edit] Conjunctions

Use properly the conjunctions given in table 3.3.

Table 3.3: Proper usage of conjunctions
Incorrect Correct
since because
as because (except when used as synonymous to like)
when because (not instead of if)

[edit] Shortkeys

Use CTRL+C to refer to pressing the control and c keys together. Use the same TextRaw text formatting for all Shortkeys in base text as for command line examples inside text.

[edit] Abbreviations

To avoid sounding too casual, do not use apostrophes to mark possession or to form plural nouns. For more details, see table 3.4.

Table 3.4: Proper usage of abbvreviations
Incorrect Correct
*'ll instead of the future tense, use the present tense.
*'re write a two separate words, for example there are
*'s instead of device's platform, write device platform or use the preposition of to form the possessive: the platform of the device

[edit] Code listings

Separate source code example listings that are not part of the base text must fulfill the following requirements:

  • Code example needs to be inside a listing box that separates it from the base text.
  • Listing box should be connected to the surrounding base text with a reference.
  • Listing box must not have Caption or Label, e.g. listings cannot be refered from text.
  • Each piece of source code used in the example must be taken from an official example application in a Garage project. The validity of all such code examples must be tested.
  • All source code examples must use source code highlighting for better readability.
  • All source code examples must include comments explaining the functionality.
  • If the example code used is longer than 50 lines it is recommended (but not required) to include also copyright and licensing information in the beginning of the example code.
Image:Ambox_notice.png
Each code example in a Garage project copyrighted by Nokia must use MIT-style licence to allow the free use of the example code.

Source code example types supported for listings are C/C++, CSS, HTML, Java, JavaScript, Latex, Pascal, Perl, PHP, Postscript, Python, Ruby, SQL, Tcl, Properties files, Makefile, XML, Log files, Ini files, Shell scripts and more.

The following is an example of how code listings can be connected to the surrounding text:

Example code below describes how to create...

/*
* example_source.c, an example source code for kernel module
*
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
*
* This maemo code example is licensed under a MIT-style license,
* that can be found in the file called "COPYING".
*
*/
 
#include <linux/module.h> /* needed by all kernel modules */
#include <linux/init.h>   /* needed for custom init/exit functions */
#include <linux/kernel.h> /* needed for KERN_ALERT macro */
 
/* Special macro to indicate license (to avoid tainting the kernel) */
MODULE_LICENSE("Dual MIT/GPL");
 
static int hello_init(void) {
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
return 0;
}
 
static void hello_exit(void)
{
printk(KERN_INFO "Goodbye, world\n");
}
 
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
module_init(hello_init);
module_exit(hello_exit);

Example given above is the simplest way to implement...

Avoid ending a section with a listing box.

[edit] Command line and screen output examples

Separate command line and screen output examples that are not part of base text and are not source code examples must fulfill the following requirements:

  • Example needs to be inside a GrayBox that separates it from the base text.
  • Example box does NOT have a title and CANNOT be referenced.
  • Example does NOT get automatic source highlighting.
  • Example box should be connectied to the surrounding base text.

The following is an example of how a command line example within a GrayBox can be connected to the surrounding text (notice that an empty line must be given before GrayBox).

Following commands show how to...

$ COMMAND LINE EXAMPLE IS HERE
$ ANOTHER COMMAND LINE IS HERE

Commands given above can be used also in...

Avoid ending a section with a GrayBox.

[edit] Product names

The following is an initial list of Maemo product names in alphabetic order:

  • Bora
  • Chinook
  • Debian
  • Diablo
  • Fremantle
  • Gregale
  • Harmattan
  • Maemo
  • maemo.org
  • Maemo C++
  • Maemo ESbox
  • Maemo Flasher-3.5
  • Maemo Host PC Connectivity
  • Maemo Mica Framework
  • Maemo PC Connectivity
  • Maemo PluThon
  • Maemo Python
  • Maemo Qt4
  • Maemo SDK
  • Maemo SDK Virtual Image
  • MaemoPad
  • Mistral
  • N800
  • N810
  • N810 WiMAX Edition
  • N900
  • Nokia 770
  • Scirocco
  • Scratchbox

The following table 3.5 presents the correct way to spell some product names:

Table 3.5: Proper usage of product names
Incorrect Correct
Maemo SDK(+) Maemo SDK
the Maemo SDK Maemo SDK
sbox Scratchbox
Maemo Virtual Image Maemo SDK Virtual Image
N810 Wimax N810 WiMAX Edition

[edit] References

  1. 1.0 1.1 Nokia Brand Book. http://brandbook.nokia.com
  2. Nokia A-Z Marketing Language Guide. http://brandbook.nokia.com
  3. Collins English Dictionary. http://www.collinslanguage.com