R + markdown简介

markdown是什么

markdown是由John Gruber提出的一种书写格式,于2004年12月推出它的1.0.1版本。到现在为止这个版本也一直没有更新过,也就是说这是一个基本稳定的版本。作者的博客地址在这里,其中包含了Markdown的语法说明,这个是英文版的。

在说明markdown是什么之前,先看一个markdown文件的实例:


# 灵根育孕源流出 心性修持大道生

**诗曰**

>混沌未分天地乱,茫茫渺渺无人见。
自从盘古破鸿蒙,开辟从兹清浊辨。
覆载群生仰至仁,发明万物皆成善。
欲知造化会元功,须看《西游释厄传》。

盖闻天地之数,有十二万九千六百岁为一元。将一元分为十二会,乃子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥之十二支也。每会该一万八百岁。且就一日而论:子时得阳气而丑则鸡鸣,寅不通光而卯则日出,辰时食后而巳则挨排,

这段markdown文档生成的效果如下:



由此可见,markdown的源码和最终输出的结果比起来,除了格式不一样外,只是多出了一些标点符号。而这些标点符号就是markdown控制格式的方法。

如果说markdown有什么特征,那么markdown最大的特征就是简单。与微软的word相比,不知简单了多少倍,简直不是一个数量级的。标准的markdown中只是定义了10多种格式,并且格式的定义非常容易记忆,以至于你根本不需要化专门的时间来学习它。

那么有人会问,它会不会太简单了?的确有时候它太简单了,比如写作一些科技文献的时候,它提供的基本格式就不够用了。在这种情况下,出现了markdown的几种扩展,可以让人们来方便的处理这些格式。目前比较流行的扩展有pandoc扩展,其次是GitHub扩展。其中GitHub的扩展主要是用于在GutHub的网站上使用。由于GitHub用户很多,所以这个扩展也很流行。而pandoc是一个强大的格式转换工具,基本上支持各类常见格式之间的转换,其中就包括有markdown。而markdown的格式超级简单,这就使得人们能够用超级简单的markdown来生成看起来复杂的其他格式,比如word、html、pdf等。这样,因为pandoc使得人们能够使用markdown来生成doc和pdf文档,因此受到广泛的欢迎。随着pandoc的流行,出现了很多以pandoc为基础的外围工具,以此来方便人们对pandoc的使用,比如在R语言中的几个软件包Rmarkdown,knitr等就使用pandoc作为底层的支持来实现从markdown到各种其他格式的转换。

另外关于这些基于pandoc的扩展,有些已经实现的非常先进,可以帮助作者完成不少以前需要手动完成的工作,比如自动生成文档的部分内容,自动插入图片等等。

基于以上这些原因,本书中也将以pandoc扩展为主要的关注点。

R语言

本书的目的是为了讲解markdown,为什么还要提到R语言?R语言是什么东西,跟markdown有什么关系呢?

如果你使用markdown只是进行文学类创作,比如写写小说什么的,那么你根本不需要使用到markdown的扩展就可以工作了。在这种情况下,你可以不去考虑makrdown扩展以及R的问题。

如果你要使用markdown进行科技文献,科技书籍的写作,那么如果你了解并能够使用R语言,将会对你的工作效率有巨大的提升。

那么R语言是什么?R语言是一种针对统计分析和数据科学的开源的统计语言,它是一种基于向量的高级函数式编程语言。近年来,由于大数据的兴起,越来越多的人开始关注R语言。每天都有大量的志愿者为R软件的发展贡献代码。因此R本身也是一个迅速发展的语言。

由于pandoc的兴起,R社区的开发者发现了这个工具给写作带来的巨大便利,因此开发了一些以pandoc为基础的软件包,其代表是Rmarkdown和knitr。这些软件包让文档或书籍的作者可以方便的从markdown文件动态的生成最终的文档。这些工具使得写作的效率大幅提高。这也是我们将要关注的内容。

rmarkdown和knitr

前面介绍提到了rmarkdown和knitr是R的软件包,它们把能够在markdown中嵌入R语言,并且执行其中的R代码,而R代码的输出可以作为文档的一部分。甚至R代码生成的图片也可以自动嵌入到markdown文件中。

Rmarkdown + knitr可以执行R语言代码的这个功能使得markdown如虎添翼,具有非凡的表现力和极高的效率。含有可执行R代码的markdown文件有一个专门的扩展名,即rmd

下面我们看一个rmarkdown的实例:


下面的代码将会画出100个正态分布的散点图,画出的图会变成文件的插图:

```{.r echo=FALSE,fig.path="./rfigures/p6172-"}
plot(rnorm(100))
```

实际生成的内容如下:

这里可以看到新生成的图片已经被插入文档中了,这样每次重新生成文档,文档的内容都会被更新,这样只要文档中的R代码没有错,该文档将永远保持使用最新的结果,你不需要为每次的代码改动来重新粘贴代码生成的结果。这将为您节省宝贵的时间。

为什么要使用markdown

从上面的介绍可以看出,markdown最大的特征就是简单,其次是基于markdown的各种外围工具使得利用markdown进行创作非常高效。这个高效体现在

  1. 语法简单,作者基本上无需关心排版的问题,只要专心写作就可以了。
  2. 对于科技文献的写作,R软件提供了文章动态生成的过程。使得作者不必要手动去拷贝粘贴代码的结果或者生成的图片等。
  3. 易于修改,因为文档可以从markdown动态的生成。作者只需要修改markdown文件,然后就立刻能够看到最终的文章结果。

还有一个使用markdown的重要原因是,它是免费的,markdown只是一种格式定义,你可以使用你喜欢的编辑器来编写markdown文件,编写完的markdown文件可以通过免费的工具来转换成html、pdf、docx等。因此使用markdown你不必要花钱去使用某软的付费系统和付费软件。

怎样使用markdown

markdown文件是通常的文本文件,你使用vi,emacs或者windows下的记事本都可以编写markdown。写好的markdown如果上传到GitHub,那么markdown文件会自动被转换成html显示出来。在本地可以通过perl,R或者其他的工具比如pandoc来将markdown文件转为html或PDF以及docx。

  • perl,在John Gruber的网站,提供了一个Markdown.pl,这是标准的markdown解析工具,它可以把markdown转为html

    使用方法是: ./Markdown.pl ./about.md

    这样将会把md文件转换为html,输出在标准输出。

    因为前面提到的,标准的markdown的功能有限,比如没有表格的支持等,所以一般使用中,不推荐直接使用这个perl脚本进行格式转换。

  • pandoc,你也可以使用pandoc直接来将md文件转换为html

    使用方法: pandoc -f markdown -t html -o ./about.html ./about.md

    pandoc也可以把md转换为pdf文件,使用方法为 pandoc -f markdown -t latex -o ./about.pdf ./about.md

    pandoc可以支持多种类型的转换,通常你需要熟悉pandoc的各种参数,你可以手动敲这些命令。不过使用R的包会使这个过程简化。

  • R ,以下是利用R将当前目录下的about.md文件转换为about.html文档的方法:

    Rscript -e “rmarkdown::render(‘./about.md’)”

    当然,为了上面的代码能够正确运行,你需要在安装R以后,安装rmarkdown这个包,这个包的安装方法是,在R的命令行键入install.packages("rmarkdown")

    如果要生成pdf格式的文件,你需要在render后面指定更多的参数。这些后面再讨论。

怎样使用rmarkdown

那么rmarkdown的文件怎么编译呢,rmarkdown的文件,也就是.rmd文件就只能在R上编译(转换)了。编译的方法和编译markdown文件一样,只是这时候,文件的扩展名由md变成了rmd,这时候,rmd文件中的r代码就会被处理了,命令行如下:

Rscript -e "rmarkdown::render('./about.rmd')"

在真正使用markdown进行创作之前,你还需要做一些准备工作。如果你比较着急的想试试,可以直接跳到后面一章去看看markdown的基础语法。

准备工作

在真正使用markdown之前,我们还需要一些准备工作。这里的准备工作主要包括两个部分,一是选择一个编辑器,再就是选择一个编译工具,我们这里选择R语言。当然你也可以选择perl,但是我不推荐。

编辑器

Linux下的同学都应该有自己趁手的工具,vim或者emacs随便找一个就可以了。这些工具下面应该还有些支持markdown语法的插件。对于vim来说,有一款插件叫vim-markdown。这个插件只是提供了语法的高亮显示。如下图所示

在Linux下使用VIM编辑markdown文件实际上是很不方便的,根本原因在于中文的切换问题。你在输入中文的时候,如果要键入一个vim的命令,需要退出中文输入,或者在输入法上输入命令然后直接键入回车键,这是很不方便的。因此,我实际的使用过程中,并不怎么使用vim。而是使用了另一款编辑器,即gedit。这个编辑器中集成了markdown语法的高亮显示。使用起来也比较直接。中文输入的不方便是我这个vim粉放弃vim的根本原因。不过除了markdown以外的其他的编辑基本在vim中进行。

另外现在有一些可以实时看到编辑效果的编辑器,比如Windows下的MarkdownPad, Mac下的Mou,Linux下的ReText等编辑器,大家也可以自己去找一下。选择一个适合自己的编辑器就好了。

pandoc

如前所述,pandoc是一个格式转换工具,可以支持常见文档格式之间的相互转换。它支持很多的格式,使用pandoc --help可以看到它所支持的所有格式,这里列出其支持的格式供参考:

xuyang@ubuntu15:~/blog$ pandoc --help
pandoc [OPTIONS] [FILES]
Input formats:  docbook, docx, epub, haddock, html, json, latex, markdown,
                markdown_github, markdown_mmd, markdown_phpextra,
                markdown_strict, mediawiki, native, opml, org, rst, t2t,
                textile, twiki
Output formats: asciidoc, beamer, context, docbook, docx, dokuwiki, dzslides,
                epub, epub3, fb2, haddock, html, html5, icml, json, latex, man,
                markdown, markdown_github, markdown_mmd, markdown_phpextra,
                markdown_strict, mediawiki, native, odt, opendocument, opml,
                org, pdf*, plain, revealjs, rst, rtf, s5, slideous, slidy,
                texinfo, textile
                [*for pdf output, use latex or beamer and -o FILENAME.pdf]

另外,pandoc还支持很多变成语言的语法高亮显示,如下所示

xuyang@ubuntu15:~/blog$ pandoc --version
pandoc 1.13.2.1
Compiled with texmath 0.8.2.2, highlighting-kate 0.5.12.
Syntax highlighting is supported for the following languages:
    abc, actionscript, ada, agda, apache, asn1, asp, awk, bash, bibtex, boo, c,
    changelog, clojure, cmake, coffee, coldfusion, commonlisp, cpp, cs, css,
    curry, d, diff, djangotemplate, dockerfile, dot, doxygen, doxygenlua, dtd,
    eiffel, email, erlang, fasm, fortran, fsharp, gcc, glsl, gnuassembler, go,
    haskell, haxe, html, idris, ini, isocpp, java, javadoc, javascript, json,
    jsp, julia, latex, lex, lilypond, literatecurry, literatehaskell, lua, m4,
    makefile, mandoc, markdown, mathematica, matlab, maxima, mediawiki,
    metafont, mips, modelines, modula2, modula3, monobasic, nasm, noweb,
    objectivec, objectivecpp, ocaml, octave, opencl, pascal, perl, php, pike,
    postscript, prolog, pure, python, r, relaxng, relaxngcompact, rest, rhtml,
    roff, ruby, rust, scala, scheme, sci, sed, sgml, sql, sqlmysql,
    sqlpostgresql, tcl, tcsh, texinfo, verilog, vhdl, xml, xorg, xslt, xul,
    yacc, yaml, zsh
Default user data directory: /home/xuyang/.pandoc
Copyright (C) 2006-2014 John MacFarlane
Web:  http://johnmacfarlane.net/pandoc
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

关于pandoc的安装:

  • ubuntu 15.10 sudo apt-get install pandoc
  • ubuntu 15.10以前的版本 在15.10以前的版本,ubuntu缺省安装的pandoc版本太低,以至于Rmarkdown拒绝调用它。所以在以前的版本上,你需要自己安装pandoc的最新版本,安装方法是:
    sudo apt-get install cabal-install
    cabal update
    cabal install pandoc
    #记得把这个添加到目录
    export PATH=$HOME/.cabal/bin:$PATH

使用这个方法安装时,需要花很长的时间,估计要1个小时吧。主要原因是需要下载大量的haskell的包。所以推荐大家在ubuntu 15.10以后的平台上使用。

另外,在用上面的方法安装pandoc的时候,如果使用国内的镜像,速度会快很多,国内镜像的使用方法可以参考清华镜像的使用方法1,这里把它记录下来供参考:

第一次使用时,先执行cabal update,待生成~/.cabal/config之后,使用ctrl+c中断这个update,然后修改~/.cabal/config。修改方法为,将下面这行注释掉(用--注释)

remote-repo: hackage.haskell.org:http://hackage.haskell.org/packages/archive

修改为:

remote-repo: mirrors.tuna.tsinghua.edu.cn:http://mirrors.tuna.tsinghua.edu.cn/hackage

然后再执行cabal updatecabal install pandoc

  • 其他的系统 暂时还没有尝试

texlive

texlive用来处理Latex,它把latex格式的文件转为pdf。如果需要从markdown生成pdf文件,或者是打算由多篇文章生成一本pdf格式的书籍,需要有texlive的支持。这里选择的是texlive,安装方法如下

sudo apt-get install texlive-full

这个安装也需要大约1小时左右,因为texlive也有很多的包需要安装。这样安装会多安装许多语言包,不过比起自己去一个一个选择包来说,这是最简单的方式。

另外,因为我们需要中文的支持,所以需要另一个latex引擎,xelatex,所以这个也需要安装,方法是

sudo apt-get install xelatex

R安装

  • ubuntu 15.10

    直接安装就可以了sudo apt-get install r-base rbase-dev

安装成功以后,你应该可以直接键入R命令,如下所示:

xuyang@ubuntu15:~/blog$ R

R version 3.2.2 (2015-08-14) -- "Fire Safety"
Copyright (C) 2015 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R是自由软件,不带任何担保。
在某些条件下你可以将其自由布。
用'license()''licence()'来看散布的详细条件。

R是个合作计划,有许多人为之做出了贡献.'contributors()'来看合作者的详细情'citation()'会告诉你如何在出版物中正确地引用R或R程序包。

用'demo()'来看一些示范程序,用'help()'来阅读在线帮助文件,或
用'help.start()'通过HTML浏览器来看帮助文件。
用'q()'退出R.

> 

R包安装

R安装以后,还需要安装一个R的扩展包才可以工作,其中的rmarkdown,knitr是必须的。安装的方法为,在R的命令行键入

install.packages(c('rmarkdown','knitr'),repos="http://mirror.bjtu.edu.cn/cran/")

其中repos参数指定包的下载地址,这里指定的是国内的一个R镜像。

准备就绪

有了以上准备工作(pandoc,texlive,R,rmarkdown)以后,你就可以开始r + markdown的工作了。后面开始学习markdown的基础语法。



本文地址: http://www.bagualu.net/wordpress/archives/6172 转载请注明




发表评论

电子邮件地址不会被公开。 必填项已用*标注