Skip to content
A basic skeleton for a book written with Pillar. Updates to come…
CSS TeX Shell JavaScript
Latest commit 05926f4 Jul 29, 2015 @jecisc jecisc Merge pull request #11 from pillar-markup/cf_update_download_script
download script should take Pillar-deployment and not the normal vers…
Failed to load latest commit information.
Example
support
.gitignore
.travis.yml
README.md
clean.sh
compile.sh add luatex compilation alternative. by default, it is pdflatex Dec 16, 2014
createNewBook.sh
download.sh
pillar.conf
updateBookSkeleton.sh

README.md

Pillar Book Skeleton Build Status

This is a skeleton that can be used as a starting place to write your book. For now on this it is being used by PharoForTheEnterprise and UpdatedPharoByExample books.

You should replace this intro and first two sections with a nice information about your book :)

What is Skeleton

Pillar Book Skeleton provides a predefined structure for source files, as well as usefull scripts to write books with Pillar markup.

How to use Skeleton

Simple way:

cd MyBook
curl https://raw.githubusercontent.com/pillar-markup/book-skeleton/master/createNewBook.sh | bash

Other way:

  • Fork this repository, and start writing your book (explained in the next section).
  • Customise pillar.conf with your book's title.
  • use the updateBookSkeleton.sh script. Basically, this script does:

    • Add this repository as a remote:
    git remote add skeleton https://github.com/pillar-markup/book-skeleton.git
    • Then you want to get updates from this repository execute:
    git pull skeleton master

    You will have to resolve conflicts if updates occurred in the lines that you've changed.

Continuous Integration suggestions

If you want your book to be built automatically (e.g., by Jenkins), you have to configure the job to execute these lines:

./download.sh
./compile.sh

and then to archive these artefacts:

Book.pdf, Book.tex, **/*.pillar, **/*.pillar.tex, **/*.pillar.pdf, **/*.pillar.html,  **/*.pillar.md, **/figures/*, html/**

Also Skeleton comes with Travis CI configuration file. This allows you to start automated testing of your book just by enabling it on Travis CI service. Finally you can follow Sharing Travis-CI generated files tutorial, to hack GitHub and Travis into storing your artefacts.

How to write a book

This book is written in Pillar markup. If you are not familiar with it please check the pillar-documentation.

Generating the book

  1. Execute ./download.sh to obtain the Pillar executable that does all the job (do it only ONCE).
  2. Execute ./compile.sh to generate your book in the book-result folder (specified in pillar.conf)

Generating one chapter

If you want to generate only one chapter, pass the file's path to the script: ./compile.sh Example/Example.pillar. If you have pdflatex installed and available in your system's PATH, the script will also generate pdf files.

Adding a chapter

To add a chapter create a directory for it (named, e.g., Example) and put there a .pillar file (named, e.g., Example.pillar) which will contain the chapter itself. Put images in the figures subdirectory of the new chapter directory.

Add your chapter to:

  • pillar.conf in the inputFiles array as: "Example/Example.pillar", and
  • support/templates/book.latex.template in \graphicspath as {../Example/}

Installing pillar command

If you use pillar in different books, you can install it once for all your books and then avoid executing the download.sh script anymore to not duplicates all the files (Pillar image, ...) in each repository of each books.

Steps to install pilar:

  1. You already executed the ./download.sh script i.e. you have the pillar script, ...
  2. Copy you the script to your user bin folder

    cp pillar ~/bin
    
  3. Copy the ressources to PILLAR_ROOT (wherever you want such as ~/Pillar)

    cp pharo Pharo.changes Pharo.image pharo-vm $PILLAR_ROOT
    
  4. Set these environment variables in your shell start up (~/.bashrc or ~/.zshrc)

    cat >> ~/.zshrc < END
    
    export PHARO_VM="${PILLAR_ROOT}/pharo"
    export PILLAR_IMAGE="${PILLAR_ROOT}/Pharo.image"
    
    END
    

Now, you should be able to use the pillar in your shell as any other commands. And, when you will clone a book repository, you don't have to execute the download.sh and you can directly compile it using compile.sh.

Fix PNG errors while compiling LaTeX

Some png file may trigger an error when compiling tex to pdf

libpng warning: iCCP: known incorrect sRGB profile

Solution, convert png file to use the right color profile

find . -type f -name "*.png" -exec convert {} -strip {} \;

Caveats

  • You must neither use spaces nor underscores (_) in file names.

Tools

There are mods/bundles/packages for text editors, that provide improvements for pillar files editing:

Something went wrong with that request. Please try again.