說明:風格

出自 Arch Linux 中文维基

這些風格約定鼓勵簡約、有條理和視覺一致的文章。請在編輯 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:i18nWikipedia:Help:Interlanguage links.

文章狀態模板[編輯 | 編輯原始碼]

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

相關文章[編輯 | 編輯原始碼]

前言或介紹[編輯 | 編輯原始碼]

  • 描述文章的話題。
    不要自己給軟件下評論,一般可以訪問項目主頁,使用作者自己的描述。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 或其它權限獲取工具(例如 gksukdesu)。
  • 應該避免# sudo command,唯一的例外是用sudo-u選項修改用戶,這時提示符可以與其它命令一致,默認使用$
  • 不要在一行命令的代碼框裡添加注釋,例如# pacman -S foo #Install package foo就不好
  • 代碼行不要過長,請儘量換行。

鍵盤按鍵[編輯 | 編輯原始碼]

  • 表示按鍵的標準方法是使用 Template:ic 模板。
  • 字母鍵應該小寫:a. 大寫字母用 Shift+a,不要使用 Shift+AA
  • 表示按鍵組合的正確方法是使用 + 號連接,不要增加額外空格,在一個模板中包含多個按鍵:Ctrl+c.
    下面格式都應該避免使用:Ctrl + c, Ctrl+c, Ctrl-c
  • 特殊鍵的標準名稱:
    • Shift (不要用 SHIFT)
    • Ctrl (不要用 CTRLControl)
    • Alt (不要用 ALT)
    • Super (不要用 WindowsMod)
    • Enter (不要用 ENTERReturn)
    • Esc (不要用 ESCEscape)
    • Space (不要用 SPACE)
    • Backspace
    • Tab
    • Ins (不要用 INSInsert)
    • Del (不要用 DELDelete)
    • Print Screen
    • Up (不要使用 Up Arrow) – 其它方向鍵類似
    • PageUp
    • PageDown
    • Fn (不要使用 FNfn) – 不同筆記本上的功能按鍵請參考 這裡

注意, 警告, 技巧[編輯 | 編輯原始碼]

  • 注意 應該用在用戶預料不到的地方。包括與文章關係不大的細節知識、軟件包名稱變動等。
    也可以用來強調容易被用戶忽略的地方。
  • 警告 用來指出需要特別警惕的地方,比如不可逆轉的修改、損害系統的可能性等。警告應該直接指出最壞的情況,並給出相應措施。不要濫用警告,如果不確定的時候,用注意即可。
  • 提示 用來給出一個可能會相當有用的小技巧,一般不是必須的,省略也無妨。
  • 如果多個注意、警告、技巧連用,最好組合到單一模板中,除非彼此毫無相干。例如:
提示:
  • 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 packagepacman -Syu package 孰好孰壞的無謂爭論。同理,也不要引入 pacman 前端或圖形界面等。
    相反,請像這樣簡單地示範:安裝說明應該使用: [[pacman (简体中文)|安装]] 软件包 {{Pkg|package}}
  • 如果安裝的是一組軟件包,則使用 : 安裝 軟件組 foobar包組.
  • 必須要用 Template:Pkg/和Template:Grp 模板進行格式化,例如{{Pkg|package}}.
  • 不要特意指出軟件包是在 [core]、[extra] 或 [community] 中的哪一個倉庫,因為一個軟件包可能會在不同倉庫之間轉移。此外如果軟件包位於 [multilib] 倉庫,請這樣示範:
    安裝官方軟件倉庫package 時,需要事先開啟 multilib 倉庫。

AUR 軟件包[編輯 | 編輯原始碼]

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

非官方軟件倉庫[編輯 | 編輯原始碼]

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

Systemd 單元操作[編輯 | 編輯原始碼]

  • 不要用systemctl 命令直接進行 startrestartstop 的操作。正確的說明方法應該是列出需要的單元,以及它們的依賴、衝突關係,描述所要執行的操作。例如:
要在開機時啟動 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:

手冊頁面[編輯 | 編輯原始碼]

代碼規範[編輯 | 編輯原始碼]

  • 添加命令或腳本時,請保持代碼風格一致,也可以參考該程序語言的主流編碼規範,並加以遵守。
  • 避免使用過時的語言功能和風格,例如推薦使用 $() 做腳本命令,而不是``.
  • 腳本儘可能短,只需表達需要的信息。儘量使用 偽變量 而不是真實變量。不要添加參數解析或輸出等無關功能。
  • 代碼應該在文本解釋不太清楚的時候使用,如果腳本確實有用但是不是必須,可以考慮使用 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,所以沒有顯示圖片的必要。
    • 資源性: 允許自行上傳圖片,會需要更多的精力來刪除重複和不合適的圖片。
    • 可行性: 有一些用戶的網速很慢,純文字頁面不光能加快其訪問速度
    • 效率性: 圖片會劇烈消耗服務器的帶寬和存儲空間。
    • 簡約性: 且界面簡約美觀。

拼寫[編輯 | 編輯原始碼]

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

措辭[編輯 | 編輯原始碼]

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

分類頁面[編輯 | 編輯原始碼]

重定向頁面[編輯 | 編輯原始碼]

  • 建議創建縮寫詞到正式文章的重定向,比如創建 ALSA, daemonAIGLX. 重定向可以簡化鏈接: [[Advanced Linux Sound Architecture|ALSA]], [[daemons|daemon]][[Xorg#Composite|AIGLX]].
  • 重定向頁面應該只包含重定向鏈接,除此之外一無所有。除非:
  • 只重定向到 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:風格 中討論)

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

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

相關討論: