Contribute to the documentation

The documentation is a set of static webpages generated from a simple wiki-like syntax called textile. See a textile reference.

Generating the pages

You need pubtal, available as a debian package for instance.

In the documentation directory (currently trunk/website or trunk/liquidsoap/doc, you can simply run make.

The texts are found in the content/ folder, and html templates in templates/. The resulting webpages are in html/.

The build system does not detect modified pages, so you will need to call make clean before rebuilding the pages.

unsupported hash version: xx

This error sometimes happen when building the html pages. This is due too an inconsistent cache in PubTalData. Running make clean or deleting this folder fixes the issue..

Adding code snipets

Files in content/ are parsed for code snipets. When a snipet is found, it is extracted and available in the scripts/ directory.

To add a code snipet in your text, simply write: 

%%(snipet_name.ext)
-> Code here.. <-
%%

The name of the snipet should makes it understandable what it's for, and should be unique in the documentation. Also, extension matters. Current recognized extensions are:

  • .liq for liquidsoap code snipets
  • .sh for bash code snipets.
  • .pl for perl snipets.

After building the pages, you can test if the snipet syntax is correct by using: make test.

Some scripts may need to be bypassed. Simply add their names in scripts/test_snipets. However, there should not be a lot of scripts in this case, hence this very hacky registration..

Convert pages from the old wiki to the new doc format

There is a script that does most of the parsing, in the documentation scripts section, called wiki2text

To use it, first copy the text of the wiki page you want to convert to a file, let say /tmp/page.wiki.

Beware that the copy from wiki may introduce utf8 invisible character at the begining of the wiki file.

Then run the script with this file as argument: wiki2text /tmp/page.wiki. The standard output should display the converted text.

If you are ok with the translation, just do wiki2text /tmp/page.wiki > /tmp/page.txt.

You can then rename all script inclusions %%(name.ext) that have been autoatically generated by wiki2text