search

pillar-markup / pillar

Markup syntax and associated tools to write and generate documentation, books and slides
MIT License
50 stars 37 forks source link
markup markup-language pharo pillar

readme

Pillar

Pillar is a markup syntax and tool-suite to generate documentation, books, websites and slides. Pillar is not new, it was invented around 2000 as a supporting language for SmallWiki: one of the first wiki using OOP for real. Its ancestor was the markup for the Pier CMS and we extracted it from Pier to make it more applicable to different domains. The Pillar syntax is similar to markdown but its emphasis is on publishing and how it handles different types of links.

Now in the latest version Pillar we are supporting Microdown syntax and migrating all the support to Microdown while supporting the Pillar syntax for backward compatibility reasons. We can migrate automatically books from Pillar syntax to Microdown syntax (compatible with markdown).

In the future Pillar will be the name of the compilation chain and the syntax language will be Microdown.

License https://github.com/pillar-markup/pillar/workflows/unit.app/badge.svg https://github.com/pillar-markup/pillar/workflows/unitTests/badge.svg

https://github.com/pillar-markup/pillar/workflows/system/badge.svg https://github.com/pillar-markup/pillar/workflows/integration.app/badge.svg

Coverage Status

Installation

1. Building from sources

For HTTPS setup, execute the build.sh script found in the scripts directory:

Here is the latest version for Pharo 12.

$ git clone https://github.com/pillar-markup/pillar.git
$ cd pillar
$ git checkout v10.1.0
$ chmod a+x ./scripts/build.sh
$ ./scripts/build.sh

Here is the latest version for Pharo 11.

$ git clone https://github.com/pillar-markup/pillar.git
$ cd pillar
$ git checkout v9.0.1
$ chmod a+x ./scripts/build.sh
$ ./scripts/build.sh

Here is the latest version for Pharo 10.

$ git clone https://github.com/pillar-markup/pillar.git
$ cd pillar
$ git checkout v8.3.2
$ chmod a+x ./scripts/build.sh
$ ./scripts/build.sh

The script will create a build directory in your current working directory with the pillar installation.

$ ls
LICENSE  README.md  appveyor.yml  archetypes  ==>>build<<==  download.sh  scripts  src

2. Setting up the environment

You can then proceed to install that pillar build where you want. For example, you can place it in a hidden directory in your home directory:

$ cd ..
$ mv pillar ~/.pillar

Then add that directory to the PILLAR_HOME and HOME environment variables, for example, by modifying your .bashrc with

export PILLAR_HOME="$HOME/.pillar"

To make the pillar command available in your shell you can:

3. Install external dependencies

You need to have a LaTeX installation in your machine. The simplest is to do a full installation, otherwise read below for a more tailored solution.

Installing LaTeX on OSX

The simplest installation is to do a full Mactex installation. Just follow the instructions in https://www.tug.org/mactex/

Installing LaTeX on *nix

The simplest way to install LaTeX on unix is to install texlive-full in your system using your preferred package manager.

Installing LaTeX on Windows

Install a LaTeX distribution such as MiKTeX and install the dependencies specified below using the provided package manager. Then, make sure the bin directory is in your PATH environment variable. For example this could be the following value:

Tailored installation (for non-full lovers)

Producing pdf documents with Pillar requires a LaTeX installation with certain packages. Pillar 7.7.3 introduced the possibility to use LaTeX 2018 or the rolling version of 2019. Check the ensure-deps.sh files and the support/latex.

Getting started

To create a book, you can start by installing the book archetype in a directory where you want to manage it:

$ mkdir my-new-book
$ cd my-new-book
$ pillar archetype bod-book

You can then edit the pillar files and the pillar configuration file pillar.conf. Finally, you can generate your book in pdf using.

$ pillar build pdf

Or in html:

$ pillar build html

The resulting pdf or html site will be written into the _result directory.

All commands

Add the -h flag to get documentation.

pillar build It builds by default the export format found in pillar.conf at defaultExport target.

pillar archetype

pillar updateTemplate

pillar serve

Contributing to Pillar

The current pillar version is being developped using Pharo12. To contribute, the easiest way to to follow the previous scripts and send PullRequests. Use the latest dev as a root for your changes.

Cleaning first

First remove existing packages from the Pharo distribution.

#( 'Microdown' 'BeautifulComments' 'DocumentBrowser' ) do: [ :name |
        (IceRepository repositoryNamed: name)
            ifNil: [ self inform: 'Project not found: ' , name ]
            ifNotNil: [ :found |
                found
                    unload;
                    forget ] ]

The following script can be useful if you develop using the launcher and want to try to execute the image as from a pillar command

/Users/ducasse/Documents/Pharo/vms/100-x64/Pharo.app/Contents/MacOS/Pharo  /Users/ducasse/Documents/Pharo/images/P11-PillarRealReference/P10-PillarRealReference.image clap build pdf index.pillar

History

For Pharo 12

The development of Pillar and Microdown are now in Pharo 12.

For Pharo 11

For Pharo 10

Planned development

Old and obsolete documentation

Read the documentation at https://github.com/SquareBracketAssociates/Booklet-PublishingAPillarBooklet. Please note that chapter on "Pharo a web Perspective" is obsolete since it refers to Pharo 60.