標籤：

Madoko-簡潔而強大的學術寫作工具

06-06
Madoko-簡潔而強大的學術寫作工具

來自專欄格知物理

Markdown和Latex代表了寫作語言的兩極：Markdown追求極致的簡潔，只有最少的格式控制；而Latex追求極致的可控，可以實現無線複雜的格式，也對語法有著嚴格的限制。而這兩極之間一直遺留著廣闊的空白地帶，是否有這樣一種寫作語言，在實現精美排版的同時，保持著足夠的簡潔和易用呢？Madoko的便是為了這一目的而生。

為論文寫作而生的工具

The main design goal of Madoko is to enable light-weight creation of high-quality scholarly and industrial documents for the web and print, while maintaining simplicity and focus on plain text readability.

寫作的意涵有兩個方面，一是表達，二是傳達。表達的載體除了文字之外，也可以是圖像、表格、視頻，理想的表達工具應該在儘可能不影響思考過程的情況下記錄思考的結果。傳達即對內容的包裝與展示，對於不同的受眾，展現方式對內容的傳達起到了至關重要的作用。就像同樣是傳達學術知識，教科書和學術論文給人的閱讀感受是很不一樣的。

從這兩個角度出發，我們就能解釋Markdown的成功。它將表達與傳達的過程和二為一，而不是相互干擾。它基於HTML的輸出形式，順應了互聯網時代的閱讀潮流。但是Markdown的輕量化設計決定了它無法滿足更為重型的寫作任務，包括書籍和學術論文。在這些領域，除了專門的排版軟體之外，仍然是Latex的天下。

Latex雖然提供了幾乎無限的靈活性，但是仍然有一些不可忽視的缺點。一，作為一個數十年歷史的老工具，Latex的語法邏輯、使用方式，與現在流行的語言和工具有一定的差別，增大了學習的難度；二，Latex能夠提供高質量的PDF輸出，但是，智能手機普及帶來的移動閱讀需求使得PDF並非手機閱讀的首選格式，類似於Markdown的HTML格式輸出更為合適。

為了解決上面的問題，Madoko誕生了。它提供了一些非常重要的特性：

  • 標籤和文檔內交叉引用
  • 相比Markdown，具有更強自定義特性的表格
  • 支持Bibtex格式的引用文獻，支持自定義引文格式
  • 更完善的數學公式支持
  • 支持TikZ、PSTricks繪圖程序包和SVG矢量圖
  • 支持任意的原生Latex樣式和宏包
  • 支持變成語言的語法高亮
  • 自動編號
  • 自動生成標題頁和目錄頁
  • 支持自定義模塊
  • 支持使用CSS樣式直接定義HTML和Latex輸出樣式
  • 強大的文本替換支持
  • 直接生成演示文稿，支持Web演示或者列印輸出
  • 與常見Markdown擴展兼容

總結起來，Madoko的優點在於三個方面：一，兼容幾乎全部Markdown和Latex功能；二，簡潔而強大的自定義語法；三，同時支持PDF和Web格式輸出，同時支持文檔和演示文稿渲染。

Madoko使用手冊

行內格式語法

// 以下代碼均成對出現在要設置格式的內容兩側- 傾斜：_ or *- 加粗：__ or **- 代碼：`- 下標：~- 上標：^- 刪除線：~~// 引用格式- 鏈接： - 引用鏈接：[Change the text][Google]，[Google]: http://www.google.com - 行內鏈接：[Google](http://www.google.com) - 直接鏈接：<http://www.google.com>- 圖片：![bfly]，[bfly]: images/butterfly-200.png "A Monarch" { width: 100px }- 腳註：[^fn]，[^fn]: 通過縮進使用多行腳註// 特殊格式- /：用於單詞內的加粗或傾斜，本身無意義。- ：用於強制換行。

塊格式語法

// 常用- 標題：和Markdown一樣，使用#個數指示標題層級// 標籤-#Label- 標題：### A named heading { #myheading }- 公式：In Equation [#euler]，~ Equation { #euler; caption:"Eulers formula" } ~ （對公式的引用會自動編號）- 自定義編號順序：下面的代碼使用 - 清除了默認屬性 ### An unnumbered heading { - } ### A labeled heading { -; id: myheading1; label: "my label" } Lets refer to Section [#myheading1].- 圖片： Figure [#fig-monarch] shows how to put an image in a figure. ~ Figure { #fig-monarch; caption: "A Monarch butterfly." } The ![monarch] image. ~ // 列表 - 無序列表：使用*，+，-作為標記均可，標記對應不同的符號。但是列表開頭需要空一行，標記後需要空一格。 - 有序列表：使用數字+點或者空格的形式。數字的順序不重要，都是從第一個數字開始依次加一。 - 名稱列表：下面兩種格式均可 * Abstract syntax : The conceptual structure (illustrated by the pictures) is called the abstract syntax of the language. Abstract syntax ~ The conceptual structure (illustrated by the pictures) is called the abstract syntax of the language. // 塊引用 - 和Markdown一樣，使用 > 插入塊引用。

表格

表格是一個Markdown和Latex都不盡如人意的地方。Markdown的表格過於簡潔，而Latex的表格語法繁瑣。Madoko發展了Markdown的表格標記，力求以簡單的方式來實現複雜的表格。其主要語法格式如下：

  • 每一行的開頭和結尾以及每一列之間都必須以（|）或者（+）分隔。
  • 橫跨多列的單元格可以使用多個（|）分隔。
  • 表格可以有一個或多個標題行。
  • 表格必須有一個列分隔行，在這個分隔行內，單元格中的內容使用（-）或者（~）。

// 一個表格的例子| id | name | description | price ||:-----|:----------:|----------------------------|--------:|| 1 | gizmo | Takes care of doohickies | 1.99 || 2 | doodad | Collects *gizmos* | 23.80 || 10 | dojigger | Foo | 102.98 || 1024 | Self-explanatory, no? || 0.99 |

列分隔行的格式說明：

  • （:）的位置用來指定對應列的對齊方式，左右分別對應左對齊和右對齊，兩側均有對應居中對齊。
  • 如果列之間用（+）號分隔，列之間會出現豎線分隔。（+）後面不能有空格。
  • 如果單元格內使用（-），則出現橫線，（~）不出現線條。（=）則出現雙橫線。

// 一個包含各種橫豎分割線的複雜表格| ------ | ----------------- | ------------------- | ------ || id | name | description | price |+--------+-------------------+:-------------------:+~~~~~~~:+| 1 | gizmo |||| | -----------------------------------------------|||| 2 | doodad | Collect *gizmos* | 23.80 || ====== | ----------------- | =================== |--------|| 1024 | thingamabob | Self-explanatory | 0.99 || ------ | ----------------- | | ------ |

對於可能橫跨多頁的長表格，我們需要在表格後設置breakable屬性為true。

// 我們可以通過添加屬性標籤直接指定列的寬度等屬性。+:----:|---{width:2cm}--+:-----{width:60%}--------:+-------:+| centered gizmos || Take care of doo hickies | 1.99 || 2 | doodad | Collects *gizmos* | 23.80 || 10 | dojigger | Foo | 102.98 || 1024 | thingabob | Self-explanatory, no? | 0.99 ||------|----------------|--------------------------|--------|// 我們可以使用類似的方式為單元格著色// 除此之外，我們也可以在表格後加上複雜的樣式控制// 前綴：tr-，行；col-，列；tbody-，表格體；thead，表格頭；// even-，偶數行；odd-，奇數行；last-，最後一行；n-，第n行；| ---- | -------------- | ------------------------ | ------ || id | name | description | price |+:----:+--{background-color:Silver}--+:-----------:|-------:+| centered gizmos || Take care of doo hickies | 1.99 || 2 | doodad | Collects *gizmos* | 23.80 || 10 | dojigger | Foo | 102.98 || 1024 | thingabob | Self-explanatory, no? | 0.99 ||------|----------------|--------------------------|--------|{ tbody-tr-odd-background-color:Gainsboro; tr-even-background-color:Floralwhite }// 為了方面的畫出樣式美觀的表格，我們可以直接使用預定義的booktable樣式| --------------- | ----------- | --------------- || Item || || /------------- | ----------- | || Animal | Description | &ensp;Price ($) || :-------------- | ----------- | --------------: || Gnat | per gram | 13.65 || | each | 0.01 || Gnu | stuffed | 92.50 || Emu | stuffed | 33.33 || Armadillo&ensp; | frozen | 8.99 || --------------- | ----------- | --------------- |{ .booktable }// 關於上面代碼的一些說明：/符號不會產生實際作用，它的目的是防止這一行被識別為列分隔行。

代碼

插入代碼塊最簡單的方式是直接將代碼縮進四個空格。或者使用和Markdown類似的方式：

~~~markdown

<a href="foo.com">a link in html</a>

~~~

使用上面的方式，Madoko會自動進行語法高亮，使用Latex輸出的PDF也會保留高亮樣式。

對於代碼塊來說，非等寬字體會顯得更美觀，但是對齊會出錯，Madoko提供了一個（.pretty）屬性使得代碼在美觀的同時，保持對齊。

~~~haskell

``` Haskell { .pretty }

data Exp = Number Int

| Add Exp Exp

| Subtract Exp Exp

| Multiply Exp Exp

| Divide Exp Exp

| Variable String -- added

deriving (Eq)

~~~Madoko也支持對語法高亮的自定義設置：```css.token.identifier { font-style: italic }.token.string.escape { color: gray }// 對於pretty環境中的代碼，可以結合下述代碼使用：@if tex { .ptoken.keyword { font-family: sans-serif }}// 我們還可以擴展現有的高亮語法，添加新的需要高亮的關鍵字，詳見Madoko參考手冊。

矢量圖

Madoko可以整合任意的Latex代碼和宏包，自然也包括Latex中常用的繪圖宏包Tikz和PSTricks。

// 先導入宏包Package: pstricksPackage: pst-plot// 使用Snippet環境插入代碼~ Center {padding:1ex} ~~ Snippetpsset{unit=2cm} egin{pspicture*}(-0.5,-1.5)(4,2) psgrid[subgriddiv=5,gridcolor=black!20% ,gridlabels=0pt](1,0)(3,1.2) psaxes{->}(0,0)(0,-1)(3.2,1.5) uput[0](3.2,0){$x$}uput[90](0,1.5){$f(x)$} pscircle*[linecolor=red](! Euler 1){3pt} psline[linecolor=red,linestylex=dashed]% (! Euler 0)(! Euler 1) psline[linecolor=red,linewidth_=0.2pt,arrowscale=2]% {->}(! Euler 1)(0, 1) uput[-90](! Euler 0){color{red}$e$} pscircle*[linecolor=blue](1,0){3pt} psplot[linewidth_=1pt]{0.2}{3}{ x ln }
put(1.6,-0.5){color{blue}fbox{$f(x)=ln(x)$}} end{pspicture*}~~~ // 使用Tikz宏包時，使用下面的代碼Package : tikzTex Header : usetikzlibrary{decorations.pathreplacing% ,decorations.pathmorphing}

Madoko渲染Latex代碼時默認使用xelatex，但是有的時候xelatex對圖片的渲染會出錯，我們可以使用命令：Math Latex Full: pdflatex，指定使用pdflatex來渲染。

公式

Madoko中的公式繼承了Latex的語法，同時做了一些修改，以保持和其他Madoko語法的一致性。

Madoko在將文檔渲染成HTML時，對公式有兩種渲染方式：

  • 靜態，static：Madoko使用Latex將公式渲染成圖片。好處是載入速度快，壞處是本地使用時需要先安裝Texlive。
  • 動態，dynamic：Madoko使用Mathjax實時渲染，好處是不需要預先安裝Latex，壞處是公式很多的時候速度慢，並且有些命令不支持。可以在文檔開頭添加：Math Mode: mathjax 來開啟這一命令。

A famous equation is $E = mc^2$, but another famous one is:~ Equation {#eq-gaussian; caption:"The Gaussian equation" } int_{-infty}^infty e^{-a x^2} d x = sqrt{frac{pi}{a}} ~// 行內公式如果太長，可以使用Latex注釋換行A long $E = %continue on next line mc^2$ formula.// 如果不想給公式自動編號，需要使用Math而不是Equation~ MathPleft(A=2;middle|frac{A^2}{B}>4
ight)~// 對齊公式~ Equation { #eq-alignment; caption:"Alignment example" }egin{aligned} f(x) &= a x^2+b x +c & g(x) &= d x^3 \ f(x) &= 2 a x +b & g(x) &= 3 d x^2end{aligned}~// 排列公式也可以通過自定義規則來簡化語法Aligned { replace:"~Math&nl;egin{aligned}&nl;&source;&nl;end{aligned}&nl;~" }~ Alignedf(x) &= (x+a)(x+b) \&= x^2 + (a+b)x + ab~// 如果公式用到了其他宏包，我們只需要提前將其導入即可Package: amscd~ Equation { #eq-commuting; caption:"A commuting diagram" }egin{CD}S^{{mathcal{W}}_Lambda}otimes T @>j>> T\@VVV @VV{P}V\(Sotimes T)/I @= (Z otimes T)/Jend{CD}~// 對於數學公式非常多的文檔，我們可以預定義一些簡化命令~ MathDefs
ewcommand{infer}[3]{#1 vdash #2,:#3}~ We infer $infer{Gamma}{e}{ au}$ for such expression $e$.// 通常我們把這些預定義命令放到單獨的tex文件中，再導入進來~ MathDefs[INCLUDE="mathdefs.tex"]~

預定義樣式的公式：Latex的數學公式環境會賦予數學公式統一的樣式，但是某些情況下我們需要對不同的部分賦予不同的樣式，比如：計算機科學書籍中描述演算法時常出現的代碼和公式混雜的情況。Madoko提供了MathPre代碼塊來解決這一問題。它具有如下特點：

  • 保留了空格，間距、縮進和換行均使用數學樣式；
  • 由字母和數字組成的名稱看起來會更緊湊；
  • 名稱後面帶的數字自動變成下標；
  • @開頭的名稱變成了mathkw格式；
  • #開頭的名稱樣式不變；
  • 可以使用&來對齊文本；

~ MathPre@function sqr_pi( num :int ) { @return (num { imes} num imes{} pi)} ~// 下面的代碼可以將所有數學公式樣式替換為MathPre樣式.math-inline,.math-display { input: mathpre;}

目錄

生成目錄非常簡單，除了生成標題目錄之外，我們還可以生成圖片、公式、表格等其它內容的目錄。也可以自定義目錄深度和樣式。

// 一般目錄，Toc Depth屬性指定深度[TOC]// 圖片目錄[TOC=figures]

引用文獻

Madoko使用 BibTeX 和 Citation Style Language](citationstyles.org/) 來處理參考文獻。

// 首先導入參考文獻所在的bib文件Bib: ../mybib1// Bib文件中的參考條目有一個關鍵字@BOOK{ Knuth:TeX, author = "Knuth, Donald E.", title = "The {TeX} book", publisher= "Addison-Wesley", year = 1984}// 通過關鍵字我們可以施加引用Read more [The book @Knuth:TeX; @Lamport:LaTeX (chapter 4)]. // 在需要放置引用文獻章節的地方使用下面代碼， 可以通過設定name-references屬性指定該章節標題 [BIB]

設置參考文獻樣式時，Madoko可以同時使用bst格式和csl格式文件。csl格式的好處在於，網路上有很多現成的文件提供。bst格式的參考文獻樣式可以在這裡找到。

// 使用下面的代碼導入csl文件Csl Style: Taylor-and-Francis-Chicago-Author-Date// 使用bst文件的方式Bib Style: plainnat// 正文中的引用樣式一般有引用樣式文件定義，我們也可以自己指定。Cite Style: natural// 可選的樣式包括：natural, sqnatural, textual, super, and numeric

除了基本的展示功能之外，Madoko對參考文獻還提供了一些有用的輔助功能。一是在HTML中參考文獻的引用位置顯示一個提示功能，二是在具體參考文獻條目後面加一個搜索按鈕，如果要在生成的PDF中也顯示上述兩個功能，需要加額外的命令：

~a: .tex-tooltip

自定義代碼塊

Madoko預定義了一些有用的代碼塊，除了之前涉及到的一些之外，還有：

  • Bibitem, Bibliography ：單獨輸入參考文獻條目
  • Note, Remark, Proof
  • Abstract ：定義摘要
  • Framed ：帶有實線邊框的塊
  • Center ：使內容居中
  • Columns, Column ：column放置在columns中，使頁面內容分幾列放置
  • TexRaw ：直接傳遞給Tex引擎的代碼
  • HtmlRaw ：直接傳遞給HTML引擎的代碼
  • TexOnly ：只會傳遞給Tex引擎的代碼
  • HtmlOnly ：只會傳遞給HTML引擎的代碼
  • Section：主要使用在演示文稿模式中
  • Article, Aside, Nav ：變成對應的HTML5標籤
  • Theorem, Lemma, Proposition, Corollary, Example, Definition ：均單獨編號，帶有對應的加粗名稱，可以使用caption屬性指定標題

另外還有一些特殊的塊元素：

  • [TITLE] ：生成標題
  • [TOC], [TOC=name] ：生成目錄
  • [FOOTNOTES] ：生成腳註
  • [INCLUDE=file] ：直接展開成對應文件內容，在其它內容處理之前最先被處理。
  • [BIB] ：導入bib文件

導入其它文件

// 語法格式[INCLUDE(=file)?(:range)?] // 指定文件名和行的範圍[INCLUDE=foo.hs:10-18][INCLUDE=foo.hs:20] // 導入20行之後的所有行// 通過片段名導入// 對於下面的文件-- BEGIN:Var-- BEGIN:Syntax-- END:Syntax-- END:Var --BEGIN:Eval--END:Eval// 我們可以使用下面的代碼導入指定片段[INCLUDE=foo.hs:Var][INCLUDE=foo.hs:Eval]// 為了省略文件名，我們可以先導入文件，而後可以直接輸入片段名[INCLUDE=foo.hs:0][INCLUDE:Syntax]

元數據和樣式設置

元數據

元數據必須出現在文檔的最一開始，用來指定標題、作者等基本信息和設置格式。

Title : An overview of MadokoAuthor : Daan LeijenAffiliation : Microsoft ResearchEmail : daan@microsoft.comLogo : FalseEmbed : False

完整的Madoko預定義關鍵字列表參見官網參考文檔。

主要語法特性：

// 條件格式@if html { Logo: True}@if not tex { h2 { color: blue }}// Entity實體The title of this document is "&title;".And this section has label &sec-entity;.Standard entities are looked up last &Delta;&hArr;&delta;.

樣式設置

Madoko使用css的語法來進行樣式設置，並提供了一些簡化語法。

{ key: value; key: value }id:name可以簡化為#id；class:classnames可以簡化為.class；This is a paragraph in small-caps.{ font-variant: small-caps} * {color: navy} This is a mylist * in italics{ .mylist; font-style: italic }

Madoko支持直接導入css文件，在輸出為pdf時，後台會將很多常見css命令轉化為對應的Latex命令，以保持PDF和HTML的格式一致性，其它的會被忽略。


推薦閱讀：

※外國寫論文的文獻標註，太講究！Harvard Referencing全科普！
※【編輯課堂】 編輯是這樣審稿的！
※CECU專訪：解讀邱漢橋「北勢南氣」學術體系
※有沒有比sci-hub更好用的論文下載平台？
※道不同，不相為謀——不當編輯也要推動開放獲取

TAG:學術論文 | 英文論文 | 論文 |