*markx.txt* MarkX : Mark placement enhancements
*markx*

Author:  Richard Bentley-Green
Version: 22/03/2023

==============================================================================
CONTENTS                                                       *markx-contents*

Introduction        |markx-introduction|
Mappings            |markx-mappings|
Commands            |markx-commands|

==============================================================================
INTRODUCTION                                               *markx-introduction*

The primary purpose of MarkX is to automatically place a sign in the left
margin for each mark that is set, and to ensure that the displayed signs
reflect the on-going state as marks are added and removed

MarkX also includes some functions to make auto-selection and placement of
marks, so you don't have to remember which marks you've used

`This help page is intended only as a quick reference to the mappings - See the`
`README file for complete details, inc. configuration`

==============================================================================
MAPPINGS                                                       *markx-mappings*

In the following description *[N]* indicates Normal mode, and *[V]* indicates
visual selection mode. The name of each mapping is shown as [name] to
allow it to be overridden/manually set

In the following description, `*` represents a single mark name

- The marks 'a' to 'z' and all the 'punctuation' marks are 'local' to the
  buffer
- The marks 'A' to 'Z' and '0' to '9' are 'global' and only one of each
  exists in a vim session
- Only the marks 'a' to 'z', 'A' to 'Z and the 6 'punctuation' marks
  ' ` < > [ ] can be controlled (set/deleted) by the user

PLACING MARKS~

`m*`          *[N/V]* Set the mark `*` at the current cursor position. This is the
            only mapping that overrides a standard vim operation. It only does
            this so that an associated sign can be placed when a mark is set.
            Other than that, it should operate in exactly the same way as the
            standard command

            Note that this operation will set the mark regardless of whether
            SelX is configured to set a sign for it or not. This is also true
            of other mappings/commands that set marks

            See `:help m` for further details
            [MarkXAdd]

`<leader>mm`  *[N]* Auto-place a mark in the range 'a' to 'z' (or a subset of
            this - see `g:MarkxAutoLMarks`).
            Auto-placement starts with the first mark (by default 'a') with
            subsequent auto-placements placing successive marks in order. The
            selection wraps-around back to the start again once the list is
            exhausted
            Auto-placement shall always attempt to use a currently unplaced
            mark. As such, it will skip any marks in the sequence if they are
            not free. If there are no free marks in the range 'a' to 'z' then
            the operation shall fail and issue a warning. This behaviour can
            be changed by enabling the `g:MarkxAutoLForce` configuration
            setting. If this is set then the auto-placement shall start to
            recycle (move) existing marks when there are no free ones
            remaining
            [MarkXAdda]

`<leader>mM`  *[N]* Auto-place a mark in the range 'A' to 'Z' (or a subset of
            this - see `g:MarkxAutoUMarks`)
            In all other respects, this operates in the same way as
            `<leader>mm`. See also the  `g:MarkxAutoUForce` configuration setting
            [MarkXAddA]

DELETING MARKS~

`<leader>md*` *[N]* Delete the mark `*`. 'Local' marks are only deleted from the
            current buffer. 'Global' marks will be deleted regardless of which
            buffer they are assigned to (if any)
            [MarkXDel]

`<leader>ma ` *[N]* Delete all the marks 'a' to 'z' (or the subset of this
            range as specified by the `g:MarkxDisplayMarks` configuration
            option)
            If the `g:MarkxConfirmDelAll` option is set then confirmation shall
            be sought before proceeding with the operation
            [MarkXDelAllL]

`<leader>mA ` *[N]* This operates exactly the same as `<leader>ma` but for the marks
            'A' to 'Z'
            [MarkXDelAllU]

`<leader>mp ` *[N]* This operates exactly the same as `<leader>ma` but for the marks
            ' ` < > [ ]
            [MarkXDelAllP]

`leader>mq `  *[N]* This operates exactly the same as `<leader>ma` but only for
            the auto-placement marks 'a' to 'z'. This only makes sense if the
            configuration `g:MarkxAutoLMarks` is defined to be a subset of the
            whole mark list. Otherwise it operates exactly as `<leader>ma`
            [MarkXDelAllAutoL]

`leader>mQ `  *[N]* This operates exactly the same as `<leader>mA` but only for
            the auto-placement marks 'A' to 'Z'. This only makes sense if the
            configuration `g:MarkxAutoUMarks` is defined to be a subset of the
            whole mark list. Otherwise it operates exactly as `<leader>mA`
            [MarkXDelAllAutoU]

REFRESH DISPLAY~

The following shouldn't be necessary in normal use, but nonetheless...

`<leader>m~`  *[N]* Re-assess all marks in the current buffer and add, move or
            delete any associated signs as required
            [MarkXRefresh]

`<leader>m#`  *[N]* Re-assess all marks in all buffers and add, move or delete
            any associated signs as required
            [MarkXRefreshAll]

OTHER~

`<leader>m@`  *[N]* Toggle 'Display signs for ALL currently placed marks'.
            This operates per-buffer and when active, overrides any
            configuration that specifies which marks to display signs for,
            instead displaying signs for ALL marks of ALL types

==============================================================================
COMMANDS                                                       *markx-commands*

A number of the configuration settings are evaluated dynamically as and when
the effected mappings are used. The following commands will toggle these
configuration settings

For full details of these configuration settings, see the `README` file

`MarkXToggleAutoForce`
    Toggle the `g:MarkxAutoLForce` configuration setting. This controls
    whether or not auto-selection shall move (recycle) existing mapped marks
    or not

`MarkXToggleSteponAuto`
    Toggle the `g:MarkxSteponAuto` configuration setting. This controls
    whether or not the auto-selection mappings' mark selection is adjusted
    by manual mark placement or not

`MarkXToggleDelAllConfirm`
    Toggle the `g:MarkxConfirmDelAll` configuration setting. This controls
    whether or not confirmation shall be sought for the 'delete all' mappings;
    `<leader>ma`, `<leader>mA`, `<leader>mp` `<leader>mq`, and `<leader>mQ`

`MarkXToggleDelUGlobal`
    Toggle the `g:MarkxDelAllUGlobal` configuration settingv. This controls
    whether or not the `<leader>mA` and `<leader>mQ`  mappings shall operate
    only on the local buffer or globally
