說明:風格 - Arch Linux 中文维基

跳至內容

# 說明:風格

出自 Arch Linux 中文维基

相關文章

- Help:Style/Formatting and punctuation
- Help:Style/White space
- Help:編輯
- Help:閱讀
- Help:討論
- Help:模板
- Help:術語表

翻譯狀態：

- 本文（或部分內容）譯自 Help:Style，最近一次同步於 2021-09-14，若英文版本有所更改，則您可以幫助同步與翻譯更改的內容。
- 您可以在 ArchWiki 的對應頁面找到本文翻譯的原始修訂歷史。
- 本文可能與英文原文存在出入。

這些風格約定鼓勵簡約、有條理和視覺一致的文章。請在編輯 ArchWiki 時儘量遵守本文的指導。

## 文章頁面

### 標題

- 標題應該使用整句大小寫格式, 例如應該使用 "Title for new page" 而不是 "Title for New Page"。如果單詞是常見縮寫的一部分，則應該使用大寫，例如應該使用 "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.
- 參見文章命名指導。

### 布局

ArchWiki 上的文章應該分為兩部分：前言和主體，且主要遵循如下順序：

- 前言：由分類、i18n、文章狀態、概覽和簡介
- 主體: 介紹、安裝、配置、技巧、問題解決和更多內容

- 文章各部分的排列順序應該為:

1. #特殊欄位 (可選)
2. #分類
3. #跨語言連結 (可選)
4. #文章狀態模板 (可選)
5. #相關文章 (可選)
6. #前言或介紹
7. 目錄 (自動生成)
8. 文章特有的部分

#### 特殊欄位

- 特殊欄位會修改文章的顯示方式，但並不會添加內容。這些欄位應該位於文章的最開始，尤其是這兩個：`{{DISPLAYTITLE:title}}` 和模板:小寫標題。

#### 分類

- 每個文章至少應該屬於一個分類。
- 一個文章可以屬於多個分類，只要分類間沒有包含關係。
- 分類必須放在文章的頂部，且在特殊欄位之後。

注意：這點和其它 MediaWiki 項目有時會不一樣，後者經常把分類放在文章末尾。

- 分類與正文第一段（包括跨語言連結）之間不要插入空格，否則會有多餘的空白。
- 參見文章分類。

提示：

- 由於分類頁面中，MediaWiki會把相同首字母的頁面歸到一欄中，對於中文標題的頁面，會把每個起始漢字歸到一類，導致頁面很混亂。因此在為名稱由中文起始的頁面，添加分類時請同時添加漢語拼音的首字母，如官方安裝指南可以添加如下分類：`[[Category:简体中文|G]]`，這樣該頁面就會歸類到字母G一欄的最上方。
- 不要添加多個字母(如：`[[Category:简体中文|GFAZZN]]`)，否則會出現分類中中英文頁面順序混排的現象，使頁面不便於查找。

#### 跨語言連結

- 如果文章有其他語言的翻譯，必須在分類和正文第一段之間加上這些跨語言連結。它們將顯示在頁面的左邊。
- 跨語言連結和正文第一段之間不應該有空格，否則文章頂部會有多餘的空白。
- 除了在當前頁面上添加其它跨語言連結，您還需要在其它語言的頁面上添加當前頁面的跨語言連結。
- 每個語言的跨語言連結應只能有一個。
- 不要加入當前語言的跨語言連結。
- 跨語言連結需要根據其語言標籤，來按字母表順序排列，不要按語言本身的正式名稱順序排列。例如，`` 就該排在 `` 前面，哪怕 「Suomi」 就本來在 「Français」 之後。
- 參見 Help:i18n 和 Wikipedia:Help:Interlanguage links.

#### 文章狀態模板

- 文章狀態模板應放在分類(或跨語言連結)和相關文章之間。
- 針對段落的標記，位置儘量靠近有問題的地方。
- 每個狀態模板都應該包含簡要的說明。有必要時，可以在討論頁面加以討論。

#### 相關文章

- 給出相關的文章列表
- 放在分類、跨語言連結和文章狀態模板之後。
- 通過組合模板模板:相關文章開始, Template:Related 和模板:相關文章結束實現。詳情參閱這幾個模板的頁面。
- 可以使用 Template:Related2 給出需要顯示的標題翻譯.
- 如果文章較多，或者需要詳細描述，請使用參閱段落。

#### 前言或介紹

- 描述文章的話題。
  不要自己給軟體下評論，一般可以訪問項目主頁，使用作者自己的描述。MediaTomb 是一個範例。
- 放在第一段前面
- 不要另外加上 `==Introduction==` 或 `==Preface==` 說明：直接在第一段開始時寫入即可。如果文章有足夠多的段落，在前言和第一段直接會自動加入目錄。
- 參見 Writing Article Introductions。

#### 標準段落

##### "安裝" 段落

- 安裝段落介紹軟體的安裝方法，請參考 #指南.
- 標準的標題是安裝，儘量往前放.

##### "已知問題" 段落

- 已知的 bug 或者使用問題，暫時還沒有解決方法(與#"問題解決" 段落相反)。
- 標準標題是已知問題.
- 儘量避免明確的版本號，如果這個問題已經報告了 bug，請提供連結；如果沒有報告，請報告它，這樣會提高問題解決的概率。

##### "提示與技巧" 段落

- 高級技巧或使用軟體的示例
- 標準標題應是提示與技巧
- 用子段落分別介紹不同的技巧

##### "問題解決" 段落

- 常見問題的解決辦法(與 #"已知問題" 段落不同)。
- 標準標題是問題解決。
- 可以提供繞過已知 bug 的臨時解決方法，但是請務必提供該 bug 的連結地址；如果還未得到報告，請自行報告 bug，這樣可以讓它更容易被修復。
  增加 bug 連結對讀者和編輯有如下好處：
  - 對讀者來說，閱讀該 Wiki 並非就到此為止了：他們還可以進一步訪問連結，獲取更多信息。
  - 對 Wiki 編輯來說，更好判斷 bug 是否已經解決，容易維護；如果讀者有得到新信息，他們也可以自主編輯。

##### "參見" 段落

- 列出參考文檔和額外信息.
- 應該是個列表，每行都以 `*` 開頭。
- 一般使用 "參見" 作為標題，應該避免使用"外部連結","更多資源",「參閱」 等。

### 段落標題

- 段落標題應該從第二級開始(`==`), 因為第一級已保留給文章標題用。
- 使用子標題時不要越級，就像二級標題下面必然是三級標題。
- 不要在標題上添加超連結，它們會破壞樣式的一致性。
  同理，請不要使用任何 html 或 wiki 標記代碼，包括 #代碼格式。
- 參見 Effective Use of Headers。

### 格式

#### 代碼格式

- 使用 Template:ic 格式化要嵌入的代碼片段、文件名、路徑、命令名、配置參數、變量等。例如:
  在終端運行`sh ./hello_world.sh`
- 對於單行的代碼 (命令行或者代碼輸出) 可以可以直接在行首加入空格，參考Help:Editing#Code. 示例：

    $ sh ./hello_world.sh

    Hello World

- 使用 `{{bc|code}}` 格式化多行代碼(命令行的輸入或輸出內容、文件內容) 例如:

    #!/bin/sh

    # Demo
    echo "Hello World"

- 如果代碼不長，代替 `{{bc|code}}` (參見編輯幫助)。
- 使用 `{{hc|input|output}}` 能同時顯示命令行及其輸出，例如:

    $ sh ./hello_world.sh

    Hello World

- 需要顯示文件內容時，可以使用 `{{hc|filename|content}}` 明確內容屬於哪個文件，例如：

    ~/hello_world.sh

    #!/bin/sh

    # Demo
    echo "Hello World"

- 大段的代碼，例如配置文件，可以考慮用 `...` 略去無關的內容
- 關於模板的一些格式上的特殊處理，比如`=` 或 `|`，請閱讀 Help:Template。

### 命令行文字

- 使用段落代碼 (Template:bc) 時，需要提示符標註執行權限;使用 Template:ic 時不需要提示符，但是需要用文字明確指出需要的權限。
- 使用 `$` 作為一般用戶權限命令的提示符；使用 `#` 作為 root 命令的提示符。
  注意：因為 `#` 也經常表示文本文件中的注釋符號，所以經常要澄清是運行命令還是編輯文件，以避免不必要的誤解。
- 引入命令的句子儘量以 `:` 結尾。
- 建議使用 `# command` 而不是 `$ sudo command`。
- 儘量少假設用戶會使用 `sudo` 或其它權限獲取工具(例如 `gksu`、`kdesu`)。
- 應該避免`# sudo command`，唯一的例外是用`sudo`的`-u`選項修改用戶，這時提示符可以與其它命令一致，默認使用`$`。
- 不要在一行命令的代碼框裡添加注釋，例如`# pacman -S foo #Install package foo`就不好
- 代碼行不要過長，請儘量換行。

### 鍵盤按鍵

- 表示按鍵的標準方法是使用 Template:ic 模板。
- 字母鍵應該小寫：`a`. 大寫字母用 `Shift+a`，不要使用 `Shift+A` 或 `A`。
- 表示按鍵組合的正確方法是使用 `+` 號連接，不要增加額外空格，在一個模板中包含多個按鍵：`Ctrl+c`.
  下面格式都應該避免使用：`Ctrl + c`, `Ctrl`+`c`, `Ctrl-c`。
- 特殊鍵的標準名稱：
  - `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`)
  - `Print Screen`
  - `Up` (不要使用 `↑` 或 `Up Arrow`) – 其它方向鍵類似
  - `PageUp`
  - `PageDown`
  - `Fn` (不要使用 `FN` 或 `fn`) – 不同筆記本上的功能按鍵請參考這裡。

### 注意、警告、提示

- 注意應該用在用戶預料不到的地方。包括與文章關係不大的細節知識、軟體包名稱變動等。
  也可以用來強調容易被用戶忽略的地方。
- 警告用來指出需要特別警惕的地方，比如不可逆轉的修改、損害系統的可能性等。警告應該直接指出最壞的情況，並給出相應措施。不要濫用警告，如果不確定的時候，用注意即可。
- 提示用來給出一個可能會相當有用的小技巧，一般不是必須的，省略也無妨。
- 如果多個注意、警告、技巧連用，最好組合到單一模板中，除非彼此毫無相干。例如:

  提示：
  - Tip example #1.
  - Tip example #2.

#### 表格

關於表格的語法，請參見 MediaWiki 幫助文檔。

- 表格通常需要包含 `wikitable` 類。
- 對照表還應包含 `sortable` 類。
- 在適當的地方使用表格標題和表格模板。
- 表格標題的第一個字母應該大寫，其餘應該小寫。（漢字並無大小寫之分，故本條可被忽略）
- 表格說明應使用定義列表，並放在表格之前。

### 指南

- 除非必要，請不要特別指定某編輯器(nano, vim, emacs, ...)。
- 除非必要，請不要使用隱晦複雜的編輯命令，就像 `$ echo -e "clear\nreset" >> ~/.bash_logout` 應該寫成這樣：

  將下行附加到 `~/.bash_logout`:

      clear
      reset

  合適的話可以增加一個到 Help:Reading#Append, add, create, edit 的連結。

#### 官方軟體包

- 在示意要從官方軟體倉庫安裝軟體包時，請避免直接標出 pacman 命令。不僅簡化內容(每個 Arch 用戶都應該知道如何使用 pacman)而且避免了 `pacman -Sy package` 之類的鍵誤，以及 `pacman -S package` 和 `pacman -Syu package` 孰好孰壞的無謂爭論。同理，也不要引入 pacman 前端或圖形界面等。
  相反，請像這樣簡單地示範：安裝說明應該使用： `[[pacman (简体中文)|安装]] 软件包 {{Pkg|package}}`。
- 如果安裝的是一組軟體包，則使用 : 安裝軟體組 foobar包組.
- 必須要用 Template:Pkg/和Template:Grp 模板進行格式化，例如`{{Pkg|package}}`.
- 不要特意指出軟體包是在 [core]、[extra] 或 [community] 中的哪一個倉庫，因為一個軟體包可能會在不同倉庫之間轉移。此外如果軟體包位於 [multilib] 倉庫，請這樣示範：
  安裝官方軟體倉庫的 package包 時，需要事先開啟 multilib 倉庫。

#### AUR 軟體包

- 安裝 AUR 軟體包的語句安裝`[[Arch 用户软件仓库|AUR]] 中的 {{AUR|package}}`。
- 可以適當修改以適應具體文章，但是一定要明確指出軟體包並非官方支持。
- 千萬不要直接示範如何安裝 AUR 軟體包：因為凡是安裝非官方軟體包的用戶，都得事先充分閱讀 Arch 用戶倉庫，並了解使用這些包會給系統帶來的風險。
- AUR 軟體包的超連結化應該使用 Template:AUR 模板，例如 `{{AUR|package}}`.

#### 非官方軟體倉庫

- 要使用非官方軟體倉庫時，請先將其加入非官方軟體倉庫，然後提供一個連結，示例：
  從 `[[Unofficial user repositories#example|示例]]` 軟體倉庫安裝 packageAUR.
  不要在文章內直接給出啟用軟體倉庫的詳細信息。
- 必須連結到非官方軟體倉庫，而且請儘量使用段落連結：`[[Unofficial User Repositories#example|example]]`.

### Systemd 單元操作

- 不要用systemctl 命令直接進行 start、 restart 或 stop 的操作。正確的說明方法應該是列出需要的單元，以及它們的依賴、衝突關係，描述所要執行的操作。例如：

    要在開機時啟動 GDM，請啟用 `gdm.service`.
  如果模板需要實例化：
    要在無線時自動切換 netctl 配置，啟用一個帶接口名稱的 `netctl-auto@.service` 實例，例如 `netctl-auto@wlan0.service`.
  可以根據上下文調整語句，但是請確保有到 systemd#Using units 文章段落的連結，可以直接引用或通過重定向實現，例如 `[[start]]`, `[[enable]]` or `[[stop]]`.

### Shells

- 除非必要，不要特別指定用戶所用的 shell：撰寫文章內容時請儘量做到與所用 shell 無關。

### 超連結

- 儘可能在該頁面和相關頁面插入彼此的超連結，實現 wiki 脈絡性最大化。
- 像系統調用之類的文章 ArchWiki 卻沒有，大可直接用到維基百科頁面的連結（使用 `zhwp:` 連結前綴）。
- 連結到 wiki 中其它頁面時，不要用完整地址，而是用 wiki 間連結語法：`[[Wiki Article]]`。 wiki 引擎可以跟蹤 wiki 間連結，好讓大家更容易維護。
  更多 wiki 間連結內容參見 Help:編輯#連結。
  - 連結到本頁面段落時，不要隱藏井號，除了簡化額外的格式，井號還明確告訴讀者這是一個到本頁面的連結。
- 請避免使用隱含連結，例如應該使用「參閱 systemd」而不是「參閱 here」。
- 僅在文件存在時才創建連結，不要連結到不存在的文件。
- 除極個別情況外，頁面不能是死亡頁面(沒有任何到其它頁面的連結)或孤立頁面(沒有其它文章連結到它).
- 添加內容時，首先請注意是不是已經有現成的文章描述了該詳細內容，如果有，請插入它的連結而不是再三重複內容。
- 如果上游的現有文檔十分完善且維護程度良好，請只寫 Arch 應特有的內容，並提供到前者文檔的連結。
- 如果某頁面中文維基沒有，請使用 `{{link-en}}` 模板來連結到英文 ArchWiki，以便在中文頁面被創建時自動連結到中文頁面。
- 需要連結到英文 ArchWiki 的時候，請使用連結前綴 `arch:`。

#### 手冊頁面

- 請用 Template:man 引用手冊頁面。

### 代碼規範

- 添加命令或腳本時，請保持代碼風格一致，也可以參考該程序語言的主流編碼規範，並加以遵守。
- 避免使用過時的語言功能和風格，例如推薦使用 `$()` 做腳本命令，而不是````.
- 腳本儘可能短，只需表達需要的信息。儘量使用偽變量而不是真實變量。不要添加參數解析或輸出等無關功能。
- 代碼應該在文本解釋不太清楚的時候使用，如果腳本確實有用但是不是必須，可以考慮使用 gist 引用。
- 明確標明是文件還是目錄/文件夾，比如

  - "檢查目錄 `/sys/firmware/efi` 是否已被創建",不要寫 "檢查 `/sys/firmware/efi` 是否已被創建".
  - "將 .conf 文件放入 `/etc/modules-load.d/`"，而不是 "將 .conf 文件放入 `/etc/modules-load.d`".

- 包含空格的參數應該用引號引用，使用 `cd "foo bar"` 而不是 `cd foo\ bar`.

### 支持的內核版本

- Arch Wiki 支持的最老內核版本為 linux-lts包 和安裝介質中的內核版本。
- 僅可以刪除比兩個版本更老的內核說明或適配信息。

### 不相關內容

- 請不要署名，甚至把文章歸功於自己：ArchWiki 是社區全體的勞動成果，文章的歷史已能足夠說明個人貢獻。
  直接在 wiki 之外的地方專門撰文、並提供連結也不失為署名的好辦法，可以通過 "參見" 段落實現。
- 一般用戶沒有上傳文件的權限，而且不能用圖片。作為替代，可以靠外部連結或者用 ASCII 編輯器，如Asciiflow 等繪製簡單圖形。原因：
  - 維護性: Arch 是滾動更新的，圖片會大幅度地提高維護文章的難度。
  - 必要性: Arch 之道注定了它並不會開發或維護 GUI，所以沒有顯示圖片的必要。
  - 資源性: 允許自行上傳圖片，會需要更多的精力來刪除重複和不合適的圖片。
  - 可行性: 有一些用戶的網速很慢，純文字頁面不光能加快其訪問速度
  - 效率性: 圖片會劇烈消耗伺服器的帶寬和存儲空間。
  - 簡約性: 且界面簡約美觀。

### 拼寫

- 儘量避免不必要的縮寫詞。
- 專有名詞拼寫與項目官方主頁裡面的拼寫保持一致。

### 措辭

- 文章的措辭應做到十分正式、專業且精確。
- 編寫時，請注意不光說怎麼樣，還要回答為什麼？解釋遠勝單純的指導。
- 不要加入個人評論，後者應該放到討論頁面，一般不要用第一人稱。
- 不要說現在，當前等等，請給出具體的時間。
- 編輯內容時，保持和頁面其它內容的一致性，用一樣的人稱描述。
- 在多個選項間提供選擇時，不要感性的建議一個或另一個，請客觀的描述每一個選擇的優點和缺點，讓用戶自行選擇。
- 翻譯頁面時，請儘量避免使用第二人稱代詞「你」或「您」。確實需要使用第二人稱代詞時，如果頁面中現存的翻譯已使用其中的一種，請與其保持一致，如果使用了多種，請考慮統一為其中的一種；如果頁面中沒有使用，則可以自行決定使用哪一種，但請確保在翻譯中保持一致。

## 分類頁面

- 除了根分類外，每個分類都應該有一個父分類。
  根分類是Category:Archive, Category:DeveloperWiki, Category:Languages，Category:Maintenance 和 Category:Sandbox.
- 分類可以屬於多個父分類，只要父分類之間是平級的。
- 避免循環關係: 兩個分類不能互相包含。
- 分類必須放到在分類頁面的頂部。
- 分類不能被重定向，除非是重命名的分類.

## 重定向頁面

- 建議創建縮寫詞到正式文章的重定向，比如創建 ALSA, daemon 或 AIGLX. 重定向可以簡化連結： `[[Advanced Linux Sound Architecture|ALSA]]`, `[[daemons|daemon]]` 或 `[[Xorg#Composite|AIGLX]]`.
- 重定向頁面應該只包含重定向連結，除此之外一無所有。除非：
  - 是歸檔頁面，雖然是重定向，需要屬於分類 Category:Archive.
  - 是重命名分類可以包含一個 Template:Archive 標記.
- 只重定向到 Wiki 內部的頁面，不要重定向到外部頁面。
- 參考 Help:Editing#Redirects

## 用戶頁面

- 用戶這一名字空間中的頁面不能被分類。
- 用戶這一名字空間中的頁面只能連結自「用戶」或者「討論」名字空間中的其他頁面，除非管理員明確同意。

## 一般規則

### 編輯摘要

請閱讀 Wiki 貢獻的基本原則.

### HTML 標籤

- 儘量不要使用 HTML 標籤：儘量使用 wiki 標記和模板，參見 Help:編輯。
- 使用 `<pre>code</pre>` 的地方都改成 `{{bc|code}}`。使用 `<tt>text</tt>` 或 `<code>text</code>` 的地方，都改用 `{{ic|text}}`。
- 特別是避免 HTML 注釋(`<!-- comment -->`): 一般使用 HTML 注釋的文字都可以放到討論頁面。
  可以加入適當的 Help:Template#Article status templates。
- 僅在必要時才使用 `<br>`：要開啟新段落時，用後面的空行實現。
  一個例外是作為一個列表的子項目時，或者在一個模板當中，這時必須使用`<br>`換行。
- 大段代碼可考慮使用 <syntaxhighlight> 標籤進行語法高亮

## 中文排版

- 中文之間不要加空格（即使樣式不同，比如包含連結）
- 儘量避免使用中文斜體

### 中英文混排

- 英文和數字使用半角字符
- 中文文字之間不加空格
- 中文文字與英文、阿拉伯數字及 @ # $ % ^ & * . ( ) 等符號之間加空格
- 中文標點之間不加空格
- 中文標點與前後字符（無論全形或半角）之間不加空格
- 翻譯時，正文的英文常見標點等需要換為中文標點
- 當半角符號 / 表示「或者」之意時，與前後的字符之間均不加空格

## 術語

這篇文章的某些內容需要擴充。

原因：需要規範術語。 (在 Help talk:風格 中討論)

為保持一致的翻譯風格，在翻譯時請遵守以下規範：

- 在正式的規範完成前，請暫時先按照現有的風格翻譯。

相關討論：

- Help_talk:Style_(簡體中文)
- ArchWiki_talk:Translation_Team_(簡體中文)
- Project:社群首頁#Help:風格之關於統一翻譯術語的新新提案

分類：​

- 幫助

說明:風格
新增話題