此 EEP 提供一個樣板或範例範本,用於建立您自己的 Markdown EEP。結合 EEP 1 中的內容指南,這應該可以讓您輕鬆地將您自己的 EEP 符合以下概述的格式。
注意:如果您透過網路閱讀此 EEP,您應該先取得此 EEP 的純文字 原始碼,以便完成以下步驟。請勿使用 HTML 檔案作為您的範本!
此文件基於 PEP 9。
EEP 提交的格式多種多樣,並非所有都符合以下設定的格式指南。請使用此範本,結合 EEP 1 中的內容指南,以確保您的 EEP 提交不會因格式問題而被自動拒絕。
要使用此範本,您必須先決定您的 EEP 將成為流程 (Process) EEP 還是標準追蹤 (Standards Track) EEP。大多數 EEP 都是標準追蹤,因為它們為 Erlang 語言或標準函式庫提出了新功能。如有疑問,請閱讀 EEP 1 以了解詳細資訊,或聯絡 EEP 編輯器 eeps@erlang.org。
一旦您決定了您的 EEP 將是哪種類型,請按照以下指示操作。
複製 此檔案(.md 檔案,而非 HTML!),並執行以下編輯。
將 “EEP 33: “ 標頭取代為 “EEP XXX: “ 以及您的 EEP 標題,也就是說,在您獲得指派的 EEP 編號之前,請使用 ‘XXX’。
變更作者標頭以包含您的姓名,以及可選的電子郵件地址。請務必仔細遵循格式:您的姓名必須首先出現,且不得包含在括號中。您的電子郵件地址可能會在第二個位置出現(或者可以省略),如果出現,則必須以角括號括住。建議您混淆您的電子郵件地址。作者可以是新行分隔的清單(遵循 RFC 2822 行接續慣例),其中第一位作者是 EEP 的擁有者。
如果您的新功能有一個用於討論的郵件清單,請在作者標頭之後立即新增一個 Discussions-To 標頭。如果使用的郵件清單是 erlang-questions@erlang.org,或者討論應該直接發送給您,則不應新增 Discussions-To 標頭。大多數流程 EEP 沒有 Discussions-To 標頭。
將狀態標頭變更為 “草稿 (Draft)”。
對於標準追蹤 EEP,請將類型標頭變更為 “標準追蹤 (Standards Track)”。
對於流程 EEP,請將類型標頭變更為 “流程 (Process)”。
對於標準追蹤 EEP,如果您的功能取決於接受其他目前正在開發的 EEP,請在類型標頭之後立即新增一個 Requires 標頭。其值應該是您的 EEP 所依賴的 EEP 編號。如果您的依賴功能在最終 EEP 中描述,則不要新增此標頭。
將建立時間標頭變更為今天的日期。請務必仔細遵循格式:它必須採用 dd-mmm-yyyy 格式,其中 mmm 是 3 個英文字母的月份縮寫,例如 Jan、Feb、Mar、Apr、May、Jun、Jul、Aug、Sep、Oct、Nov、Dec 之一。
對於標準追蹤 EEP,在建立時間標頭之後,新增一個 Erlang-Version 標頭,並將其值設定為下一個計劃的 Erlang 版本,也就是您的新功能有望首次出現的版本。因此,如果最後一個版本的 Erlang/OTP 是 R13B-3,而您希望將您的新功能加入 28.0,則將版本標頭設定為
Erlang-Version: OTP-28.0
暫時不要動 Post-History;每次您將您的 EEP 張貼到 erlang-questions@erlang.org 時,您都會將日期新增至此標頭。例如,如果您在 2009 年 8 月 14 日和 2009 年 9 月 3 日將您的 EEP 張貼到清單,則 Post-History 標頭看起來會像
Post-History: 14-Aug-2009, 03-Sept-2009
您必須手動新增新日期並將它們簽入。如果您沒有簽入權限,請將您的變更發送給 EEP 編輯器。
如果您的 EEP 使較早的 EEP 過時,則新增一個 Replaces 標頭。此標頭的值是您的新 EEP 所取代的 EEP 編號。僅當較早的 EEP 處於「最終」形式時才新增此標頭,也就是說,其狀態為已接受、最終或已拒絕。如果您要提交一個競爭的想法,則您不會取代較早的開放 EEP。
現在撰寫您的摘要、理由和 EEP 的其他內容,並將所有這些無意義的文字取代為您自己的文字。請務必遵守以下格式指南,特別是關於禁止使用 Tab 字元和縮排要求的規定。
更新您的參考文獻和版權部分。通常,您會將您的 EEP 置於 CC0-1.0-Universal 許可證下,在這種情況下,只需保留「版權」部分即可。或者,您可以使用 開放發佈許可證 或 創用 CC 姓名標示 3.0 許可證,但仍然強烈建議使用 CC0-1.0-Universal。
保留此檔案末尾的小型 Emacs 垃圾,使用它可以獲得良好的模式和字元編碼,並且可以使用例如 fill-paragraph
(預設 [ESC] q
)修正段落。
將您的 EEP 提交發送給 EEP 編輯器 eeps@erlang.org。
請參閱 Markdown 語法以取得一般格式語法。除了這些之外,Markdown EEP 還有以下要求
EEP 的前幾行是用於 EEP 索引產生器剖析和 Markdow 預處理,因此它必須看起來像 此檔案 的前 10 行,並具有特定樣式的水平線和標題 2 標題。您的 EEP 可能有更多或更少的標題行。
EEP 的頂層標題類型為 H1,也就是帶有 ====
底線的標題。每個單字的首字母必須大寫,如書名。
縮寫應全部大寫。
各節內的程式碼範例應縮排 4 個空格。
您必須在所有 H1 標題之前使用三個空行,在所有 H2 標題之前使用兩個空行。
您必須遵守 Emacs 的慣例,在每個句子的末尾新增兩個空格。您應該將段落填滿至第 70 欄,但在任何情況下,您的行都不應超出第 79 欄。如果您的程式碼範例溢出第 79 欄,則您應該重寫它們。
Tab 字元絕對不能出現在文件中。
當在 EEP 的正文中參考外部網頁時,您應該在文字中包含該頁面的標題,並附上指向 URL 的註腳參考。請勿在 EEP 的正文中包含 URL。例如
Refer to the [Erlang Language web site][1] for more details.
:
[1]: https://erlang.dev.org.tw
"Erlang Programming Language"
註腳參考定義應放在文件的倒數第二個位置,緊接在「版權」部分和 Emacs 魔術程式碼之前。請注意,這些參考在 Markdown 產生的 HTML 中是不可見的。
當參考另一個 EEP 時,請使用隱式連結名稱註腳,例如 [EEP 1][]
,在正文中包含 EEP 編號。標題可能會選擇性地出現。註腳本文應包含 EEP 的標題和作者,並且應參考其 URL。
注意:URL 相對於目前的 URL,而建置工具會將其修正為指向 .html 檔案。
範例
Refer to [EEP 1][] for more information about EEP style
:
[EEP 1]: eep-0001.md
"EEP 1, EEP Purpose and Guidelines, Gustafsson"
URL 中的 EEP 編號必須從左側以零填補,使其寬度恰好為 4 個字元,但是文字中的 EEP 編號絕不會填補。
此文件置於公有領域或 CC0-1.0-Universal 許可證下,以較寬鬆者為準。