Contents
Booklet
Booklet is a publishing software for short texts, particularly user documentation. It is designed to be easy to write and read on any platform. Booklet is a fork of Pamflet by Nathan Hamblen and others. Before use Booklet please read Pamflet documentation. Most things that work in Pamflet work in Booklet too.
Features of Booklet:
- hardcoded content is moved to dynamic Scalate templates;
- ability to use markdown inside HTML blocks;
- ability to modify options per block of markdown;
- options are merged from different levels: per documentation, per page, user specific;
- reevaluate environment from the beginning for every transformation. Changes are applied immediately, which is important for end user while design stage. Realtime parameter isn't a primary one for a such type of text generators. It works like a charm with compass watch and interactive development.
This documentation is created with Booklet. Such result is a hardly available with hardcoded template. Scalate gave it a new breath of life.
Usage
Components
Booklet itself consists of 3 parts:
- booklet-library - Core part that provides storage, options, Scalate publishing logic;
- booklet-knockoff - Knockoff integration part that enhance standard Knockoff parsers;
- booklet-app - application, that compatible with SBT launcher.
Use as the standalone application
You may start it in *NIX environment with command line like this:
java \
-Dsbt.boot.properties=/home/user/booklet/booklet-app.configuration \
-jar /home/user/booklet/sbt-launch.jar -- @mybooklet.properties
where
- sbt.boot.properties - location of the application configuration
- sbt-launch.jar - the latest ;-) launcher from SBT
- mybooklet.properties - argument with user options, for example. Use '-h' for help
Application configuration
The typical application configuration is provided bellow. You may copy'n'paste it or download sample one and modify. Change 1.2.3.4-SNAPSHOT version to the latest available.
[scala]
version: 2.10.3
[app]
org: org.digimead
name: booklet-app
version: 1.2.3.4-SNAPSHOT
class: org.digimead.booklet.Application
cross-versioned: binary
[repositories]
local
maven-central
digimead-maven: http://storage.googleapis.com/maven.repository.digimead.org/
[boot]
directory: \${user.home}/.sbt/booklet-boot
SBT launcher
You may use any available SBT launcher. I recommend the latest one.
User options
File with user options may be specified in @file format. For example I used bellow options file while designing Booklet:
resources: /my/path/to/template-dev
user: digimead-specific
project: Booklet
artifacts: booklet-app, booklet-knockoff, booklet-library
logo: http://commondatastorage.googleapis.com/digimead/booklet.png
disqus: Booklet
Of course, for publishing I provided different options. I specified path to production template with compressed resources and adjusted other parameters.
Running
docs directory with markdown files must be exists. After start you will see something like:
[main] INFO org.digimead.booklet.template.Preview\$ - Warm up Scalate engine.
[main] INFO org.eclipse.jetty.server.Server - jetty-7.6.9.v20130131
[main] INFO org.eclipse.jetty.server.handler.ContextHandler - started o.e.j.s.ServletContextHandler{/,null}
[main] INFO org.eclipse.jetty.server.AbstractConnector - Started SocketConnector@127.0.0.1:50059
Previewing `docs`. Press CTRL+C to stop.
The Booklet is ready to process HTTP requests on 127.0.0.1:50059.
Use as a library
Add Booklet to you application and invoke
Produce(BookletStorage(input, bookletProperties).globalized, output)
where
- input - directory with markdown files
- output - directory with transformation result
- bookletProperties - user options
Options
There are several booklet options that affect the result. From the user point of view the options is a map of key -> value pairs. These pairs are held by Properties. There are few sources of options:
- file booklet.properties in markdown catalog (the lowest priority)
- properties that is emmedded into a markdown
- user specified properties (the highest priority)
While processing all options are merged and converted to Scalate attributes.
You may add your own options as well.
List of the booklet options.
Key | Description | Example Values | Notes |
|---|---|---|---|
Flag indicating whether the line numbers in code should be visible. | Y/N | changed by user |
|
A name of the default language. | en | changed by user |
|
An exclude regexp that applied to booklet markdowns. | changed by user |
||
An exclude regexp that applied to booklet markdowns. | changed by user |
||
A name of the file with an index content. | Y/N | changed by user |
|
Flag indicating whether the HTML content should be processed as markdown. | Y/N | changed by user |
|
A list of the booklet languages. | en, ja, ru | changed by user |
|
A name of the file with site manifest for offline usage. | booklet.manifest | changed by user |
|
Flag indicating whether the generated content should support offline mode. | Y/N | changed by user |
|
Full path to user container with booklet template. | changed by user |
||
A name of the template directory. | template | changed by user |
|
A name of the PageContent template. | pageContent.scaml | changed by user |
|
Full path to PageContent template. | /full/path/to/pageContent.scaml | ||
A name of the PageDeepContents template. | pageDeepContents.scaml | changed by user |
|
Full path to PageDeepContents template. | /full/path/to/pageDeepContents.scaml | ||
A name of the PageScroll template. | pageScroll.scaml | changed by user |
|
Full path to PageScroll template. | /full/path/to/pageScroll.scaml | ||
A name of the file with template properties. | booklet.properties | changed by user |
|
title | Page title. | changed by user |
|
Title pattern that applied to each page title (not to the content title). | changed by user |
||
Flag indicating whether page title should be generated from the file name. | Y/N | changed by user |
|
Flag with toc sort order. | Y/N | changed by user |
|
Flag indicating whether the library should be verbose. | Y/N |
For Your Perusal
All techniques described in this booklet are used to produce it. Take
a look through Booklet's docs/ directory on github.
