說明:風格

出自 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:i18n 和 Wikipedia: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 或其它權限獲取工具(例如 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 User Repository (简体中文)|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:。

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

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

  • 添加命令或腳本時，請保持代碼風格一致，也可以參考該程序語言的主流編碼規範，並加以遵守。
  • 避免使用過時的語言功能和風格，例如推薦使用 $() 做腳本命令，而不是``.
  • 腳本儘可能短，只需表達需要的信息。儘量使用 偽變量 而不是真實變量。不要添加參數解析或輸出等無關功能。
  • 代碼應該在文本解釋不太清楚的時候使用，如果腳本確實有用但是不是必須，可以考慮使用 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, daemon 或 AIGLX. 重定向可以簡化連結： [[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:風格 中討論)

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

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

相關討論：

取自「https://wiki.archlinuxcn.org/wzh/index.php?title=Help:风格&oldid=24323」