写作工具的取经之路

写作工具的取经之路 - 图1

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

最早我使用的是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如下：

  1. ADOCTOR=asciidoctor
  2. PRINCE=prince
  3. CSSLINER=bin/cssliner
  4. CAT=cat
  5. BOOK=book.adoc
  6. SUFFIX=suffix.adoc
  7. OUT=./out
  8. ALL_CHAPTERS=$(shell find chapters -name "*.adoc" | grep -v index.adoc)
  9. ALL_HTML=$(ALL_CHAPTERS:%.adoc=$(OUT)/%.html)
  10. HTML_CSS=./templates/html/style.css
  11. WEIXIN_CSS=./templates/weixin/style.css
  12. HTML_FILE=$(OUT)/book.html
  13. WEIXIN_FILE=$(OUT)/weixin.html
  14. PDF_FILE=$(OUT)/book.pdf
  15. .PHONY: html weixin
  16. html:
  17. @$(ADOCTOR) -o $(HTML_FILE) -a stylesheet=$(HTML_CSS) $(BOOK)
  18. @$(PRINCE) $(HTML_FILE) -o $(PDF_FILE)
  19. @echo "Done!"
  20. $(ALL_HTML): $(OUT)/%.html: %.adoc
  21. @echo "Working on $<..."
  22. @$(CAT) $< $(SUFFIX) > $(OUT)/tmp.adoc
  23. @$(ADOCTOR) -o $@ -a stylesheet=$(WEIXIN_CSS) $(OUT)/tmp.adoc
  24. @rm $(OUT)/tmp.adoc
  25. @$(CSSLINER) $@ $@
  26. weixin: $(ALL_HTML)
  27. @echo "Done!"
  28. clean:
  29. @rm -rf $(OUT)/*

稍稍解释一下：

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

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

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

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

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

  1. $ make html

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

  1. $ make weixin

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

如果您觉得这篇文章不错，请点赞。多谢！

欢迎订阅公众号『程序人生』（搜索微信号 programmer_life）。每篇文章都力求原汁原味，早8点与您相会。

  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的工具