Browse Source

some characters and punctuations corrected.

pull/1/head
Tan I-kun 14 years ago
parent
commit
c1b4da626f
  1. 36
      syntax.md

36
syntax.md

@ -40,7 +40,7 @@ Markdown: Syntax
Markdown 的目標是實現「易讀易寫」。 Markdown 的目標是實現「易讀易寫」。
不過可讀性是最需要強調的。一份使用 Markdown 格式撰寫的文件應該可以直接以純文字發佈,並且看起來不會充斥著標籤與版面要求語法。Markdown 語法受到一些既有 text-to-HTML 格式的影響,包括 [Setext] [1]、[atx] [2]、[Textile] [3]、[reStructuredText] [4]、[Grutatext] [5] 和 [EtText] [6],然而最大靈感來源其實是純文字的電子郵件格式。 不過它的可讀性是最需要強調的(優點?)。一份使用 Markdown 格式撰寫的文件應該可以直接以純文字發佈,並且看起來不會充斥著標籤與版面要求語法。Markdown 語法受到一些既有 text-to-HTML 格式的影響,包括 [Setext] [1]、[atx] [2]、[Textile] [3]、[reStructuredText] [4]、[Grutatext] [5] 和 [EtText] [6],然而最大靈感來源其實是純文字的電子郵件格式。
[1]: http://docutils.sourceforge.net/mirror/setext.html [1]: http://docutils.sourceforge.net/mirror/setext.html
[2]: http://www.aaronsw.com/2002/atx/ [2]: http://www.aaronsw.com/2002/atx/
@ -55,11 +55,11 @@ Markdown 的目標是實現「易讀易寫」。
Markdown 的語法有個主要的目的:用來作為一種網路內容的*寫作*用語言。 Markdown 的語法有個主要的目的:用來作為一種網路內容的*寫作*用語言。
Markdown 不是要來取代 HTML,甚至也沒有要和它相似,它的語法種類不多,只和 HTML 的一部分有關係,重點 *不是* 要創造一種更容易寫作 HTML 文件的語法,我認為 HTML 已經很容易寫了,Markdown 的重點在讓文件更容易閱讀、編寫,HTML 是一種 *發佈* 的格式,Markdown 是一種 *編寫* 的格式,因此,Markdown 的格式語法只涵蓋純文字可以涵蓋的範圍。 Markdown 不是要來取代 HTML,甚至也沒有要和它相似,它的語法種類不多,只和 HTML 的一部分有關係,重點 *不是* 要創造一種更容易寫作 HTML 文件的語法,我認為 HTML 已經很容易寫了,Markdown 的重點在於,它能讓文件更容易閱讀、編寫。HTML 是一種 *發佈* 的格式,Markdown 是一種 *編寫* 的格式,因此,Markdown 的格式語法只涵蓋純文字可以涵蓋的範圍。
不在 Markdown 涵蓋範圍之外的標籤,都可以直接在文件裡面用 HTML 撰寫。不需要額外標註這是 HTML 或是 Markdown;只要直接加標籤就可以了。 不在 Markdown 涵蓋範圍之外的標籤,都可以直接在文件裡面用 HTML 撰寫。不需要額外標註這是 HTML 或是 Markdown;只要直接加標籤就可以了。
只有區塊元素──比如 `<div>`,`<table>`, `<pre>`, `<p>` 等標籤,必需在前後加上空白,以利與內容區隔。而且這些的開始與結尾標籤,不可以用 tab 或是空白來縮排。Markdown 的產生器有智慧型判斷,可以避免在區塊標籤前後加上沒有必要的 `<p>` 標籤。 只有區塊元素──比如 `<div>`,`<table>`, `<pre>`, `<p>` 等標籤,必需在前後加上空白,以利與內容區隔。而且這些(元素)的開始與結尾標籤,不可以用 tab 或是空白來縮排。Markdown 的產生器有智慧型判斷,可以避免在區塊標籤前後加上沒有必要的 `<p>` 標籤。
舉例來說,在 Markdown 文件裡加上一段 HTML 表格: 舉例來說,在 Markdown 文件裡加上一段 HTML 表格:
@ -73,9 +73,9 @@ Markdown 不是要來取代 HTML,甚至也沒有要和它相似,它的語法
This is another regular paragraph. This is another regular paragraph.
請注意,在 HTML 區塊標籤內,是不會對 Markdown 的語法進行處理的。例如,HTML 區塊內,無法使用 Markdown 形式的 `*強調*` 請注意,在 HTML 區塊標籤內,是不會對 Markdown 的語法進行處理的。例如,HTML 區塊內,無法使用 Markdown 形式的 `*強調*`
HTML 的區段標間如 `<span>`, `<cite>` 或者 `<del>` 則不受限制,可以在 Markdown 的段落、清單或是標題裡任意使用。依照個人習慣,甚至可以不用Markdown 格式,而採用 HTML 標籤來格式化。舉例說明:如果比較喜歡 HTML 的 `<a>``<img>` 標籤,可以直接使用這些標籤,而不用 Markdown 提供的連結或是影像標示語法。 HTML 的區段標籤如 `<span>`、`<cite>`、`<del>` 則不受限制,可以在 Markdown 的段落、清單或是標題裡任意使用。依照個人習慣,甚至可以不用Markdown 格式,而採用 HTML 標籤來格式化。舉例說明:如果比較喜歡 HTML 的 `<a>``<img>` 標籤,可以直接使用這些標籤,而不用 Markdown 提供的連結或是影像標示語法。
HTML 區段標籤和區塊標籤不同,在區段標籤的範圍內, Markdown 的語法是有效的。 HTML 區段標籤和區塊標籤不同,在區段標籤的範圍內, Markdown 的語法是有效的。
@ -83,7 +83,7 @@ HTML 區段標籤和區塊標籤不同,在區段標籤的範圍內, Markdown
在 HTML 文件中,有兩個字元需要特殊處理: `<``&``<` 符號用於起始標籤,`&` 符號則用於標記 HTML 實體,如果你只是想要使用這些符號,你必須要使用實體的形式,像是 `&lt;``&amp;` 在 HTML 文件中,有兩個字元需要特殊處理: `<``&``<` 符號用於起始標籤,`&` 符號則用於標記 HTML 實體,如果你只是想要使用這些符號,你必須要使用實體的形式,像是 `&lt;``&amp;`
`&` 符號其實很讓寫作網路文件的人很困擾,如果你要打 'AT&T' ,你必須要寫成'`AT&amp;T`' ,你還必須要轉換網址內的 `&` 符號,如果你要連結到: `&` 符號其實很讓寫作網路文件的人很困擾,如果你要打「AT&T」 ,你必須要寫成「`AT&amp;T`」 ,還得轉換網址內的 `&` 符號,如果你要連結到:
http://images.google.com/images?num=30&q=larry+bird http://images.google.com/images?num=30&q=larry+bird
@ -91,7 +91,7 @@ HTML 區段標籤和區塊標籤不同,在區段標籤的範圍內, Markdown
http://images.google.com/images?num=30&amp;q=larry+bird http://images.google.com/images?num=30&amp;q=larry+bird
才能放到你的連結標籤的 `href`不用說也知道這很容易忘記,這也可能是數量最多的HTML 標準檢查的錯誤。 才能放到<del>你的</del>連結標籤的 `href`不用說也知道這很容易忘記,這也可能是數量最多的 HTML 標準檢查的錯誤。
Markdown 允許你直接使用這些符號,但是你要小心跳脫字元的使用,如果你是在HTML 實體中使用 `&` 符號的話,它不會被轉換,而在其它情形下,它則會被轉換成 `&amp;` 所以你如果要在文件中插入一個著作權的符號,你可以這樣寫: Markdown 允許你直接使用這些符號,但是你要小心跳脫字元的使用,如果你是在HTML 實體中使用 `&` 符號的話,它不會被轉換,而在其它情形下,它則會被轉換成 `&amp;` 所以你如果要在文件中插入一個著作權的符號,你可以這樣寫:
@ -113,7 +113,7 @@ Markdown 將會把它轉換為:
4 &lt; 5 4 &lt; 5
不過要注意的是,code 範圍內,不論是行內還是區塊, `<``&` 兩個符號都 *一定* 會被轉換成 HTML 實體,這項特性讓你可以很容易用 Markdown 寫 HTML code (和 HTML 相對而言, HTML 語法中,你要把所有的 `<``&` 都轉換為 HTML 實體,才能在 HTML 文件裡面寫出 HTML code。) 不過要注意的是,code 範圍內,不論是行內還是區塊, `<``&` 兩個符號都 *一定* 會被轉換成 HTML 實體,這項特性讓你可以很容易用 Markdown 寫 HTML code (和 HTML 相對而言, HTML 語法中,你要把所有的 `<``&` 都轉換為 HTML 實體,才能在 HTML 文件裡面寫出 HTML code。)
* * * * * *
@ -124,11 +124,11 @@ Markdown 將會把它轉換為:
一個段落是由一個以上連接的行句組成,而一個以上的空行則會切分出不同的段落(空行的定義是顯示上看起來像是空行,就被視為空行,例如有一行只有空白和 tab,那該行也會被視為空行),一般的段落不需要用空白或斷行縮排。 一個段落是由一個以上連接的行句組成,而一個以上的空行則會切分出不同的段落(空行的定義是顯示上看起來像是空行,就被視為空行,例如有一行只有空白和 tab,那該行也會被視為空行),一般的段落不需要用空白或斷行縮排。
「一個以上連接的行句組成」這句其實暗示了 Markdown 允許段落內的強迫斷行,這個特性和其他大部分的 text-to-HTML 格式不一樣(包括 MovableType 的 "Convert Line Breaks" 選項),其它的格式會把每個斷行都轉成 `<br />` 標籤。 「一個以上連接的行句組成」這句其實暗示了 Markdown 允許段落內的強迫斷行,這個特性和其他大部分的 text-to-HTML 格式不一樣(包括 MovableType 的「Convert Line Breaks」選項),其它的格式會把每個斷行都轉成 `<br />` 標籤。
如果你 *真的* 想要插入 `<br />` 標籤的話,在行尾加上兩個以上的空白,然後按 enter。 如果你 *真的* 想要插入 `<br />` 標籤的話,在行尾加上兩個以上的空白,然後按 enter。
是的,這確實讓你要花比較多功夫插入 `<br />` ,但是「每個換行都轉換為 `<br />`」的方法在 Markdown 中並不適合, Markdown email 式的 [區塊引言][bq] 和多段落的[清單][l] 在使用換行來排版的時候,不但更好用,還更好閱讀! 是的,這確實需要花比較多功夫來插入 `<br />` ,但是「每個換行都轉換為 `<br />`」的方法在 Markdown 中並不適合, Markdown email 式的 [區塊引言][bq] 和多段落的[清單][l] 在使用換行來排版的時候,不但更好用,還更好閱讀!
[bq]: #blockquote [bq]: #blockquote
[l]: #list [l]: #list
@ -203,7 +203,7 @@ Markdown 也允許你只在整個段落的第一行最前面加上 `>` :
> >
> return shell_exec("echo $input | $markdown_script"); > return shell_exec("echo $input | $markdown_script");
任何標準的文字編輯器都可以簡單的建立 email 樣式的引言,例如 BBEdit ,你可以選取文字後然後從選單中選擇 *增加引言階層* 任何標準的文字編輯器都能簡單地建立 email 樣式的引言,例如 BBEdit ,你可以選取文字後然後從選單中選擇 *增加引言階層*
<h3 id="list">清單</h3> <h3 id="list">清單</h3>
@ -253,7 +253,7 @@ Markdown 支援有序清單和無序清單。
1. McHale 1. McHale
8. Parish 8. Parish
你都會得到完全一樣的 HTML 輸出。重點在於,你可以讓 Markdown 文件的清單數字和輸出的結果相同,或是你懶一點,你可以完全不用在意數字的正確性。 你都會得到完全相同的 HTML 輸出。重點在於,你可以讓 Markdown 文件的清單數字和輸出的結果相同,或是你懶一點,你可以完全不用在意數字的正確性。
如果你使用懶惰的寫法,建議第一個項目最好還是從 1. 開始,因為 Markdown 未來可能會支援有序清單的 start 屬性。 如果你使用懶惰的寫法,建議第一個項目最好還是從 1. 開始,因為 Markdown 未來可能會支援有序清單的 start 屬性。
@ -347,9 +347,9 @@ Markdown 支援有序清單和無序清單。
<h3 id="precode">程式碼區塊</h3> <h3 id="precode">程式碼區塊</h3>
和程式相關的寫作或是標籤語言原始碼通常會有已經排版好的程式碼區塊,通常這些區塊我們並不希望它一般段落文件的方式去排版,而是照原來的樣子顯示,Markdown 會用 `<pre>``<code>` 標籤來把程式碼區塊包起來。 和程式相關的寫作或是標籤語言原始碼通常會有已經排版好的程式碼區塊,通常這些區塊我們並不希望它一般段落文件的方式去排版,而是照原來的樣子顯示,Markdown 會用 `<pre>``<code>` 標籤來把程式碼區塊包起來。
在 Markdown 中要建立程式碼區塊很簡單,只要簡單的縮排 4 個空白或是 1 個 tab 就可以,例如,下面的輸入: 要在 Markdown 中建立程式碼區塊很簡單,只要簡單地縮排 4 個空白或是 1 個 tab 就可以,例如,下面的輸入:
This is a normal paragraph: This is a normal paragraph:
@ -394,11 +394,11 @@ Markdown 會轉換成:
&lt;/div&gt; &lt;/div&gt;
</code></pre> </code></pre>
程式碼區塊中,一般的 Markdown 語法不會被轉換,像是星號就只會是星號,這表示你可以很容易用 Markdown 語法寫 Markdown 語法相關的文件。 程式碼區塊中,一般的 Markdown 語法不會被轉換,像是星號就只會是星號,這表示你可以很容易用 Markdown 語法寫 Markdown 語法相關的文件。
<h3 id="hr">分隔線</h3> <h3 id="hr">分隔線</h3>
你可以用在一行內用三個或以上的星號、減號、底線來建立一個分隔線,行內不能有其他東西,你也可以在星號中間插入空白,下面每種寫法都可以建立分隔線: 你可以在一行中用三個或以上的星號、減號、底線來建立一個分隔線,行內不能有其他東西,你也可以在星號中間插入空白,下面每種寫法都可以建立分隔線:
* * * * * *
@ -676,7 +676,7 @@ Markdown 會轉成:
在瀏覽器裡面,這段字串會變成一個可以點擊的 "address@example.com" 連結。 在瀏覽器裡面,這段字串會變成一個可以點擊的 "address@example.com" 連結。
(這種作法雖然可以混淆不少的機器人,但並無法全部下來,不過這樣也比什麼都不做好些。無論如何,公開你的信箱終究會引來廣告信件的。) (這種作法雖然可以混淆不少的機器人,但並無法全部下來,不過這樣也比什麼都不做好些。無論如何,公開你的信箱終究會引來廣告信件的。)
<h3 id="backslash">跳脫字元</h3> <h3 id="backslash">跳脫字元</h3>

Loading…
Cancel
Save