分享 asciidoctor-htmlbook —— HTMLBook 电子书工具链其一

Rei · February 01, 2017 · Last by luft replied at February 16, 2017 · 4647 hits

很高兴开源我的电子书工具链第一部分,一个 Asciidoctor 的 HTMLBook 后端。

项目链接 https://github.com/chloerei/asciidoctor-htmlbook

Asciidoctor 是一个 AsciiDoc 文档转换器,AsciiDoc 是专为书籍文档设计的标记语言,详情可以看 http://asciidoctor.org/

HTMLBook 是基于 XHTML5 的书籍文档标准,详情可以看 https://github.com/oreillymedia/HTMLBook

有了 asciidoctor-htmlbook,可以方便的把 AsciiDoc 转换到 HTMLBook。

例如,对于以下 AsciiDoc 文档:

= Hello, AsciiDoc!
Doc Writer <[email protected]>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

用内置的 Asciidoctor 后端转换的 HTML 内容是这样的:

<div id="preamble">
  <div class="sectionbody">
    <div class="paragraph">
      <p>An introduction to <a href="http://asciidoc.org">AsciiDoc</a>.</p>
    </div>
  </div>
</div>
<div class="sect1">
  <h2 id="_first_section">First Section</h2>
  <div class="sectionbody">
    <div class="ulist">
      <ul>
        <li>
          <p>item 1</p>
        </li>
        <li>
          <p>item 2</p>
        </li>
      </ul>
    </div>
    <div class="listingblock">
      <div class="content">
        <pre class="highlight"><code class="language-ruby" data-lang="ruby">puts "Hello, World!"</code></pre>
      </div>
    </div>
  </div>
</div>

用 HTMLBook 后端转换的 HTML 内容是这样的:

<section data-type="preamble">
  <p>An introduction to <a href="http://asciidoc.org">AsciiDoc</a>.</p>
</section>
<section id="_first_section" data-type="chapter">
  <h1>First Section</h1>
  <ul>
    <li>
      <p>item 1</p>
    </li>
    <li>
      <p>item 2</p>
    </li>
  </ul>
  <figure>
    <pre data-type="programlisting" data-code-language="ruby">puts "Hello, World!"</pre>
  </figure>
</section>

为什么要把 AsciiDoc 转换到 HTMLBook?

把 AsciiDoc 转换到标准化的 HTMLBook 后有利于处理成实际的电子书格式。现有的 Asciidoctor-pdf 和 Asciidoctor-epub3 跟 Asciidoctor 深耦合,对中文支持不好,难以修改样式。转化为 HTMLBook 后只需要对 HTMLBook 处理就行了。

处理流如下:

所以,接下来会实现 HTMLBook -> Website,HTMLBook -> PDF,HTMLBook -> EPUB 等转换器。更长远来说,任何源文档只要能转换到 HTMLBook,都能重用这些输出后端,例如 Docx -> HTMLBook,Markdown -> HTMLBook。

在我过去 3 年运营 SelfStore 的过程中,深感现有的电子书制作工具还不够好,包括 Asciidoctor,GitBook,LeanPub,于是萌生自己做工具链的想法。实现这套工具链的前置条件已经满足,但还有很多工作要做,欢迎有经验者与我联系。

期待 HTMLBook -> WebSite

感謝大大踩雷,可以的話能舉些 asciidoctor 中文支援問題的例子嗎?原本我想去用看看所以對這很有興趣。

#5 楼 @lulalala

Asciidoctor PDF

使用 Prawn 绘制 PDF,Prawn 不支持 CJK 文字环绕和 OTF 字体,需要打断字补丁,字体选择很少,样式设置很不方便。

以前处理的问题汇总在这里 https://github.com/asciidoctor/asciidoctor-pdf/issues/82

不过修了一个 bug 又引出新的 bug(https://github.com/chloerei/asciidoctor-pdf-cjk/pull/3),我不想再在这个方向投入。

我打算用 http://wkhtmltopdf.org/ 生成 PDF,借助 webkit,使用者可以基于 HTML/CSS 设置样式,字体也可以使用任意系统字体。

Asciidoctor EPUB3

这个包基本可用,就是有些小问题,但问题虽小却不好修。另外也是难于定制样式。

Asciidoctor 本身

代码很复杂,我想加个 rouge 代码高亮都无从下手,理解 Asciidoctor 的内部数据结构不如 HTML 方便。

综合这些问题,我觉得用 HTMLBook 作为中间格式会更好处理,不跟 Asciidoctor 耦合。

👍 👍 之前因为一些小需求,用过 wkhtmltopdf,不错。。

四处找此类工具中…… http://docs.racket-lang.org/pollen/ @Rei 请教您对 Pollen 的意见?谢谢。

#8 楼 @luft 之前没看过这个工具,看了几节文档。

我赞同副标题的内容“book is a program”,书有源码、编译、发布,跟程序差不多。不过这个工具跟 latex 的问题一样:难用。我是不知道怎么向一般作者介绍这个工具,写作之前要学习这套 Lisp 系 DSL,门槛太高。

在我构想中,制作一本书的可以分开三个环节。

  1. 作者写作,这个过程作者只需要考虑内容,不需要考虑样式和构建。工具可以是标记语言,或者其他标准化文档的编辑器。
  2. 制作样式,这个过程由技术或设计师进行,工具是 HTML/CSS/JavaScript。
  3. 构建发布,这个过程是自动化进行,把内容和样式编译成各种格式。可以是命令行工具,也可以是 SaaS。

所以在我看来现在最接近理想的工具是 GitBook。

#8 楼 @luft 好神奇的 markup,用這個不知道怎樣打出來的 ◊ 符號當作指令起頭。因為這樣應該很難推廣。要當作中間格式的話,會不會其標榜的可編程優勢就沒有了呢?

@lulalala 打出◊可以用快捷键,

# lozenge character ◊ 
# mac
option + shift + V 
# Windows
holding down alt, type 9674 on the num pad 
# Ubuntu
ctrl + shift + U, then 25CA

http://docs.racket-lang.org/pollen/pollen-command-syntax.html §12.2 有介绍。

我只是初步了解下,也有意向学学看。不过,可能还是等 @Rei 的工具链更实际些。

You need to Sign in before reply, if you don't have an account, please Sign up first.