.. -*- coding: utf-8; -*-
.. highlight:: ini

.. _configuration:

#####################
General configuration
#####################

*******************
Configuration files
*******************

Oh My CAD makes extensive use of configuration files. Configuration
files are plain text files that you can edit using a simple text
editor like Notepad.exe, `Notepad++`_, `GNU Emacs`_ and `many
others`_. Avoid using a `word processor`_ to edit configuration files.

Configuration files contain one or more sections, defined by a line
with ``[Section Name]``. Each section contains one or more options,
which take the format ``Name = Value``. For example::

  [pencils]
  yellow = 0.9 mm
  blue = 0.7 mm
  black = 0.5 mm
  dark green = 0.3 mm

  [ballpoint pens]
  colors = blue
           black
           red
  refill = yes

  [markers]
  red = error
  yellow = incomplete
  green = good
  blue = out of scope

Leading spaces on any line are ignored, so you can indent your lines
to visually group sections or options if you want. Multiline values
are written by indenting the lines below the option name with at least
one whitespace character as in the example above.

You can write comments by starting the line with a hash sign (``#``)
or a semicolon (``;``) as the first non-space character of the line.
To disable an option, you may comment it out by putting a ``#`` at the
start of the line instead of deleting it.

Depending on the specific option and how it is used, the ``Name`` and
``Value`` texts may be case-sensitive or case-insensitive so it is
best to treat them as case-sensitive. If an option is commented out or
omitted, the default value for the option will be used.

For more information, you can check Wikipedia's article on `INI
file`_. This implementation is based on Python's configparser library
so you can also read more about the supported file structure in its
`documentation`_.

Make a backup copy of your configuration files before editing it, so
that you have a working file in case a change you make happens to have
unintended effects. Hopefully you won't need to edit the configuration
files very often after creating them with your initial options. For
frequent changes, it may be better to make a macro, alias or command
function than to change themes back and forth.

.. _notepad++: https://notepad-plus-plus.org/
.. _GNU Emacs: https://www.gnu.org/software/emacs/
.. _many others: https://en.wikipedia.org/wiki/List_of_text_editors
.. _word processor: https://en.wikipedia.org/wiki/Word_processor
.. _INI file: https://en.wikipedia.org/wiki/INI_file
.. _documentation:
   https://docs.python.org/3/library/configparser.html#supported-ini-file-structure

Paths
=====

In configuration files handled by Oh My CAD, all relative paths are
relative to the directory that contains the *themes.conf* selected.

File and directory paths in any configuration file used by Oh My CAD
can be written in one of two ways: absolute or relative. Absolute
paths start at the filesystem root, the drive letter, and point to the
same location regardless of the location of any other directory.
Relative paths specify only the final part of a path and the program
must refer to some other directory to determine the exact location it
points to. For more information, see `this article`_.

.. _this article:
   https://en.wikipedia.org/wiki/Path_%28computing%29#Absolute_and_relative_paths

******
Themes
******

Oh My CAD works with a central theme engine for all configuration
options. The configurations in a theme need not be for appearance
only, they can also alter the bahavior of commands and settings
without direct visual effect. The theme engine may also be used by
other applications or by your own extensions to enable persistent
configuration. The storing program state and input/output in the form
of configuration files.

Defining a theme
================

All themes are defined in the file *themes.conf* that must be created
and pointed to by the user with the command *THEME*. In *themes.conf*,
each section is a theme, and the option values point to the
configuration directories that should be searched. The option names in
*themes.conf* are not currently used and can have any name, but must
not be duplicated. A simple *themes.conf* example would be::

   [jane's theme]
   1 = c:\config_team
   2 = c:\config_jane

   [john]
   1 = c:\config_team
   2 = c:/config_john
   3 = extensions/work

The *THEME* command is also used to choose which theme is active from
the ones defined in *themes.conf*.

The active theme is looked for in *themes.conf* and, if found, it is
processed with the following procedure:

* The directories listed for the active theme in *themes.conf* are
  visited in the order they are written.
* Each directory is searched for files with *.conf* extension.
* Each file found is parsed and its name, sections and options are
  stored in the theme structure. The name of the file becomes the name
  of a configuration group.
* Files with the same name in different directories result in a
  configuration group that is a merge of the sections and options of
  all these files, each one overwriting the ones that came before it
  if necessary. See the examples below.

This procedure assembles the final theme structure.

Theme structure
===============

A theme is a rooted tree graph of three levels: groups, sections and
options.

.. figure

The name of each file is the name of a configuration group.

Simple example
==============

Complex example
===============

Graphical interface
===================