Generated Configuration File

Some notes follow about the whenever configuration files generated by When.

  • The generated configuration files are well-formed TOML files: this means, for instance, that they can be re-edited by hand and, if the result is still well-formed and compliant to the format used by whenever, used to configure the scheduler. However there are some peculiarities that have to be taken into account:

    • most of the times When tries to produce appropriate and readable strings in TOML files: most script-like entries are formatted using multiline literal strings, and commands (and command arguments) also tend to be literal strings, even though in some cases, when it is hard to use a literal string, it will produce plain escaped strings;

    • lists of small TOML tables (such as parameter/result check arrays) are rendered as multiline arrays of inline TOML tables, for the sake of readability: plain TOML tables (especially the tags tables) are rendered using the extended TOML syntax for tables;

    • When will try to omit an entry if its value is the default value as specified in the whenever documentation, in order to avoid excessively cluttered configuration files;

    • generally (but there might be some exceptions), the format used for an item remains the same as it was found in the configuration file when it was loaded: this means that most of the times, if users modify parts of the configuration file (for example: scripts) to suit their taste, the modified format will remain the same until they re-edit the item in the GUI.

  • When uses the tags configuration entry for specialized items built on top of the ones that are native to whenever: of course, it also sets the standard parameters known to whenever (it ignores the contents of the tags entry), and the user can modify any of these standard parameters by hand if needed: whenever will obey these changes when using the resulting configuration files even when it is launched using When as frontend; however, as soon as When re-reads the file for editing, it will ignore all the changes that have been made to the standard parameters and reuse the ones that are calculated according to the values stored in the tags section.

  • Since the files generated by When are just standard whenever oriented configuration files, they can be used with any frontend and even with no frontend at all, by just respectively instructing the chosen frontend (for example, whenever_tray) or whenever itself to use the %APPDATA%\Whenever\whenever.toml or ~/.whenever/whenever.toml configuration file depending on the host platform.

This means, for instance, that When can also be used as a way to start configuring the scheduler only for the first time, and that the resulting configuration file can then be edited and enhanced manually to suit the user’s needs. Also note that if the tags table is completely removed from the definition of an item, that item will still work in whenever. The only drawback is that When will not be able to edit that item using the specific editor and, if supported, the editor for the corresponding standard item is used.

Legacy Configuration Files

During the development of When, especially in case any new features are added to the actual whenever scheduler, some of the item definitions for items specific to When[1] in the configuration files may change, in order to use more efficient or lightweight ways to achieve the same result. In this case, provided that the prerequisites for the legacy version of a changed item are still verified, using the old configuration file does not affect the expected behavior of the scheduler. Instead, it may become impossible to use the GUI to edit these items because When does not recognize them anymore.

In order to be able to use the configuration utility it may be necessary to fix the configuration file using the provided --fix-config tool from the command line.

See Also

◀ Main