Revisions: 2                Implicit Provenance Tag                 Éric NICOLAS
Latest: 2025-08-06          =======================                Jan Heuermann

                             Segregation strategies
                         for multi-source Klog commands
                                      ---

0. Set-Up ----------------------------------------------------------------------

    The time is 18:00.

    file: @default                      file: @work -> /path/to/work.klg
    --------------                      -----------
    2025-01-01                          2025-01-01 (8h!)
        30m #social Grandpa called          30m #commute
        45m #workout                        09:00 - ?
        1h30m netflix                       -1h lunch
                                            20:00-21:00 afterwork #social


1. Use-Case --------------------------------------------------------------------

1.1. Implicit tag for Entries in multi-source processing .......................

    CURRENT output:                     PROPOSED output:
    ---------------                     ----------------
    #social    1h30m                    #social  1h30m
    #workout     45m                    #workout   45m
    #commute     30m                    #commute   30m
    (untagged) 9h30m                    @default 1h30m
                                        @work    8h00m

    My end goal would be to have a neat little indicator that goes over my
    bookmarks and shows me how long I've been #work-ing today ;)


2. Proposal --------------------------------------------------------------------

    We propose to introduce a flag to the commands that may process an arbitrary
    number of sources.  That flag would be understood by the more generic
    input parsing system, and have the internal, in-memory data model remember
    the original partitioning of its collected Records, for possible refined
    processed by the invoked command.

    The flag's name is not finalised yet, but strong candidates are:

        --split
        --no-merge

    In the rest of this document, we'll use --split to enable this flag.

    When set, the several commands will be at liberty to use this new data.  One
    example would be that of the tags command, where we could imagine wanting to
    pool the tagged entries from all sources, which is the current behaviour,
    but aggregate the remaining ones by their origin.  The rest of this document
    will outline how this possible use-case may behave.


2.1. The (possible) case of klog tags ------------------------------------------

    In case Klog is to process the content from either the implied @default
    bookmark or a single bookmark or file:

        klog tags
        klog tags misc.klg
        klog tags @misc

    Then when --split isn't set,

        The --with-untagged flag adds a line in its output to tally the duration
        of the processed Entries that were deprived of tags.  These durations
        are pooled together and shown under the (untagged) label.  This is the
        behaviour currently implemented.

    Or when --split is set,

        These same untagged durations are now shown under a label carrying an
        identifier for their source, either a bookmark or file path.

    When Klog processes content from its standard input, these remaining
    untagged Entries are aggregated under the (untagged) umbrella.  This is the
    behaviour currently implemented.

        echo '2025-01-01\n    8h #work' | klog tags


2.2. With several inputs .......................................................

    Without --with-untagged, the command will forgo tallying untagged Entries,
    as is currently the case.

    The precise behaviour of --with-untagged will now be driven by the upstream
    --split flag:

    (A) split UNSET with-untagged UNSET     Don't process untagged entries.
    (B) split UNSET with-untagged   SET     Pool untagged entries together.
    (C) split   SET with-untagged UNSET     Don't process untagged entries.
    (D) split   SET with-untagged   SET     Aggregate untagged Entries by their
                                            source.

    For completeness, here's how the "tags" command *currently* behave:

    (A)  klog tags @default @work    --now
    (B)  klog tags @default @work    --now --with-untagged
    (C)  klog tags @default @work    --now                 --split
    (D)  klog tags @default @work    --now --with-untagged --split
    (D2) klog tags @default /abc.klg --now --with-untagged --split

    Output (A)         Output (B)         Output (C)    Output (D)    Output (D2)
    ----------------   ----------------   -----------   -----------   -----------
    #social    1h30m   #social    1h30m   UNSUPPORTED   UNSUPPORTED   UNSUPPORTED
    #workout     45m   #workout     45m
    #commute     30m   #commute     30m
                       (untagged) 9h30m

    Here's how we propose it would behave after the introduction of --split:

    Output (A)         Output (B)         Output (C)       Output (D)       Output (D2)
    ----------------   ----------------   --------------   --------------   --------------
    #social    1h30m   #social    1h30m   #social  1h30m   #social  1h30m   #social  1h30m
    #workout     45m   #workout     45m   #workout   45m   #workout   45m   #workout   45m
    #commute     30m   #commute     30m   #commute   30m   #commute   30m   #commute   30m
                       (untagged) 9h30m                    @default 1h30m   @default 1h30m
                                                           @work    8h00m   /abc.klg 8h00m


                                                          vim: tw=80 sw=4 et sta