Typographical Guidelines/zh-cn: Difference between revisions

From KDE UserBase Wiki
(Updating to match new version of source page)
(Updating to match new version of source page)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages />
<languages />


''There are separate pages explaining [[Special:myLanguage/PageLayout|Page Layout]] and [[Special:myLanguage/Toolbox|syntax]] with example code.''
<div class="mw-translate-fuzzy">
''这些页面解释了[[Special:myLanguage/PageLayout|页面布局]][[Special:myLanguage/Toolbox|语法]],并且带有示例代码。''
</div>


{{Remember|3=Important|1=Adhering to these typographic guidelines will ensure that your documentation can be accurately and easily exported for translation purposes. Some guidelines may not be applicable for non-English languages. These should be noted on specific language pages, linked from [[Translation_Workflow|Translation Workflow]].  If no such page exists for your language, please add one and make guidelines there.}}
{{Remember|2=重要|1=遵循这些排版指南可以让您的文档准确方便地导出以供翻译。有些指南或许不适用于英语之外的语言。这些情况应该在特定语言的页面上注明,并在 [[Special:myLanguage/Translation_Workflow|翻译流程]]中做好链接。如果您的语言没有这种页面,那么请添加一个并在此处指明。}}


== Links ==
Links to other UserBase pages should follow this pattern:
{{Input|1=<nowiki>[[Special:MyLanguage/page name|whatever]]</nowiki>}}
<nowiki>[[Special:MyLanguage/Welcome to KDE UserBase|start page]]</nowiki> links to the welcome  page in the readers language if the translation exists or else to the english version of that page.
Links to external pages follow normal wiki syntax:
{{Input|1=<nowiki>[https://web.site.xxx/page text]</nowiki>}}
<span id="Bold_Text"></span>
==粗体字==
==粗体字==


用粗体字来突出
用粗体字来突出
* 窗口标题
* 窗口标题
* Common labels that are not user-configurable
* 不能被用户自定义的一般化文本
* 图标标题
* 图标标题
* 程序名字
* 程序名字
Line 17: Line 32:
* 突出会复制到 '''Klipper''' 的所选文字。
* 突出会复制到 '''Klipper''' 的所选文字。


<span id="Italic_Text"></span>
==斜体字==
==斜体字==


Use italic text to emphasise
斜体文本起强调作用
* Words or phrases as in general writing.
* 通常情况下想要强调的词语。
* Titles when referencing other works.
* 引用的其他资源的标题。
* The first use of an unfamiliar word.
* 首次使用一个生僻词时。


Some examples:
例子:
* ''Save your work at this point.''
* ''请在此时保存你的工作。''
* Details can be found in ''Samba 3 by Example''....
* 相关细节可以在''Samba 3 by Example''找到....
* KDE Manuals are in ''Docbook'' format.
* KDE手册用''Docbook''格式编写。


{{Tip|1=''Programs'' are launched by users, ''components'' are used by programs}}
{{Tip|1=''程序'' 被用户启动,''组件'' 被程序使用}}


<span id="Combined_Bold_and_Italic_Text"></span>
==粗体斜体并用==
==粗体斜体并用==


Use this combination for replaceable or variable text.
对于可替换的或者说可变的文本,请使用这种组合格式。


Some examples:
例子:
* To connect to your remote server, type <code>ssh</code> '''''[email protected]''''' in '''Konsole'''.
* 要连接到你的远程服务器的话,在 '''''Konsole''''' 中键入 <code>ssh</code> '''''[email protected]'''''
* In rpm-based distributions, the command <code>rpm -q</code> '''''packagename''''' will result in '''''package-version-release'''''.
* 在基于rpm的发布包中,命令 <code>rpm -q</code> '''''packagename''''' 将输出 '''''package-version-release'''''


<span id="Mono-spaced_Text"></span>
==等宽文字==
==等宽文字==


Code should be presented in mono-spaced text, usually boxed, as shown below.  Input text will be on a pale yellow background.  For output text, the background colour will be violet-grey.  
<div class="mw-translate-fuzzy">
代码应该通过等宽文本显示,通常显示在框中,如下所示。输入文本将在淡黄色背景上。对于输出文本,背景颜色将为紫灰色。
</div>  


* Code, whether single lines or blocks, use templates to ensure consistency
* 对于代码,无论是否是单行的,都应使用该模板以确保其平滑度


* Use the  Input template like this: {{Input|1=<nowiki>{{Input|1=<nowiki>
* 请使用像这样的Input模板: {{Input|1=<nowiki>{{Input|1=<nowiki>
qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
rm -r ~/.kde/share/apps/nepomuk
rm -r ~/.kde/share/apps/nepomuk
rm -r ~/.kde4/share/apps/nepomuk
rm -r ~/.kde4/share/apps/nepomuk
nepomukserver&lt;/nowiki>}}</nowiki>}} This will display like this: {{Input|1=<nowiki>
nepomukserver&lt;/nowiki>}}</nowiki>}} 这将会像这样显示: {{Input|1=<nowiki>
qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
rm -r ~/.kde/share/apps/nepomuk
rm -r ~/.kde/share/apps/nepomuk
Line 56: Line 76:




* Output works the same way: {{Output|1=<nowiki>{{Output|1=<nowiki>terminal output  
* Output文本也一样: {{Output|1=<nowiki>{{Output|1=<nowiki>terminal output  
is also shown as code,  
is also shown as code,  
but on a grey background&lt;/nowiki>}}</nowiki>}} which displays as {{Output|1=<nowiki>terminal output  
but on a grey background&lt;/nowiki>}}</nowiki>}} 被显示为 {{Output|1=<nowiki>terminal output  
is also shown as code,  
is also shown as code,  
but on a grey background</nowiki>}}
but on a grey background</nowiki>}}


{{Note|1=Note the use of <code><nowiki>1=<nowiki> some text &lt;/nowiki></nowiki></code> to avoid situations that break the display format}}
{{Note|1=请注意 <code><nowiki>1=<nowiki> some text &lt;/nowiki></nowiki></code>。有时候,部分文本可能会使wiki解析器混淆。而 <code><nowiki><nowiki>...</nowiki></nowiki></code> 可以防止这种情况。另外,如果像 <tt>n=</tt> 这样的文本出现在文本中间的话,解析器会对此感到困惑。将 <code>1=</code> 放在文本开头就可以防止这种情况。其他情况下,这个标记不会起作用。长话短说就是:这个标记没有坏处,而且可以防止一些烦人的副作用。}}


* Starting an Input or Output template on a new line will break the display format if it is within lists.  Simply continue on the same line if you need to correct this.
* 在新的一行上应用输入或输出模板将破坏列表中的显示格式 (如果你正在编辑列表的话) 。如果需要更正,在同一行上继续敲完模板就行了。


* You can also combine input/output areas with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi GeSHi syntaxhiglighting]. An input area like this {{Input|1=<nowiki>{{Input|<syntaxhighlight lang="php" line>
* 你也可以把输入/输出区域和 [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi GeSHi 语法高亮格式] 混合使用。像这样的输入 {{Input|1=<nowiki>{{Input|<syntaxhighlight lang="php" line>
# Initialise common code
# Initialise common code
$preIP = dirname( __FILE__ );
$preIP = dirname( __FILE__ );
require_once( "$preIP/includes/WebStart.php" );
require_once( "$preIP/includes/WebStart.php" );
</syntaxhighlight>}}</nowiki>
</syntaxhighlight>}}</nowiki>
}} will result in {{Input|<syntaxhighlight lang="php" line>
}} 产生的结果是 {{Input|<syntaxhighlight lang="php" line>
# Initialise common code
# Initialise common code
$preIP = dirname( __FILE__ );
$preIP = dirname( __FILE__ );
Line 77: Line 97:
</syntaxhighlight>}}
</syntaxhighlight>}}


* Single code words can be kept in-line by using {{Input|1=<nowiki><code></code></nowiki>}} It will <code>display</code> like this.
* 为了让单个出现的代码词汇显示在一行内,可以使用{{Input|1=<nowiki><code></code></nowiki>}} 它将会像这样被<code>显示</code>。注意,如果<nowiki><code></nowiki>标签之后紧跟着一个换行符号,它将不会正常地显示。


* {{Input|1=<nowiki>&lt;tt> &lt;/tt></nowiki>}} is useful for displaying filenames and paths.  This looks like this: <tt>  a/path/to/here </tt>
* 文件名和文件路径应该使用路径模板(后面会说到)。


==Block Quotes==
{{Warning|1=行内被<nowiki><code></nowiki>包含的代码文本应保持简短。如果一长串代码被分在几行显示的话,它看上去将十分怪异。并且记住一点,就算这样在你自己的浏览器看上去还行,别人的浏览器尺寸和你的不一定一样。即使您的文本在所有屏幕尺寸上看起来都不错,翻译可能仍然会受到影响。因此对于代码而言最好使用Input模板,除非它真的十分短。 }}


The tags <nowiki><blockquote></nowiki> and <nowiki></blockquote></nowiki> should be used when quoting other works or other pages.  This produces a proportional italic font, with some padding.
{{Note|1=请避免将shell命令和其他的代码词汇用作动词。这样子会翻译很不好。你应该永远把代码词汇视为专有名词。}}


<blockquote>Here is an example of the display that you get by using the blockquote tags.</blockquote>
<span id="Block_Quotes"></span>
==引用文本==


==Text in Section Headers==
当你引用其他人的文本时,应使用标签<nowiki><blockquote></nowiki>和<nowiki></blockquote></nowiki>。例如:


Even though the criteria above may be met, do not use Bold text in section headers or in links.
<blockquote>使用了blockquote标签的文本会像这样显示</blockquote>


==Text in Information, Note, Tip or Warning Templates==
<span id="Text_in_Section_Headers"></span>
==节标题中的文本==


Bold text should be avoided in the text within these templates.  Italic text for emphasis may still be used - use sparingly for maximum effect.
即使上述条件可能都符合,也不要在节标题或者链接中使用粗体文本。


<span id="Text_in_Information,_Note,_Tip_or_Warning_Templates"></span>
==信息、注释、提示或警告模板中的文本==
在这些模板中的文本中应避免使用粗体文本。你仍然可以使用斜体文本来起强调作用,但要谨慎使用以获得最好效果。
<span id="Lists"></span>
<span id="Lists"></span>
==列表==
==列表==


You can have various kinds of lists in your pages &mdash; bulleted, numbered or itemized. Find details on the [[Special:myLanguage/Toolbox#Bulleted Lists|Toolbox]] page.
你可能会在页面中用到各种列表——项目符号、编号或者逐项列出。前往[[Special:myLanguage/Toolbox#Bulleted Lists|工具箱]]页面以了解更多。
<span id="Keeping things together"></span>
<span id="Keeping_things_together"></span>
==把相关内容放在一起==


==Keeping things together==
当你编写一些文本后,翻译系统会自动为它们添加一些标记。这意味着每遇到一个空行,翻译系统便开始一个新的单元。当你的文本呈现给翻译者时,他们通常一次只阅读一个单元,因此不应该在本应被当做一个单元的文本的中间留下空行。一般来说一个段落应该放在一个单元之内;任何情况下都不要把一个句子拆分到不同的单元内!
 
After your text is written some markup is automatically added by the translation system. This means that whenever it sees a blank line, it starts a new unit. When your text is presented to translators, they typically see it one unit at a time, so it is important not to leave a blank lines in the middle of something that should be treated as a unit. Normally an entire paragraph should be kept in a single unit; and under no circumstance should a sentence be split between units!
 
If you need a linebreak in the middle of a section, the preferred way to achieve this is without breaking units is to use <nowiki><br /></nowiki> at the end of the line where you want to break to occur (not on a new line). If you need space between the lines add <nowiki><br /><br /></nowiki>.


如果您需要在一个部分的中间换行,那么在不破坏单位的情况下实现这一目标的首选方法是在您想要换行的行尾使用<nowiki><br /></nowiki>(而不是在新的一行)。 如果您想要在两行之间添加一个空行的话,请添加<nowiki><br /><br /></nowiki>。
<span id="Unbalanced brackets"></span>
==Unbalanced brackets==
==Unbalanced brackets==


Line 116: Line 145:


==Special Tags==
==Special Tags==
=== Key presses and menu selections ===


* <nowiki> <keycap></nowiki> and <nowiki> </keycap> </nowiki> denote (keyboard) key names e.g. <keycap>Enter</keycap>
* <nowiki> <keycap></nowiki> and <nowiki> </keycap> </nowiki> denote (keyboard) key names e.g. <keycap>Enter</keycap>
Line 121: Line 152:
* Sequences of menu choices should use <nowiki> <menuchoice> </nowiki>and <nowiki> </menuchoice> </nowiki> for example <menuchoice> View -> Message List -> Aggregation -> Standard Mailing List </menuchoice>
* Sequences of menu choices should use <nowiki> <menuchoice> </nowiki>and <nowiki> </menuchoice> </nowiki> for example <menuchoice> View -> Message List -> Aggregation -> Standard Mailing List </menuchoice>
* In general, if the user needs to choose an element, even if it is not in a menu, the <nowiki><menuchoice></menuchoiсe></nowiki> markup should be used.
* In general, if the user needs to choose an element, even if it is not in a menu, the <nowiki><menuchoice></menuchoiсe></nowiki> markup should be used.
* If you are contributing to a manual page, you should always use the markup describes above. For other pages, though, there is a template to enter menu selections: <nowiki>{{Menu|Top|sub|...}}</nowiki>. Fx, <nowiki>{{Menu | View | Message List | Aggregation | Standard Mailing List}}</nowiki> yields {{Menu | View | Message List | Aggregation | Standard Mailing List}}
* If you want to use the <nowiki><menuchoice></nowiki> but use &rarr; in stead of ->, you write <code>& rarr;</code> (without a space between '&' and r!) as in <nowiki><menuchoice> View</menuchoice> & rarr; <menuchoice>Message List</menuchoice></nowiki> which yields <menuchoice> View</menuchoice> &rarr; <menuchoice>Message List</menuchoice>. (Note, that the &rarr; character has to be outside of the menuchoice tags to be shown properly
=== Files and file paths ===
Traditionally, file names and paths have been marked up between <nowiki><tt>...</tt></nowiki> tags.
{{Input|1=<nowiki><tt>~/.kde/share</tt></nowiki>}}
yields
{{output|1=<tt>~/.kde/share</tt>}}
There is now also a template for this, which should be preferred in new content for ordinary UserBase pages (but not for manual pages, please!):
{{Input|1=<nowiki>{{Path | ~/.kde/share }}</nowiki>}}
yields
{{Output|1={{Path | ~/.kde/share }} }}


== The Problematic Pipe ==
== The Problematic Pipe ==
Line 131: Line 182:
In many cases, you can also enclose the text containing the pipe character between <nowiki><nowiki>...</nowiki> </nowiki> tags, like this <code><nowiki>{{Input|1=<nowiki>cmd1 | cmd2</nowiki></nowiki><nowiki>}}</nowiki></code>, which also displays {{Input|1=<nowiki>cmd1 | cmd2</nowiki>}}
In many cases, you can also enclose the text containing the pipe character between <nowiki><nowiki>...</nowiki> </nowiki> tags, like this <code><nowiki>{{Input|1=<nowiki>cmd1 | cmd2</nowiki></nowiki><nowiki>}}</nowiki></code>, which also displays {{Input|1=<nowiki>cmd1 | cmd2</nowiki>}}


<span id="Translatable_Content"></span>
==可译内容==
==可译内容==


Everything that is translatable is contained within <nowiki><translate> and </translate></nowiki> tags.  In most cases any images should be contained within the translatable section, as it is sometimes necessary to use localised versions of the images to explain a point.  The rule of thumb is "If in doubt, include it!".
Everything that is translatable is contained within &lt;translate> and &lt;/translate> tags.  In most cases any images should be contained within the translatable section, as it is sometimes necessary to use localised versions of the images to explain a point.  The rule of thumb is "If in doubt, include it!".


[[Category:贡献/zh-cn]]
[[Category:贡献/zh-cn]]

Latest revision as of 04:08, 19 May 2024

这些页面解释了页面布局语法,并且带有示例代码。

重要

遵循这些排版指南可以让您的文档准确方便地导出以供翻译。有些指南或许不适用于英语之外的语言。这些情况应该在特定语言的页面上注明,并在 翻译流程中做好链接。如果您的语言没有这种页面,那么请添加一个并在此处指明。


Links

Links to other UserBase pages should follow this pattern:

[[Special:MyLanguage/page name|whatever]]

[[Special:MyLanguage/Welcome to KDE UserBase|start page]] links to the welcome page in the readers language if the translation exists or else to the english version of that page.

Links to external pages follow normal wiki syntax:

[https://web.site.xxx/page text]

粗体字

用粗体字来突出

  • 窗口标题
  • 不能被用户自定义的一般化文本
  • 图标标题
  • 程序名字

比如:

  • 突出会复制到 Klipper 的所选文字。

斜体字

斜体文本起强调作用

  • 通常情况下想要强调的词语。
  • 引用的其他资源的标题。
  • 首次使用一个生僻词时。

例子:

  • 请在此时保存你的工作。
  • 相关细节可以在Samba 3 by Example找到....
  • KDE手册用Docbook格式编写。

Tip

程序 被用户启动,组件 被程序使用


粗体斜体并用

对于可替换的或者说可变的文本,请使用这种组合格式。

例子:

  • 要连接到你的远程服务器的话,在 Konsole 中键入 ssh [email protected]
  • 在基于rpm的发布包中,命令 rpm -q packagename 将输出 package-version-release

等宽文字

代码应该通过等宽文本显示,通常显示在框中,如下所示。输入文本将在淡黄色背景上。对于输出文本,背景颜色将为紫灰色。

  • 对于代码,无论是否是单行的,都应使用该模板以确保其平滑度
  • 请使用像这样的Input模板:
    {{Input|1=<nowiki>
    qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
    rm -r ~/.kde/share/apps/nepomuk
    rm -r ~/.kde4/share/apps/nepomuk
    nepomukserver</nowiki>}}
    这将会像这样显示:
    qdbus org.kde.NepomukServer /nepomukserver org.kde.NepomukServer.quit
    rm -r ~/.kde/share/apps/nepomuk
    rm -r ~/.kde4/share/apps/nepomuk
    nepomukserver


  • Output文本也一样:
    {{Output|1=<nowiki>terminal output 
    is also shown as code, 
    but on a grey background</nowiki>}}
    被显示为
    terminal output 
    is also shown as code, 
    but on a grey background

Note

请注意 1=<nowiki> some text </nowiki>。有时候,部分文本可能会使wiki解析器混淆。而 <nowiki>...</nowiki> 可以防止这种情况。另外,如果像 n= 这样的文本出现在文本中间的话,解析器会对此感到困惑。将 1= 放在文本开头就可以防止这种情况。其他情况下,这个标记不会起作用。长话短说就是:这个标记没有坏处,而且可以防止一些烦人的副作用。


  • 在新的一行上应用输入或输出模板将破坏列表中的显示格式 (如果你正在编辑列表的话) 。如果需要更正,在同一行上继续敲完模板就行了。
  • 你也可以把输入/输出区域和 GeSHi 语法高亮格式 混合使用。像这样的输入
    {{Input|<syntaxhighlight lang="php" line>
    # Initialise common code
    $preIP = dirname( __FILE__ );
    require_once( "$preIP/includes/WebStart.php" );
    </syntaxhighlight>}}
    产生的结果是
    # Initialise common code
    $preIP = dirname( __FILE__ );
    require_once( "$preIP/includes/WebStart.php" );
    
  • 为了让单个出现的代码词汇显示在一行内,可以使用
    <code></code>
    它将会像这样被显示。注意,如果<code>标签之后紧跟着一个换行符号,它将不会正常地显示。
  • 文件名和文件路径应该使用路径模板(后面会说到)。

Warning

行内被<code>包含的代码文本应保持简短。如果一长串代码被分在几行显示的话,它看上去将十分怪异。并且记住一点,就算这样在你自己的浏览器看上去还行,别人的浏览器尺寸和你的不一定一样。即使您的文本在所有屏幕尺寸上看起来都不错,翻译可能仍然会受到影响。因此对于代码而言最好使用Input模板,除非它真的十分短。


Note

请避免将shell命令和其他的代码词汇用作动词。这样子会翻译很不好。你应该永远把代码词汇视为专有名词。


引用文本

当你引用其他人的文本时,应使用标签<blockquote>和</blockquote>。例如:

使用了blockquote标签的文本会像这样显示

节标题中的文本

即使上述条件可能都符合,也不要在节标题或者链接中使用粗体文本。

信息、注释、提示或警告模板中的文本

在这些模板中的文本中应避免使用粗体文本。你仍然可以使用斜体文本来起强调作用,但要谨慎使用以获得最好效果。

列表

你可能会在页面中用到各种列表——项目符号、编号或者逐项列出。前往工具箱页面以了解更多。

把相关内容放在一起

当你编写一些文本后,翻译系统会自动为它们添加一些标记。这意味着每遇到一个空行,翻译系统便开始一个新的单元。当你的文本呈现给翻译者时,他们通常一次只阅读一个单元,因此不应该在本应被当做一个单元的文本的中间留下空行。一般来说一个段落应该放在一个单元之内;任何情况下都不要把一个句子拆分到不同的单元内!

如果您需要在一个部分的中间换行,那么在不破坏单位的情况下实现这一目标的首选方法是在您想要换行的行尾使用<br />(而不是在新的一行)。 如果您想要在两行之间添加一个空行的话,请添加<br /><br />。

Unbalanced brackets

The translation system marks any translated unit as incompletely translated if it contains any kind of unbalanced brackets. If you need to have unbalanced brackets in your text, please add a balancing bracket in a comment tag, like this:

<!-- }} -->{{ A line 

Another line}}<!-- {{ -->

This goes for all kinds of brackets, even ordinary parentheses. (Of course it is normally better to avoid blank lines within a mark up unit - see Keeping things together.)

Special Tags

Key presses and menu selections

  • <keycap> and </keycap> denote (keyboard) key names e.g. Enter
  • <keycap></keycap> can also be used around groups of keys to be used concurrently, e.g. Ctrl + Alt + F1 to launch a virtual terminal. (Note that "(space)+(space)" is used to link keys to be pressed concurrently).
  • Sequences of menu choices should use <menuchoice> and </menuchoice> for example View -> Message List -> Aggregation -> Standard Mailing List
  • In general, if the user needs to choose an element, even if it is not in a menu, the <menuchoice></menuchoiсe> markup should be used.
  • If you are contributing to a manual page, you should always use the markup describes above. For other pages, though, there is a template to enter menu selections: {{Menu|Top|sub|...}}. Fx, {{Menu | View | Message List | Aggregation | Standard Mailing List}} yields View Message List Aggregation Standard Mailing List
  • If you want to use the <menuchoice> but use → in stead of ->, you write & rarr; (without a space between '&' and r!) as in <menuchoice> View</menuchoice> & rarr; <menuchoice>Message List</menuchoice> which yields ViewMessage List. (Note, that the → character has to be outside of the menuchoice tags to be shown properly

Files and file paths

Traditionally, file names and paths have been marked up between <tt>...</tt> tags.

<tt>~/.kde/share</tt>

yields

~/.kde/share

There is now also a template for this, which should be preferred in new content for ordinary UserBase pages (but not for manual pages, please!):

{{Path | ~/.kde/share }}

yields

 ~/.kde/share 

The Problematic Pipe

In some situations the pipe symbol can't be used - for instance when adding parameters into a template. In any such case, please use {{!}} which will display as a pipe symbol. For example, if you want to display a command line containing the pipe character using the {{Input|...}} template, the simplest way to do it is this: {{Input|1=cmd1 {{!}} cmd2}} which displays

cmd1 | cmd2


If you just write {{Input|cmd1 | cmd2}} you get instead

cmd1 

the problem being, that cmd2 is seen as a second parameter to the template, which in this case is not used.

In many cases, you can also enclose the text containing the pipe character between <nowiki>... </nowiki> tags, like this {{Input|1=<nowiki>cmd1 | cmd2</nowiki>}}, which also displays

cmd1 | cmd2

可译内容

Everything that is translatable is contained within <translate> and </translate> tags. In most cases any images should be contained within the translatable section, as it is sometimes necessary to use localised versions of the images to explain a point. The rule of thumb is "If in doubt, include it!".