写作工具的取经之路

写公众号写了一年,穿插着写了一本书,在工具的使用上,也渐渐有了些心得,不敢独专,跟大家分享一下。

最早我使用的是reST [1] ,使用sphinx [2] 来撰写文章。使用reST/sphinx最大的好处是格式简单,扩展性强,便于生成PDF和多种文档结构。

然而我的博客在用octopress等工具生成的 [3] ,使用的是markdown。做类似的事,却用两种格式,这让人十分抓狂。再三考虑后,我决定也使用markdown来写公众号。

使用markdown恼人的是格式太简单,有时候需要一些变化,便只好直接上html。不过简单有简单的好处,它让我更专注于内容,而非作为点缀的形式。

为了便于版本管理,我所有的稿子都放在一个git repo下,同步到github(private repo,嘻嘻)。这样做的好处是我不必担心丢稿子,同时github自动为markdown生成的展示页面让我可以copy & paste到公众号上。

最初公众号对github的格式的支持是良好的,但七八月间的某次调整,公众号突然对各种外部粘入的内容不友好了,格式丢得一塌糊涂,恼人得很。后来从知乎上,我了解到markdown here这个chrome神器,你只需把原始的markdown文稿粘入公众号的输入框,按下一个快捷键(记得是ctrl + alt + M),markdown here就会自动帮你转换成html,还保留所有格式。稍稍研究了一下markdown here,我才明白但凡公众号上发布的文章,格式都需要是inline的,就跟html email一样。markdown here自带一个基础样式表,然后在生成html的时候,把这个样式表inline到每一行html代码中。

了解了这一点后,便再也没人能阻挡我对公众号文章的「美」的追求。在不同的文章里,我不断尝试,一点点修改样式表,使其至少符合我的审美。

在此期间,我还用node-webkit + ace + marked做了个简单的osx下的编辑器,但因为没有比sublime text + markdown here更好用,我自己都没在用,所以便罢了。

随着「途客圈创业记」连载的不断深入,我发现自己需要一个好的PDF生成工具。最初我在LaTeX [4] 上艰难前行,生成了也还算过得去的PDF,后来发现了kitabu [5] + princexml [6] 的解决方案,便全面转换到这个方案,「途客圈创业记」便是用其生成的。

后来读者朋友先后给我推荐了gitbook [7] 和asciidoctor [8]。gitbook的能力自不必说,不少出版社都在使用,而且其生成的html可以用做交互式教学,很适合技术类的电子书。但gitbook目前只支持markdown格式,使得其扩展成为问题。在未来的版本中,gitbook有可能会加入asciidoc的支持。

相对于大家都很了解的markdown,知道asciidoc的人不多。这也是一个纯文本的写作语言,和markdown一样很好掌握,但格式丰富得多。想了解asciidoc的语法,可以google asciidoctor syntax。

我的新书「奇博士的管理课」便使用asciidoc撰写,之所以这么选择,是因为我喜欢尝鲜,就跟不断变换写作风格一样,我喜欢在未知的世界里探索。

asciidoc的世界里没有kitabu这样的工具,至少我没发现。所以我只好自己写一个,使用了这些工具:

  • ✓ asciidoctor,一个基于ruby的asciidoc → html的命令行工具。
  • ✓ 自己写的cssliner,用于生成公众号友好的网页,使用python的premailer lib
  • ✓ princexml,用于生成PDF。
  • ✓ makefile,把所有工具连接起来。

Makefile如下:

ADOCTOR=asciidoctor
PRINCE=prince
CSSLINER=bin/cssliner
CAT=cat

BOOK=book.adoc
SUFFIX=suffix.adoc

OUT=./out

ALL_CHAPTERS=$(shell find chapters -name "*.adoc" | grep -v index.adoc)
ALL_HTML=$(ALL_CHAPTERS:%.adoc=$(OUT)/%.html)

HTML_CSS=./templates/html/style.css
WEIXIN_CSS=./templates/weixin/style.css

HTML_FILE=$(OUT)/book.html
WEIXIN_FILE=$(OUT)/weixin.html
PDF_FILE=$(OUT)/book.pdf

.PHONY: html weixin

html:
    @$(ADOCTOR) -o $(HTML_FILE) -a stylesheet=$(HTML_CSS) $(BOOK)
    @$(PRINCE) $(HTML_FILE) -o $(PDF_FILE)
    @echo "Done!"

$(ALL_HTML): $(OUT)/%.html: %.adoc
    @echo "Working on $<..."
    @$(CAT) $< $(SUFFIX) > $(OUT)/tmp.adoc
    @$(ADOCTOR) -o $@ -a stylesheet=$(WEIXIN_CSS) $(OUT)/tmp.adoc
    @rm $(OUT)/tmp.adoc
    @$(CSSLINER) $@ $@

weixin: $(ALL_HTML)
    @echo "Done!"

clean:
    @rm -rf $(OUT)/*

稍稍解释一下:

1) 我的所有文章都放在chapters目录下,$(ALL_CHAPTERS) 获取所有adoc文档。

2) 每个新的章节单独一个文档,为了公众号发表方便,生成独立的html。由于每篇文章末尾我都要加一段共同的内容,所以:

@$(CAT) $< $(SUFFIX) > $(OUT)/tmp.adoc

用于生成一个临时的,包含 $(SUFFIX) 的文档,然后再用 cssliner 将css inline化。

其它的不解释。这样,对于「奇博士的管理课」,当我想生成PDF时:

$ make html

想生成用于公众号的内容时:

$ make weixin

就一切OK了。如果大家觉得这工具有用,也许我可以将其做成一个python命令行工具包,一条命令完成所有工作。

1. restructured text

2. 一个基于python的文档生成工具

3. 最早是octopress,后来使用wintersmith,最后又迁移到docpad上

4. 一个基于TeX的排版系统,没听过TeX?你还记得那个神一样的the art of computer progrmming的作者Donald Knuth,写书的时候他觉得排版工具不爽,便花了差不多十年时间发明了TeX

5. 一个ruby下的电子书生成工具

6. 最好的将html转换成PDF的工具,没有之一

7. 一个通过markdown生成印刷级质量的电子书的工具

8. 一个使用asciidoc生成精美html和docbook的工具

原文发布于微信公众号 - 程序人生(programmer_life)

原文发表时间:2014-11-04

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏HBStream流媒体与音视频技术

C++实现RTMP协议发送H.264编码及AAC编码的音视频,摄像头直播

41150
来自专栏西枫里博客

创维50E680进入工厂模式安装第三方软件

由于广电总局的...

14610
来自专栏酷玩时刻

QQ轻游戏入门到精通OR放弃?

注册很简单,使用已有Q号登录「厘米游戏」开放平台按照流程提交资料审核即可 。开发者接入官方说明文档

80340
来自专栏鹅厂网事

走进腾讯公网传输系统

"鹅厂网事"由深圳市腾讯计算机系统有限公司技术工程事业群网络平台部运营,我们希望与业界各位志同道合的伙伴交流切磋最新的网络、服务器行业动态信息,同时分享腾讯在网...

47650
来自专栏FreeBuf

Pegasus间谍套件内部原理及流程剖析

事件介绍 这篇报道是关于最近发生的在全球范围内活跃的APT间谍软件的深度研究,Lookup团队已经捕获了样本,并且在一台全新的iOS设备上进行了深度研究。 NS...

39890
来自专栏HBStream流媒体与音视频技术

C++实现RTMP协议发送H.264编码及AAC编码的音视频,摄像头直播

  RTMP(Real Time Messaging Protocol)是专门用来传输音视频数据的流媒体协议,最初由Macromedia 公司创建,后来归Ado...

40150
来自专栏葬爱家族

Android高德之旅(2)地图类型

今天继续我们的Android高德之旅,上一篇已经可以显示最基本的地图了,有基本的缩放、旋转功能,还有最后做的小特效,今天这篇文章来记录一下高德地图的5种地图类型...

17110
来自专栏求索之路

适用于键盘流、懒人、强迫症患者以及码农的究极Mac使用指南

再次声明:本文是给一些喜欢折腾提升效率的、希望成为键盘流选手的、懒惰得不愿意多移动手指的、有严重的强迫症的人提供一些经验和帮助的。所以意义党、不分青红皂白党、键...

35330
来自专栏媒矿工厂

SRT: 开源的视频传输协议

SRT(Secure Reliable Transport)是新一代低延迟视频传输协议,是一种开源、免费和应用灵活的规范,它的性能与专用的协议一样优秀,同时能够...

2.7K30
来自专栏吉浦迅科技

【用户经验分享】Jetson TX1-TX2通电后自动开机运行的方法

国庆前(我要是没失忆的话应该是2017年的国庆)有群友问到Jetson如何开机自启动(意思是不想每次都人为的按下开机按键)。刚开始我以为他有程序要开机自启动...

61660

扫码关注云+社区

领取腾讯云代金券