File: README — Documentation for pirka (0.1.5)

Description

Pirka highlights source code syntax in EPUB books

Features

Highlights synatax in EPUB files
Extracts <code> elements from EPUB files and asks you which programing language they are, and then uses them to highlight
Downloads shared code and language information from Git repository

Examples

Highlighting source code syntax in EPUB books

$ pirka path/to/book.epub

It’s a short cut to:

$ pirka highlight path/to/book.epub

To highlight books, run pirka update(see below for details) just after installation because pirka highlight requires library files.

Detecting source code from EPUB books

$ pirka detect path/to/book.epub
Detecting code from "Book Title"
Library file was saved to:
path/to/library.yaml

library.yaml here includes:

location of <code> element(expressed by EPUB CFI but you don’t need to undarstand it.)
language field with blank value
file path in EPUB file(zip archive)
source code

Example:

  epubcfi(/6/64!/4/2/30/2):              # location
    language:                            # language name. blank at first
    item: OEBPS/text/p-003-003.xhtml     # file path in zip archive
    code: |                              # source code
      f1 = open("|cat", "w")
      f2 = open("|sed 's/a/b/'", "w")
      f1.print "Hello\n"
      f2.print "abc\n"
      f1.close
      f2.close

In Pirka context, the file is called library.

pirka highlight command determines programming languages of source code according to this file. Read source code, determine languages, write it at language field, remove code field, and then you can highlight the EPUB file by pirka highlight.

You also determine languages interactively. Set -i(--interactive) option:

$ pirka detect -i path/to/book.epub

Updating libraries

$ pirka update

Pirka provides official library files for some EPUB books as Git repository(https://gitlab.com/KitaitiMakoto/pirka-library). pirka update command fetches the files from the repository and you benefit from it.

Additionally, you can host library files by your own and make Pirka recognizes it by configuration file. See later section for that.

Listing supported books

$ pirka lib

pirka lib command lists books Pirka can highlight with:

Release Identifier(special identifier for EPUB books)
location of library file
title
some other metadata

Configuration

Pirka can be configured by environment variables, config file and command-line options.

Environment variables

XDG_DATA_HOME: Affects directory to save library files.
Library files are saved to $XDG_DATA_HOME/pirka/local
The directory is used to search library, too.
Default: $HOME/.local/share
XDG_DATA_DIRS: Affects directory to search library files.
You can specify multiple directory by seperating with a colon like XDG_DATA_DIRS=/dir1:/dir2.
/dir1/pirka/local and /dir2/pirka/local are used to search library, for example.
Default: /usr/local/share:/usr/share
XDG_CONFIG_HOME: Affects directory to search and save config file.
$XDG_CONFIG_DIRS/pirka.yaml is recognized as config file.
Default: $HOME/.config
XDG_CONFIG_DIRS: Affects directory to search config file.
You can specify multiple directory by seperating with a colon like XDG_CONFIG_DIRS=/dir1:/dir2.
/dir1/pirka.yaml and /dir2/pirka.yaml are searched as config file.
Default: /etc/xdg

Config file

Config file is a YAML file. Properties below are recognized:

data_home: Directory to save and search library files.
Default: $XDG_CONFIG_HOME/pirka/local
additional_directories: Directories to search library files.
Expressed by sequence(array).
Default: []
library_repositories: Git repository URIs used by pirka lib command.
Expressed by sequence(array).
Default: []

Command-line options

You can configure Pirka by pirka command’s global options:

-c, --config=FILE: Path to config file.
Default: $HOME/.config/pirka.yaml
-s, --data-home=DIRECTORY: Same to config file’s data_home property.
-d, --directory=DIRECTORY: Same to config file’s additional_directories property.
Able to multilpe times.

You can also see help by

$ pirka --help
Pirka highlights source code syntax in EPUB files

Usage: pirka [global options] [<command>] [options]

Global options:
    -c, --config=FILE                Config file. Defaults to /Users/ikeda/.config/pirka.yaml
    -s, --data-home=DIRECTORY        Directory to *SAVE* library data
    -d, --directory=DIRECTORY        Directory to *SEARCH* library data.
                                     Specify multiple times to add multiple directories.

Commands:
    highlight        Highlights source code in EPUB file
    detect           Detects source code from EPUB file and generate library file
    update           Update library files by remote files
    lib              Show library infomation
If command is ommitted, highlight is used with no option

Requirements

Ruby 2.2 or later
C compiler to compile Nokogiri gem

Install

$ gem install pirka

Make faster

By default, Pirka uses archive-zip gem, a pure Ruby implementation, for zip archive but you can make command execution faster by using Zip/Ruby gem, a C implementation. Just install Zip/Ruby:

$ gem install zipruby

Pirka, actually internally-used EPUB Parser, tries to load Zip/Ruby and use it if available.

Copyright

See COPYING for details.