Noherring.com code warehouse

Soho usage and configuration file

This page is a reference of all command-line options and configuration file settings of Soho. You may want to read the tutorial before.

Usage

The most simple usage of Soho is to call it without any parameter: soho. It will then use sensible default values and log what it does in the standard output. See the sections below to know more about the default values and the possible command-line options.

Note

Remember that you can always type soho --help: it prints a listing of all available settings. For further details, see below.

Configuration file

Soho first tries to read a configuration file. Its default name is soho.conf and it is supposed to live in the current working directory. However, you can provide the path of the configuration file to be read with the -c option:

$ soho -c /path/to/soho.conf

The configuration file uses the classic INI file format:

[main]
template = main_template.pt
bindings = mybindings.py
filters = myfilters.py

Warning

The main section is required. In the future, we might get rid of this useless section (since it is currently unique), or we might add other sections if there are much more settings. Anyway, right now it is not optional and must be provided. In fact, you will get an error if you do not and the program will stop.

Order of processing

Almost all settings can be configured in the configuration file or via command-line options and are processed in this order:

  1. Soho tries to read a configuration file.
  2. It then overrides settings with those given via the command-line options.
  3. If some options are still missing, default values are chosen.

It is quite convenient when you want to test a particular setting without changing the configuration file, work in another output directory and/or perform a dry run.

Available configuration settings

Source directory

By default, source files are supposed to be in a src/ sub-directory of the current working directory (that means ./src/). This setting lets you set another source directory via the command-line:

$ soho -i ~www/input

... or via the configuration file:

[main]
in_dir = ~www/input

By default, all text files (.txt and .rst files) are supposed to be source files and are processed to generate HTML files. Other files and directories are simply copied to the output directory. See Directories and files to ignore section below.

Output directory

By default, Soho will write generated files in a www/ sub-directory of the current working directory (that means ./www/). This setting lets you set another output directory via the command-line:

$ soho -o ~www/public_html

... or via the configuration file:

[main]
out_dir = ~www/public_html

If this directory does not exist, it is created.

Template file

By default, Soho will use the file main_template.pt in the current working directory as the template. This setting lets you use another template file via the command-line:

$ soho -t brand-new-template.pt

... or via the configuration file:

[main]
template = brand-new-template.pt

Bindings file

By default, no binding is included in the template. In particular, built-in bindings are not included. You have to define a bindings file that lists them (see the Bindings chapter for further details) and tell Soho to use it via the command-line:

$ soho --bindings mybindings.py

... or via the configuration file:

[main]
bindings = mybindings.py

Filters file

By default, no filter is used during the processing of the files. In particular, built-in filters are not used. You have to define a filters file that lists them (see the Filters chapter for further details) and tell Soho to use it via the command-line:

$ soho --filters myfilters.py

... or via the configuration file:

[main]
filters = myfilters.py

Directories and files to ignore

As mentioned above, Soho processes all files. However, there are directories (e.g. .svn/ directories) and/or files (Vi *.swp or Emacs *~ backup files, depending on your religion) that you may want to ignore. There is no command-line option for that: you have to use the configuration file:

[main]
ignore_directories = .*\.svn.*
ignore_files = (\.DS_Store)|(.*~$)

These values must be valid regular expressions. Soho will:

  • ignore a directory if its complete path matches the ignore_directories;
  • ignore a file if its base name (not its complete path) matches ignore_files.

The values in the example above are in fact the default values.

Log file

By default, Soho logs what it does in the standard output. This setting lets you set the file where Soho should log instead, via the command-line:

$ soho -l /tmp/soho-out.log

... of via the configuration file:

[main]
logfile = /tmp/soho-out.log

Soho appends logs to the file, it does not overwrite it.

Force processing

By default, Soho will not process a source file if it has not been modified since the last time HTML version has been generated. That is what it says when you see this kind of line in the log:

Ignoring "src/soho/bindings.txt" because previously generated file seems to be up to date.

However, you may want to force the processing of all files, e.g. if you have made changes to the template, the bindings, the filters or the configuration file in general. You can use the command-line:

$ soho -f

... or the configuration file:

[main]
force = True

Dry run

You may want to test what Soho would do (on a particular set of source files, with a particular setting, etc.), but without actually writing or copying any file. This option lets you do this. Note that Soho will still log what it would have done (e.g. indicating that it has processed or copied files), but the first line of the log will hopefully tell you that nothing will be done, in fact:

Dry run. No files will be harmed, I promise.

To do that, use the command-line:

$ soho -d

... or the configuration file:

[main]
do_nothing = True

Additional command-line arguments

As mentioned above, a brief listing of the available options of Soho is available via:

$ soho --help

And if you are not sure what version you are currently running:

$ soho --version