Help:Style (正體中文)

From ArchWiki
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

相關文章

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

Tango-preferences-desktop-locale.png本條目或段落需要進行翻譯。Tango-preferences-desktop-locale.png

註記: not done yet (討論)

以下的風格規範鼓勵人們使用整潔、組織化且視覺效果一致的文章呈現方式。請在編輯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:i18n#Page titles的規定。
  • 參照Help:Article naming guidelines以了解為文章命名的原則。

格式呈現

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

特殊功能關鍵字

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

文章分類

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

跨語言連結

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

顯示文章狀態之樣板

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

相關文章

前言/簡介

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

章節標題

  • 文章內的章節層級必須從第二級(==)開始，因為第一級已經被文章標題所保留。
  • 創建章節次標題時，請勿跳級。
  • 標題的大小寫規則依照句子的寫法，比方說不是全字首大寫My New Heading，而應該是My new heading。
  • 避免在標題使用超連結，因為這樣會產生不一致的排版風格。應該改用以下方式呈現：
請參照Some related article。
基於一樣的理由，請勿在標題使用HTML或wiki特有的效果，包括排版樣板[broken link: invalid section]。請參照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或是其他取得特權指令如gksu或kdesu。

編輯檔案

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

按鍵

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

關於套件管理的指示

官方套件

  • 撰寫關於安裝官方套件的指令時，應當避免在文中直接使用pacman，這是不但為了簡單考量(所有Arch的使用者都應該知道pacman套件管理工具)，也為了避免錯誤，如：pacman -Sy package，或是幾乎永不停止的討論如pacman -S package與pacman -Syu package之間的取捨。更進一步，撰寫指令時也應該避免建議其他建立在pacman之上的工具。
請直接使用簡單的描述，如：
安裝foobar套件。
在應用程式名稱與套件名稱相異的場合，則使用：
MyApplication可以藉由安裝my-app-pkg套件使用。
安裝一連串套件的指令可以如以下方式呈現：
安裝foobar1、foobar2以及foobar3套件。
若要指名某一套件群組，使用：
安裝foobar群組。
當然，你有彈性去決定如何用字遣辭。
  • 相關套件的連結至關重要，應該使用Template:Pkg，如{{Pkg|foobar}}。
當連結到套件群組時，則使用Template:Grp，如{{Grp|foobar}}。
  • 對於安裝也建議一併附上連結，也就是[[install|安裝]])。我們推薦至少在安裝指令的第一次出現時附上這個連結，尤其是那些容易被Arch新手造訪的條目。
  • 若該套件位於core、extra或是community套件庫中，請勿連結至這些套件庫。這是為了方便套件的管理，因為遷移套件於不同的套件庫中並非罕見的事情。若是在非預設的官方套件庫如multilib或testing，提及這些套件庫則是必要的，如：
自multilib套件庫安裝foobar套件。

AUR套件

  • 請避免使用範例展示安裝AUR套件的方法，無論是官方的方法或是AUR的額外工具。因為每個安裝非官方套件的使用者都應當閱讀Arch User Repository的說明，以明白所有可能對系統造成的後續影響。
如有需要，請使用下列敘述：
安裝foobarAUR套件。
當然，你有彈性去決定如何用字遣辭。可以閱讀這個段落[broken link: invalid section]以找到更多用法範例。
  • 套件的連結是重要的，應當使用Template:AUR，如{{AUR|foobar}}。

非官方套件

  • 建議他人使用非官方套件庫安裝預先建置的套件時，請勿提供啟用該套件庫的指令，而應當將該套件庫加入並確認其存在於非官方套件庫中再行連結。並且，類似官方套件[broken link: invalid section]的作法，請勿直接使用pacman指令的範例，如：
自example[broken link: invalid section]套件庫中安裝foobar套件。
若該套件在AUR中可用，則可提供如下說明：
安裝foobarAUR套件，亦可自example[broken link: invalid section]套件庫安裝。
若是該套件在AUR中具有不同的命名，則可提供以下說明：
安裝aurpkgAUR套件, 亦可安裝example[broken link: invalid section]套件庫中的builtpackage套件。
你有彈性去決定如何用字遣辭。
  • 非官方套件庫的相關連結至關重要，應該被指名，如[[Unofficial user repositories#example|example]]的方式。

systemd元件相關操作

  • 避免直接使用systemctl指令之操作範例，而應該使用描述性的語句說明應當達成的事項。如：
要將GDM設定為開機即開啟，啟用gdm.service服務。
或者，若該systemd元件是一個需要實體化(instantiation)的樣板(template)：
欲啟用無線網路介面的netctl資料自動切換，啟動netctl-auto@.service的一個實體並附帶該介面名稱。例：netctl-auto@wlan0.service。
你可以有彈性地用字遣詞。
  • 務必連結到systemd#Using units的文章段落。可以是直接的連結redirect，或是[[start]]、[[enable]]及 [[stop]]之類的用法。

提醒、警告、技巧

  • 若某些資訊與讀者對該篇文章的自然理解有所分歧，則應當使用提示樣板。這個樣板也可用於其他更加深入的知識，當直接加入那些內容於本文之中會顯的不具有關連性的時候。其他使用情境的例子則包含暫時性的宣告，如一個套件名稱的改變。
提醒樣板也可以用在加強那些重要而易被初接觸該主題的人忽略的內容。
  • 若是文章內容描述了某些可能造成系統難以回覆甚至損害的過程，則應該使用警告樣板。警告樣板應當包含最糟糕的後果以及避免那些結果的方式。
一般而言，不要濫用警告；若是你無法決定該使用何者，很有可能你該使用的是提醒樣板。
  • 對於一些可能帶給某些使用者好處的方法與流程可以使用技巧樣板，它們對於完成相關主題的目標並非必要手段，因此可以安全地忽略。
  • 當有兩個或更多的提示、警告或技巧必須在文章中的同一段落出現時，請使它們列舉在同一個樣板之中；除非它們完全彼此無關，否則請避免使它們各自堆疊。舉例而言：
提示: ABC
  • Tip example #1.
  • Tip example #2.

Shells

  • 請勿假設使用者使用特定的shell(如Bash)，除非真的需要特別指明環境。撰寫或編輯文章時請保持對各shell環境中立的態度。

超連結

  • 請試著使用你的文章中的關鍵字與盡可能多的其他條目做連結。
  • 在新的文章完成之後再連結它們。原則上，應避免連結到不存在的文章。
  • 在Archwiki之中沒有詳述的科技術語，如system call應當連結到維基百科。
  • 連結到本站的其他文章時，請勿使用完整的網址；反之，使用內部連結的特殊語法：[[Wiki Article]]，這將使得維基引擎得以追蹤內部連結，增加維護的程度。詳見Help:Editing#Links之相關討論。
  • 避免文意不清的連結。例如，「請參考systemd」，而非「請參考這篇文章」。
  • 除了一些罕見的情況，你不應創建沒有任何連結參考的文章或是沒有任何文章能夠連結到的文章。
  • 在撰寫一些特定的流程時，請先確認相關細節是否已經在其他文章出現過；若有，則以連結代替重複。
  • 若是專案上游的相關主題文件易懂且維護良好，則為了一般性考量，請只注重與Arch相關的部份並連結到該上游文章。
  • 對於相同語言文章中的本地化文章，請勿使用內部連結，因為如此一來它們將不會顯示在Special:WhatLinksHere頁面中。舉例而言，在Hungarian文章中使用[[:hu:Main page]]是錯誤的用法；使用[[Main page (Magyar)]]則是正確的。
    考量到不同語言在未來可能會使用不同的wiki系統管理，跨語言的內部連結則是可接受的。
    最後，請注意這類連結與跨語言連結[broken link: invalid section]的差異：它們並沒有冒號在文章標題之前。

程式碼風格

  • 撰寫指令或script時，請維持一致的程式碼風格，如果情況允許的話也應附上連結到其他文章以做參考。如果情況允許，請遵循官方或是該種語言最普遍的程式碼風格。
  • 避免已經被廢棄的用法。以shell script為例，使用$()來表示shell指令代換，而非``。

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).

重新導向頁面

  • 重新導向頁面應當只包含重新導向需要的程式碼。
  • 重新導向應當只用以連結內部文章；請勿將重新導向用在跨wiki頁面。
為了符合與Help:i18n的一致性以及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>標籤，應該盡量開啟新的段落或是增加空白行以達成換行效果。
    常見的例外是在清單之中想要斷行，或是在樣板之中無法使用清單的時候。