Lilac 0.1.0.8 / user-manual.org

User Manual

1 Introduction

Lilac originally started out as an extension to Emacs Orgmode, to fix most of the nondeterminism issues of Orgmode's weaving (aka "export") process.

Sometime later, it was determined that Orgmode's HTML export was simply too slow (it could take 10+ seconds on large documents). This project was then rewritten in Haskell, mainly for performance but also for maintainability.

2 Major differences with vanilla Org

This section may be useful for existing Orgmode users, to see at a glance what is and isn't supported.

Orgmode is quite complex. Some features have been purposely left out, mainly for simplicity or readability.

2.1 Compilation step

Orgmode tangles and weaves from Org files directly. There is no intermediate compilation step.

Lilac adds a compilation step in order to cache some computations. Basically, an Org doc must be compiled into a Lilac Object (*.lobj), and then one or more of these objects are archived into a Lilac Archive (*.larc). It is this archive file which is then tangled or woven as needed.

Figure 1. The relationship of Lilac subcommands. init is not included here because it is not strictly needed.
The relationship of Lilac subcommands. [[id:58b8cf79-8b0d-4092-a70c-f772fff985b5][~init~]] is not included here because it is not strictly needed.
🔗
fig:lilac-subcommands.pikchr
🎯 image/lilac-subcommands.pikchr

2.2 List item spacing required

List items must be indented from the main text with two leading spaces, and also must have an empty blank line. See List items.

These spacing requirements were determined to be necessary in order to maximize readability in raw Org (plaintext) form.

2.4 No #+include support

The ability to declaratively copy/paste chunks of other files is not supported, because doing so results in unreadable raw Org files (you would have to open up the linked page separately to see what was actually included).

2.5 Headings must be linked via their ID (UUID)

You cannot link to headings by their name, or by a "search" of a file path. You must instead always use UUID links. See ti:0004-properties-drawer-not-empty for an example (or, if you are reading this document from the raw Org file, just grep for :ID:)

By the same token, all documents require a UUID, so that even if you don't have a heading, other documents can still reference a named block in your doc via the top-level document UUID.

You probably don't want to type these ID values by hand. In Emacs, you can use M-x org-store-link to get the heading or document's ID (or create one automatically in the process if one doesn't exist yet).

2.6 No implicit concatenation of multiple blocks sharing the same name when tangling

Orgmode allows multiple blocks all sharing the same #+header: :noweb-ref bar metadata, where during tangling these blocks will be concatenated together, in the order that they appear in the doc. However, we do not allow this style for the following reasons:

  1. Orgmode doesn't have good navigation support for it. org-babel-goto-named-src-block only supports #+name: ... metadata.

  2. Using this style can lead to anonymous blocks that don't have a name. IOW, avoiding this style forces us to provide a name for all blocks, and naming everything is generally not a bad thing, because explicit is better than implicit.

  3. The order of concatenation is implicitly hardcoded to be top-to-bottom. When we only use #+name: ..., we can choose any order we want, not just top-to-bottom (by naming the children and choosing how to order the exposition of these child blocks).

2.7 Expandable blocks

If you set #+header: :collapsed true for a block, it will be collapsed in the woven output. You can then click on a button to expand it. This is useful when you have source code that generates figures (drawing), and you don't want the code to steal the attention away from the figure. fig:lilac-subcommands.pikchr is an example of this.

Below is an example of a collapsed anonymous block.

🔗

2.8 Other unsupported Org features

The features below are not supported (and are not planned to be supported).

3 Comparison with other LP tools

Table 1. Comparison of LP tools.
NameWritten inWritten with LP?
(Does it use itself?)		Markup language
(Input syntax)		Tangle-able languages
LilacHaskellYesOrgmodeAny
Emacs OrgmodeEmacs LispNoOrgmodeAny
EntangledPythonNoMarkdownAny
srcweaveCommon LispNoMarkdownAny
FunnelWebCNoFunnelWeb1Any
PortiaOCamlYesAnyAny
NowebC, Awk, IconYesNoweb1Any
NuwebCYesLaTeXAny
LiterateDYesMarkdownAny
CWEBCYesTeX1C, C++

4 Basic initial setup

The main requirement is that you must author Org files, because that's what Lilac understands. Emacs is perhaps the most popular application for authoring Org files, so using Emacs is highly recommended.

4.1 Nix setup (declarative installation)

The Lilac build pipeline uses Cachix to cache the builds, so that you don't have to build from scratch (the above will still make you compile Lilac from the sources). After installing Cachix, run

🔗
cachix use funloop

to get access to the cached builds (all tagged commits are cached).

And then from your project's Nix configuration, you can bring Lilac into your project's scope with:

🔗
lilacSrc = builtins.fetchGit {
  url = "https://git.sr.ht/~listx/lilac";
  ref = "refs/tags/<<lilac-version>>";
  name = "lilac";
  submodules = true;
};

lilacPkg = import "${lilacSrc}/nix/release.nix" {
  lilacGitVersion = "<<lilac-version>>";
};

where <<lilac-version>> is the version string vX.X.X.X you want to use. The current version is defined at Lilac version, so you should use that one.

4.1.1 Summary

Pros:

Cons:

4.2 Manual setup (imperative installation)

The instructions below are useful for developing Lilac, if you want to submit patches.

Clone this repo. There are 2 ways to install Lilac. The first is with Nix and Cachix. You can just download from the funloop Cachix cache, by running

🔗
cachix use funloop
make build-release
make install-release

The build-release target will end up pulling from the funloop cache (unless CI on main branch is broken).

You can also build with Cabal, by running make install to have Cabal install the lilac binary to disk. For end-users, this is not as desirable because it takes longer.

4.2.1 Summary

Pros:

Cons:

4.3 Using Lilac

Now go to your repo where you want to use Lilac. Run

🔗
lilac init

to generate a starter Lilac.toml and index.org. This will also give you a Makefile, which you can use to run make to start tangling and weaving. You can also do watch -cn 1 make to constantly run make so that you don't have to keep running it yourself.

At this point your index.org is your source of truth, so have a read through it, and adjust as needed.

5 Using Lilac as a static site generator

Because Lilac weaves output to HTML, it makes it suitable for use as a static content generator. An example is https://funloop.org/build.html (source code at https://git.sr.ht/~listx/personal-website).

There are a couple flags for the weave subcommand which are worth mentioning for using Lilac as an SSG:

6 Footnotes

1. For CWEB, it has the cweave utility which then converts this to TeX, after which it can be converted as a PDF. However, both FunnelWeb and Noweb can support any documentation language, not just TeX --- although, you are still required to use that same documentation language directly in your input file. For example, Noweb input files with the *.nw file syntax can be processed by an HTML backend if you have HTML already inside the *.nw files. In a sense both FunnelWeb and Noweb are just text preprocessors --- they have no knowledge of the underlying documentation syntax (HTML, TeX, or otherwise) used in the input files. ↑ Table 1

Page metrics

Backlinks (5)

  1. index.org (2)
    1. ^ Top (2)
      1. ¶ (Cell 3)
      2. ✿ user-manual.org
  2. build.org (1)
    1. fig:lilac-subcommands.pikchr ← ¶ (Cell 100)
  3. fe.org (1)
    1. fig:lilac-subcommands.pikchr ← ¶ (Cell 176)
  4. release-notes.org (1)
    1. § 4 Basic initial setup ← ¶ (Cell 100)

Tangled files (1)

  1. image/lilac-subcommands.pikchr

Named cells (3)

  1. Footnote (fn:web-markup)
  2. fig:lilac-subcommands
  3. fig:lilac-subcommands.pikchr