Difference between revisions of "Help:Style (正體中文)"

From ArchWiki
Jump to navigation Jump to search
(普遍原則: translation to zh-tw)
(使用者頁面: translation to zh-tw)
Line 313: Line 313:
 
== 使用者頁面 ==
 
== 使用者頁面 ==
  
* Pages in the [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=2 User] namespace cannot be categorized.
+
* 無法給予使用者頁面文章分類。
* Pages in the [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=2 User] namespace can only be linked from other pages in the ''User'' or ''talk'' namespaces, unless authorization to do otherwise is given by Administrators.
+
* 只有使用者頁面或使用者討論頁面才能夠連結到一個使用者頁面,除非具有管理員身份。
  
 
== 普遍原則 ==
 
== 普遍原則 ==

Revision as of 07:02, 21 November 2015

zh-cn:Help:Style

翻譯狀態: 本文章是 Help:Style 的翻譯版本。最近一次的翻譯時間:2015-10-25。點擊本連結查看英文頁面之後的變更。

Tango-preferences-desktop-locale.pngThis article or section needs to be translated.Tango-preferences-desktop-locale.png

Notes: not done yet (Discuss in Help talk:Style (正體中文)#)

以下的風格規範鼓勵人們使用整潔、組織化且視覺效果一致的文章呈現方式。請在編輯ArchWiki的時候遵守這些規範。

文章頁面

標題

  • 文章標題應該要根據sentence case的風格規範,比方說"Title for new page"是正確的,而"Title for New Page"是錯誤的風格。若有一般的單詞是專有名詞或是縮寫的一部分則應該以大寫呈現字首,如ALSA應該是"Advanced Linux Sound Architecture"而不是"Advanced Linux sound architecture"。命名空間不是標題的一部分,因此"ArchWiki:Example article"是正確的,而"ArchWiki:example article"是錯誤的呈現方式。子頁面的名稱應該要以大寫字母開始,正確的例子是"My page/My subpage",而"My page/my subpage"則不對。
  • 一個標題名稱應該要是單數的形式;在特殊的情況下,需要表示群體或是不同類別的可數名詞時,才需要表示成為複數形式。
  • 若有一篇文章的主題其名稱與縮寫都廣為人知,則在這裡偏好使用全名作為該文章的標題。請勿在標題同時使用全名與縮寫(比方說將縮寫放在後製括弧之中),而是應當編輯一個以縮寫為名稱的重新導向頁面,並讓該頁面指向以全名為標題的主頁面。
  • 參照Help:Article naming guidelines以了解為文章命名的原則。

格式呈現

  • 請在一篇文章中,依照順序呈現如下項目:
  1. 特殊用字 (不強制)
  2. 分類
  3. 多語言連結
  4. 文章狀態之樣板 (不強制)
  5. 相關文章 (不強制)
  6. 前言或簡介
  7. 目錄 (自動產生)
  8. 特定文章的章節

特殊功能關鍵字

  • 一般來說,特殊功能關鍵字會改變文章的顯示方式,但不改變文章的內容。這類的功能應該要放置在文章頂端。
    這個規則尤其應該使用在{{DISPLAYTITLE:title}}的功能,以及小寫樣板,因為後者使用了前者的功能。

文章分類

  • 每篇文章都應該至少歸屬於一種既定的分類
  • 一篇文章可以屬於多於一種的分類,只要那些分類之中沒有直接的上下階層的關係。
  • 分類與第一行文字內容之間不應該有空白行(或是跨語言連結),因為這樣會導致文章頂端額外的空間浪費。
  • 詳情請參考Help:Category文章。

跨語言連結

  • 若是文章具有其他語言版本(無論是ArchWiki內部或外部連結),跨語言連結應該要緊接在文章分類之後,且在首行文字之前。
    且需注意的是,這些跨語言連結在實際的呈現上會出現在頁面左方的窗格之中。
  • 在跨語言連結與首行文字之間不應該有空白行,否則會導致文章頂端的額外空間浪費。
  • 當在新增或編輯跨語言連結時,應該要在所有已經存在的翻譯版本也新增或修改那些連結。
  • 請勿為了同一種語言的文章新增超過一個跨語言連結。
  • 請勿在某種語言的文章新增其自身的跨語言連結。
  • 跨語言連結應該要以語言標籤的字母順序排序,如[[fi:Title]]應該要在[[fr:Title]]之前。
  • 詳情請參考Help:i18nWikipedia:Help:Interlanguage links等文章。

顯示文章狀態之樣板

  • 文章狀態樣板可以緊接在分類的下方(或跨語言連結的下方),而且在文章介紹(或是相關文章)之上。
  • 視情況,文章狀態樣板也可以用在文章內的章節。
  • 在加入文章狀態樣板時,請在適當的地方加入說明。若是需要的話,請在討論頁面直接發起討論。

相關文章

前言/簡介

  • 描述文章的主題。
    比起自行撰寫可能帶有偏差的描述,你可以使用該專案社群或作者對該專案的描述。MediaTomb就是一個例子。
  • 位在文章的第一個章節之前。
  • 請勿額外編輯==Introduction====Preface==的章節,因為簡介與目錄都會自動出現在第一個章節之前。
  • 請參照Help:Writing article introductions以取得更多資訊。

章節標題

  • 文章內的章節層級必須從第二級(==)開始,因為第一級已經被文章標題所保留。
  • 創建章節次標題時,請勿跳級。
  • 標題的大小寫規則依照句子的寫法,比方說不是全字首大寫My New Heading,而應該是My new heading
  • 避免在標題使用超連結,因為這樣會產生不一致的排版風格。應該改用以下方式呈現:
請參照Some related article
基於一樣的理由,請勿在標題使用HTML或wiki特有的效果,包括排版樣板。請參照Help:Style/Formatting and punctuation

格式化程式碼

  • 對於短短數行的程式碼、檔案名稱、指令名稱、變數名稱與一些可在文章中穿插使用的文字,使用{{ic|code}}語法標示。舉例而言,你可以使用這個寫法:
    在命令列中執行sh ./hello_world.sh
  • 若要將程式碼或指令表示在獨立區塊之中,可以將那些指令部份的開頭加上一個空白,請參考Help:Editing#Code的內容。舉例而言:
$ sh ./hello_world.sh
Hello World
  • 對於多行的程式碼或檔案等文字內容,可以使用{{bc|code}}樣板,以將之呈現在獨立區塊之中,舉例而言:
#!/bin/sh

# Demo
echo "Hello World"
  • 想要呈現命令列輸入與輸出的時候,使用{{hc|input|output}}樣板。舉例而言:
$ sh ./hello_world.sh
Hello World
  • 想要呈現檔案內容且需要展示檔案名稱時,使用{{hc|filename|content}}樣板,例為:
~/hello_world.sh
#!/bin/sh

# Demo
echo "Hello World"
  • 對於整個區塊的程式碼或檔案,請僅顯示相關的重點,不相關的則以(...)省略不相關的內容。
  • 參考Help:Template以獲得更多資訊,以及關於排版相關議題的的疑難排解,如=|

命令列文字

  • 需要在內文引用程式碼時,不應加入命令列符號,但櫻明確描述相對應指令所需要的權限。
  • 當使用程式碼區塊(或以空白格開頭的程式碼)時,應使用$示意為一般使用者之命令列,而#為root之命令列。需注意#符號在文字檔中也代表註解的形式,請避免混淆的情況出現(這可以透過額外的說明「執行指令」或「寫入檔案」的情況)。
    • 使用程式碼區塊之前的文字敘述應以冒號結尾。
    • 除非有其必要,否則描述特權指令時,偏好使用:
      # command
      而非:
      $ sudo command
    • 請勿將root命令列與sudo指令混用,如:
      # sudo command
      唯一的例外是指定使用者功能(sudo -u),這個情況下必須符合同一個程式碼區塊中的其他指令用法,或是單純採用$命令列指示字元。
    • 請勿在同一個程式碼區塊添加註解。
    • 請避免撰寫太長的程式碼;必要時當使用適當的斷行。
  • 請勿假設使用者使用sudo或是其他取得特權指令如gksukdesu

編輯檔案

  • 需要編輯檔案時,請勿假設使用者使用特定的編輯器,除非確有需要。
  • 需要編輯檔案時,請勿使用不明確的指令操作,除非確有需要。舉例而言,$ echo -e "clear\nreset" >> ~/.bash_logout應該編寫為:
附加下列數行至檔案~/.bash_logout
clear
reset
若有需要,亦可添加連結至Help:Reading#Append, add, create, edit

按鍵

  • 於文章中呈現鍵盤按鍵的標準方法是使用ic的樣板
  • 普通的字母按鍵應該表示為小寫,如:a;若要呈現大寫,則請使用Shift+a的表示法,而不是Shift+AA
  • 組合鍵的正確呈現方式是使用加號連結多個按鍵。這些組成必須包含在同一個樣板之內,且彼此之間無空白區隔,如:Ctrl+c
    Ctrl + cCtrl+c或是Ctrl-c都是不良的呈現方式,請避免。
  • 若要呈現連續按鍵,可以使用字面敘述,如:按下g之後緊接著按下Shift+t;或者更明確地,使用空格區別它們,如:g Shift+t
  • 以下是一些常用特殊件的標準呈現方式:
    • Shift (而不是 SHIFT)
    • Ctrl (而不是 CTRLControl)
    • Alt (而不是 ALT)
    • Super (而不是 WindowsMod)
    • Enter (而不是 ENTERReturn)
    • Esc (而不是 ESCEscape)
    • Space (而不是 SPACE)
    • Backspace
    • Tab
    • Ins (而不是 INSInsert)
    • Del (而不是 DELDelete)
    • PrintScreen
    • PageUp
    • PageDown

Package management instructions

Official packages

  • Please avoid using examples of pacman commands in order to give instructions for the installation of official packages: this has been established both for simplicity's sake (every Arch user should know pacman's article by memory) and to avoid errors such as pacman -Sy package or possibly never-ending discussions like the choice between pacman -S package and pacman -Syu package. All the more reason you should not suggest the use of pacman frontends or wrappers.
Instead, just use a simple statement like:
Install the foobar package.
Or, if for example the application name differs from the package name:
MyApplication can be installed with the my-app-pkg package.
The instructions for the installation of a list of packages may appear as:
Install the foobar1, foobar2 and foobar3 packages.
If referring to a package group you may use:
Install the foobar group.
You are granted the flexibility to adapt the wording to your specific article.
  • Links to the referenced packages are mandatory and should be created using Template:Pkg, for example {{Pkg|foobar}}.
When referring to package groups, Template:Grp should be used instead, for example {{Grp|foobar}}.
  • The above examples also make use of a link to install (e.g. [[install]]): this is recommended to be used at least on the first occurrence of an installation request, especially in articles that are more likely to be visited by Arch novices.
  • Examples of pacman commands are nonetheless accepted and even recommended in the Beginners' guide.
  • If the package is hosted in the core, extra, or community repositories, do not make reference to the repository, thus facilitating maintenance because it is not uncommon for a package to be moved to a different repository. If however the package is hosted in an official repository which is not enabled by default (multilib, testing, etc.), mentioning it is required, using a wording like:
Install the foobar package from the official multilib repository.

AUR packages

  • Please avoid using examples of how to install AUR packages, neither with the official method nor mentioning AUR helpers: every user who installs unofficial packages should have read the Arch User Repository article, and be aware of all the possible consequences on his system.
Instead, just use a simple statement like:
Install the foobarAUR package.
You are granted the flexibility to adapt the wording to your specific article, see the section on #Official packages for more examples.
  • Links to the referenced packages are mandatory and should be created using Template:AUR, for example {{AUR|foobar}}.

Unofficial repositories

  • When suggesting to use an unofficial repository for installing a pre-built package, do not provide instructions for enabling the repository, but make sure such repository is included in Unofficial user repositories and then simply link to it. Also, just like with official packages, do not add examples of pacman commands. For example:
Install the foobar package from the example repository.
If the package is also available in the AUR:
Install the foobarAUR package, also available in the example repository.
If the package is available in the AUR with a different name:
Install the aurpkgAUR package, also available as builtpackage from the example repository.
You are granted the flexibility to adapt the wording to your specific article.
  • The link to Unofficial user repositories is mandatory and should point to the relevant repository section, for example [[Unofficial user repositories#example|example]].

systemd units operations

  • Do not give examples of how to enable, start, or perform any other basic operations with systemctl on systemd units. Instead, use a simple sentence listing the units involved, possibly remarking dependencies or conflicts with other units, and a description of the actions to be performed. For example:
To have GDM launched at boot time, enable gdm.service.
Or, if for example the unit is a template that needs instantiation:
To enable automatic switching of netctl profiles on a wireless interface, enable an instance of netctl-auto@.service with the interface name, for example netctl-auto@wlan0.service.
You are granted the flexibility to adapt the wording to your specific article.
  • Make sure to link to the systemd#Using units article section, either directly or through a dedicated redirect like [[start]], [[enable]] or [[stop]].
  • Examples of systemctl commands are nonetheless accepted and even recommended in the Beginners' guide.

Notes, Warnings, Tips

  • A Note should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package.
A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
  • A Warning should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
In general, do not abuse Warnings: if you are undecided, chances are high that you should use a Note.
  • A Tip should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
  • When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
Tip:
  • Tip example #1.
  • Tip example #2.

Shells

  • Do not assume a particular shell as the user's shell (e.g. Bash), except when really needed: try to be as shell-neutral as possible when writing or editing articles.

Hypertext metaphor

  • Try to interlink your article with as many others as you can, using the various keywords in the text.
  • Only link to a new article after creating it. In general, do not create links to non-existent articles.
  • For technical terms, such as system call, not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
  • When linking to other articles of the wiki, do not use full URLs; take advantage of the special syntax for internal links: [[Wiki Article]]. This will also let the wiki engine keep track of the internal links, hence facilitating maintenance.
    See Help:Editing#Links for in-depth information and more advanced uses of interwiki links syntax.
  • Avoid implicit links whenever possible. For example, prefer instructions like "See the systemd article for more information" instead of "See here for more information".
  • Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked to from any other).
  • Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
  • If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
  • Do not use interwiki links for links to localized pages of the same language of the article being edited because they will not be shown in Special:WhatLinksHere pages. For example, using [[:hu:Main page]] in a Hungarian article is wrong, while [[Main page (Magyar)]] is correct.
    Using this kind of links between different languages is instead acceptable because this would make it easier to move the articles to a separate wiki in case a separate wiki is created in the future.
    Finally, note the difference of this kind of links from #Interlanguage links, which do not have the colon at the beginning.

Coding style

  • When adding commands or scripts, use a consistent coding style throughout the article, possibly also referring to the other articles, especially if there are any related ones. If available, respect the official or most common coding style guidelines for the language.
  • Avoid deprecated features of the programming/scripting language you are using: for example, use the $() syntax for shell command substitution instead of the backticks/grave (``) syntax.

Supported kernel versions

  • Do not remove any notes or adaptations regarding kernel versions greater than or equal to the minimum version between the current linux-lts package in the core repository and the kernel on the latest installation media.

"Tips and tricks" sections

  • Tips and tricks sections provide advanced tips or examples of using the software.
  • Use the standard title of Tips and tricks.
  • The various tips and tricks should be organized in subsections.

"Troubleshooting" sections

  • Troubleshooting sections are used for frequently asked questions regarding the software or for solutions to common problems (compare to #"Known issues" sections).
  • Use the standard title of Troubleshooting. Common misspellings that should be avoided are Trouble shooting, Trouble-shooting, and TroubleShooting.
  • You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
    There are great benefits in linking to a bug report both for readers and editors:
    • For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
    • For Wiki editors, it makes cleanup easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.

"Known issues" sections

  • Known issues sections are used for known bugs or usage problems which do not have a solution yet (compare to #"Troubleshooting" sections).
  • Use the standard title of Known issues.
  • If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.

"See also" sections

  • See also sections contain a list of links to references and sources of additional information.
  • This should be a list where each entry is started with *, which creates a MediaWiki bulleted list.
  • Use the standard title of See also. Other similar titles such as External links, More resources, etc. should be avoided.

Non-pertinent content

  • Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors.
    Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
  • Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like Asciiflow. Rationale:
    • Maintenance: Arch is rolling release, and images would make updating articles much more difficult.
    • Necessity: Arch does not develop nor maintain any sort of GUI application, so we do not need to display any screenshot.
    • Moderation: free image upload would require time to be spent removing oversized or inappropriate images.
    • Accessibility: we support users with slow connections, text-only browsers, screen readers and the like.
    • Efficiency: images waste server bandwidth and storage space.
    • Simplicity: text-only articles just look simpler and tidier.

Language register

  • Articles should be written using formal, professional, and concise language. Care should be taken to remove grammar and orthography errors through edit previews and proofreading.
  • Remember not only to answer how, but also why. Explanatory information always goes further toward imparting knowledge than does instruction alone.
  • Avoid contractions: "don't", "isn't", "you've", etc. should be "do not", "is not", and "you have", for example.
  • Avoid unnecessary shortening of words: for example, instead of "repo", "distro", and "config", prefer "repository", "distribution", and "configuration".
    In the same fashion, prefer using the long form of uncommon command options instead of their single-character counterpart.
  • Do not omit terms that are necessary to give an exact, unambiguous meaning to a sentence. For example, always add the word "repository" when mentioning the name of a repository.
  • Do not use indefinite time references such as "currently", "at the time of writing" or "soon"; replace them with definite expressions such as "as of May 2015" etc.
  • Write objectively: do not include personal comments on articles; use discussion pages for this purpose. In general, do not write in first person.

分類頁面

  • Every category must be appropriately categorized under at least one parent category, except for root categories, which are Category:DeveloperWiki, Category:Languages, Category:Maintenance and Category:Sandbox.
  • A category can be categorized under more than one category, provided one is not ancestor of the others.
  • Avoid circular relationships: two categories cannot be reciprocal ancestors.
  • Do not categorize a category under itself (self-categorized category).
  • Categories must be included at the top of the category page.
  • Categories should not redirect, except temporarily during renaming.
  • By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe one of its members ("set" categories).

重新導向頁面

  • Redirect pages should contain only the redirect code and nothing else. In rare cases, they can also contain a flag such as Template:Deletion.
  • Redirect only to internal articles; do not use interwiki redirections.
Redirects using interlanguage links are exceptionally allowed in accordance with Help:I18n and upon authorization from the ArchWiki:Maintenance Team.

使用者頁面

  • 無法給予使用者頁面文章分類。
  • 只有使用者頁面或使用者討論頁面才能夠連結到一個使用者頁面,除非具有管理員身份。

普遍原則

編輯總結

每一次的編輯都應該附帶簡明的總結,參見ArchWiki:Contributing#The 3 fundamental rules一文。

HTML標籤

  • 我們不建議使用HTML標籤。請盡量使用wiki的修飾功能或是樣板,請參見Help:Editing
  • 當你需要HTML中的pre標籤功能(如<pre>code</pre>)時,請使用bc樣板({{bc|code}});當你需要tt標籤功能(如<tt>text</tt><code>text</code>)時,請使用ic樣板({{ic|text}})。
  • 尤其是請避免使用HTML的註解功能(<!-- comment -->),編輯者可考慮將註解的內容放在討論頁面,或是為文章本身加上文章狀態的樣板
  • 僅有在必要的時候使用<br>標籤,應該盡量開啟新的段落或是增加空白行以達成換行效果。
    常見的例外是在清單之中想要斷行,或是在樣板之中無法使用清單的時候。