code2ebook - Generate ebooks in various formats from source trees in various programming languages

• Name
• Description
  • Generate static HTML sites from source trees
    • src2html.pl
      • Change CSS style
      • Usage
      • HTML output features
      • Source file types recognized
  • Convert the HTML site to ebooks in various formats
    • Generate MOBI ebooks for Kindle
    • Generate EPUB ebooks for iPad/iPhone
• Prerequisites
• Sample eBooks
  • weighttp
    • HTML for weighttp source tree
    • EPUB for weighttp source tree
    • MOBI for weighttp source tree
  • LuaJIT
    • HTML for LuaJIT source tree
    • EPUB for LuaJIT source tree
    • MOBI for LuaJIT source tree
  • Nginx
    • HTML for Nginx source tree
    • EPUB for Nginx source tree
    • MOBI for Nginx source tree
• Known issues
• TODO
• Author
• Copyright and License
• See Also

Want to browse big source code trees in your Kindle or iPad?

This project provides utilities to help generating pretty ebook files in various formats directly from arbitrary source trees.

Before you begin, ensure you have installed all the prerequisites (well, don't be scared, just vim, ctags, and perl ;)).

The src2html.pl script can generate an HTML tree from the source tree that you specify, for example:

export PATH=/path/to/code2ebook:$PATH

cd /path/to/your/project/
src2html.pl --color --cross-reference . 'Your Book Title'

The resulting HTML site can be viewed in a web browser. And the entry point is ./index.html (according to the command above).

The following image shows what a typical HTML page looks like when rendered by a web browser:

See Samples for more complicated real-world sample outputs. Note that, for ebook readers lacking colors (like Amazon Kindle), then you should not specify the --color option for the src2html.pl script.

This is essentially an HTML-formatted "ebook", which is readily browsable in a web browser on either a PC or a tablet.

Back to TOC

It is worth mentioning that if you do not like the default colors or have further style requirements, you can just specify the --css FILE option to make the HTML pages use your own. You can start with the default CSS file (named colorful.css) in this project.

Back to TOC

For the full usage of this script, specify the -h or --help options. One sample output is

src2html.pl [options] dir book-title

Options:
    --charset CHARSET     Specify the charset used by the HTML
                          outputs. Default to UTF-8.

    -c
    --color               Use full colors in the HTMTL outputs.

    --css FILE            Use FILE as the CSS file to render the HTML
                          pages instead of using the default style.

    -e PATTERN
    --exclude PATTERN     Specify a pattern for the source code files to be
                          excluded.

    -h
    --help                Print this help.

    -i PATTERN
    --include PATTERN     Specify the pattern for extra source code file names
                          to include in the HTML output. Wildcards
                          like * and [] are supported. And multiple occurances
                          of this option are allowed.

    -x
    --cross-reference     Turn on cross referencing links in the HTML output.

Copyright (C) Yichun Zhang (agentzh) <[email protected]>.

Back to TOC

This src2html.pl script generates pretty HTML pages for each source code file featuring

Back to TOC

1. Summarized data types, macros, global variables, and functions defined in each source code file shown as TOC at the beginning of the corresponding HTML page.
2. Colorful syntax highlighting via the vim program (enabled by the --color option).
3. Cross-reference links to the definition lines of the referenced data types, macros, global variables, and functions across all the source code lines (similar to the LXR Cross Referencer but ours is much more lightweight). This is enabled by the --cross-reference option (or the -x option for short).

Back to TOC

Right now all the file extension names known to your ctags program are supported. But .html and .htm files are always excluded to avoid infinite recursion.

For the full language list supported by this tool, just type the following command:

ctags --list-maps=all

You can explicitly include extra source files by specifying as many --include=PATTERN options as you like, as in

src2html.pl --include='src/*.blah' --include='*foo*' --color . "my project"

Similarly, you can also exclude files by specifying one or more --exclude=PATTERN options.

Back to TOC

Now that we have the HTML-formatted "ebook", we can generate ebooks in other formats like .mobi and .epub using Calibre.

Back to TOC

For example, to generate a .mobi file for Kindle DX:

cd /path/to/your/project/

# assuming we specified the "." directory while running src2html.pl
ebook-convert ./index.html my-project.mobi \
    --output-profile kindle_dx --no-inline-toc \
    --title "Your Book Title" --publisher 'Your Name' \
    --language en --authors 'Your Author Name'

In this example, the resulting ebook file is named my-project.mobi in the current working directory.

Note: On OS X you have to go to Preferences->Advanced->Miscellaneous and click install command line tools to make the command line tools available after you installed the app. On other platforms, just start a terminal and type the command.

Here we use the value "kindle_dx" for the --output-profile option assuming that we want to view the ebook in Kindle DX. You should use "kindle" for other (smaller) models of Kindle.

The ebook-convert utility is provided by Calibre, see its online documentation for full usage:

http://calibre-ebook.com/user_manual/cli/ebook-convert.html

Well you need both Perl and Python ;)

Back to TOC

Below is a simple sample command to generate the .epub ebook from the HTML site:

cd /path/to/your/project/

# assuming we specified the "." directory while running src2html.pl
ebook-convert ./index.html my-project.epub \
    --output-profile ipad3 \
    --no-default-epub-cover \
    --title "Your Book Title" --publisher 'Your Name' \
    --language en --authors 'Your Author Name'

In this example, the resulting ebook file is named my-project.epub in the current working directory, which is readily readable in apps like iBooks on iPad or iPhone.

Back to TOC

You need to install the following dependencies of a recent version (the newer, the better):

• Exuberant ctags

should be readily available in almost all the Linux distributions by simply installing the ctags package.

• vim

should be readily available in almost all the Linux distributions by simply installing the vim package.

• perl

should be readily available in almost all the Linux distributions by simply installing the perl package. It is worth mentioning that perl 5.10 or above is highly recommended due to performance boost in the perl regex engine. But older versions of perl should also work as well, just much slower.

All these components are very common programs in the *NIX world.

Back to TOC

Below provides some sample ebooks generated from real-world opensource projects like weighttp, LuaJIT, and Nginx.

Back to TOC

weighttp is a lightweight and small benchmarking tool for webservers.

Back to TOC

The HTML site generated from the weighttp source code can be browsed here:

http://agentzh.org/misc/code/weighttp/

Back to TOC

The corresponding EPUB ebook can be downloaded from below:

http://agentzh.org/misc/code/weighttp/weighttp.epub

Back to TOC

The corresponding MOBI ebook can be downloaded from below:

http://agentzh.org/misc/code/weighttp/weighttp.mobi

Back to TOC

LuaJIT is a Just-In-Time Compiler (JIT) for the Lua programming language. Lua is a powerful, dynamic and light-weight programming language.

Back to TOC

The HTML site generated from the LuaJIT source code can be browsed here:

http://agentzh.org/misc/code/luajit2/

Back to TOC

The corresponding EPUB ebook can be downloaded from below:

http://agentzh.org/misc/code/luajit2/luajit-2.0-src.epub

Back to TOC

The corresponding MOBI ebook can be downloaded from below:

http://agentzh.org/misc/code/luajit2/luajit-2.0-src.mobi

Back to TOC

Nginx is an open source reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer, HTTP cache, and a web server (origin server).

Back to TOC

The HTML site generated from the Nginx source code can be browsed here:

http://agentzh.org/misc/code/nginx/

Back to TOC

The corresponding EPUB ebook can be downloaded from below:

http://agentzh.org/misc/code/nginx/nginx-1.7.9.epub

Back to TOC

The corresponding MOBI ebook can be downloaded from below:

http://agentzh.org/misc/code/nginx/nginx-1.7.9.mobi

Back to TOC

• vim is the dominating performance bottleneck when running the src2html.pl tool with the --color option.
• When a tag has multiple targets, only the first one is picked up (in the future, we may provide a middle page listing all the targets for the user to choose, just as in the LXR Cross Referencer).

Back to TOC

• Add support for the --exclude=PATTERN options to the src2html.pl tool.

Back to TOC

Yichun "agentzh" Zhang (章亦春) [email protected], CloudFlare Inc.

Back to TOC

This module is licensed under the BSD license.

Copyright (C) 2011-2014, by Yichun "agentzh" Zhang, CloudFlare Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Back to TOC

• LXR Cross Referencer
• Exuberant ctags
• vim

Back to TOC