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.

.. _tutorial: tutorial.txt


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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [main]
    bindings = mybindings.py


.. _Bindings: bindings.txt


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:

.. sourcecode:: ini

    [main]
    bindings = myfilters.py


.. _Filters: filters.txt


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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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:

.. sourcecode:: ini

    [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
