CROSSBOW.CONF(5)           File Formats Manual (urm)          CROSSBOW.CONF(5)

NAME
     crossbow.conf ? configuration file for crossbow(1)

DESCRIPTION
     crossbow(1) attempts to load the configuration from ~/.crossbow.conf,
     ${XDG_CONFIG_HOME}/crossbow.conf, or ~/.config/crossbow.conf in that
     order.  The configuration file is case sensitive.  Lines can be indented
     by any number of white-spaces (according to the isspace(3) definition).
     Empty lines, and lines starting with ?#? are ignored.

     Settings are defined by statements in the form

         key value

     A single white-space character separates the key from the value.
     Everything that follows the separator, up to the next line-feed character
     is considered part of the value, including any surrounding white-space.

     The configuration can define global settings and multiple feed sections,
     one for each monitored feed.  Global settings are defined in the
     beginning of the configuration file.  The first encountered feed key
     introduces the first feed section.  All the subsequent settings, up to
     the next occurrence of the feed key or the end of the file, affect the
     declared feed.

     Setting whose value represents a path on the filesystem are subject to
     tilde expansion: if the value is prefixed with "~/", the ?~? character is
     expanded with the content of the $HOME environment variable.  Relative
     paths are interpreted relative to the directory where crossbow(1) is
     invoked.

   Global settings
     jobs N
        Define the maximum number of concurrent feed XML retrievals.

        Defaults to 10.

     persist_dir path
        Define the path where crossbow(1) will persist the seen entry
        identifiers for each monitored feed.

        Defaults to ~/.crossbow

   Feed settings
     chdir path
        If the feed handler is exec or pipe, execute the subprocess in the
        given directory.

        Defaults to ./

     command format-string
        If the feed handler is exec or pipe, use format-string as a command
        template, expanding it into the argument vector of the subprocess.

        The template is split on white-space, with the first item being the
        command to execute and the subsequent items being the arguments.  The
        accepted syntax allows to use printf(3)-like placeholders that are
        substituted with the fields of the processed entry, so that they can
        be made available to the subprocess.

        Security remark: Doing proper shell escaping against untrusted input
        is really hard, if not impossible, which is why the template is not
        parsed by means of a shell interpreter.  Constructing an interpreted
        code snippet within a command template (e.g. by invoking "sh -c") is
        strongly discouraged, as it might result in accidental or malicious
        code injection.

        See crossbow-format(5).

     feed name
        Declare a new feed.

        This setting is special in that it marks the beginning of a feed
        section in the configuration file.  Every settings that follows, up to
        the next feed section or to the end of file (whichever comes first)
        will be applied to the declared feed.

        The provided name identifies the feed.  All feeds must have distinct
        names.  Feed names are forbidden to contain the ?/? character.

     format format-string
        If the feed handler is print, use format-string as a template for the
        textual representation of each handled feed entry.  The template uses
        the same printf(3)-like syntax as the command setting.  See
        crossbow-format(5).

        This setting is optional: if not provided, the print handler will use
        the default representation.

     handler handler
        Use the selected handler to process new feed entries.  The handler
        argument must be one of the following:

        print
           Print a textual representation of each new entry to stdout(3).  A
           custom template can optionally be defined by specifying a format
           setting.

           This is the default handler for feeds that do not define one.

        exec
           Handle new entries by means of a subprocess.  This handler requires
           the command setting to be defined.

        pipe
           Like exec, but the whole content is made available to the
           subprocess by means of a pipe(2), besides by the regular %d
           placeholder.  This handler requires the command setting to be
           defined.

     url URL
        Define the URL of the feed XML.

        The allowed remote protocols are HTTP, HTTPS, and Gopher (using the
        "http://", "https://" and "gopher://" URL schemas respectively).
        Local file-system access (using "file://")is possible too.  HTTPS is
        the default protocol when no schema is specified.

        This setting must be defined for each feed.

SEE ALSO
     crossbow(1), crossbow-format(5), crossbow-cookbook(7)

AUTHORS
     Giovanni Simoni <dacav@fastmail.com>

                               October 20, 2021