[help] add option help apart from description #1961

- store all help strings like these on vd.help_foo for easy reuse
- added help for formatting
- mark other needed help strings with HELPTODO

visidata/_types.py

@@ -3,8 +3,19 @@
 import locale
 from visidata import options, TypedWrapper, vd, VisiData
 
-vd.option('disp_float_fmt', '{:.02f}', 'default fmtstr to format for float values', replay=True)
-vd.option('disp_int_fmt', '{:d}', 'default fmtstr to format for int values', replay=True)
+vd.help_float_fmt = '''
+- fmt starting with `'%'` (like `%0.2f`) will use [:onclick https://docs.python.org/3.6/library/locale.html#locale.format_string]locale.format_string[/]
+- other fmt (like `{:.02f}` is passed to Python [:onclick https://docs.python.org/3/library/string.html#custom-string-formatting)]string.format][/]
+'''
+
+vd.help_int_fmt = '''
+- fmt starting with `'%'` (like `%04d`) will use [:onclick https://docs.python.org/3.6/library/locale.html#locale.format_string]locale.format_string[/]
+- other fmt (like `{:4d}` is passed to Python [:onclick https://docs.python.org/3/library/string.html#custom-string-formatting)]string.format[/]
+'''
+
+vd.option('disp_float_fmt', '{:.02f}', 'default fmtstr to format float values', replay=True, help=vd.help_float_fmt)
+vd.option('disp_int_fmt', '{:d}', 'default fmtstr to format int values', replay=True, help=vd.help_int_fmt)
+
 
 vd.numericTypes = [int,float]
 

visidata/aggregators.py

@@ -7,6 +7,7 @@
 from visidata import Progress, Sheet, Column, ColumnsSheet, VisiData
 from visidata import vd, anytype, vlen, asyncthread, wrapply
 
+vd.help_aggrs = 'HELPTODO'
 
 vd.option('null_value', None, 'a value to be counted as null', replay=True)
 

visidata/color.py

@@ -9,6 +9,8 @@
 
 __all__ = ['ColorAttr', 'colors', 'update_attr', 'ColorMaker', 'rgb_to_attr']
 
+vd.help_color = 'HELPTODO'
+
 
 @dataclass
 class ColorAttr:

visidata/features/describe.py

@@ -5,7 +5,7 @@
 from visidata import BaseSheet, TableSheet, ColumnsSheet, SheetsSheet
 
 
-vd.option('describe_aggrs', 'mean stdev', 'numeric aggregators to calculate on Describe sheet')
+vd.option('describe_aggrs', 'mean stdev', 'numeric aggregators to calculate on Describe sheet', help=vd.help_aggrs)
 
 
 @Column.api

visidata/features/scroll_context.py

@@ -18,7 +18,7 @@
 
 from visidata import vd, Sheet
 
-vd.option('disp_scroll_context', 0, helpstr='minimum number of lines to keep visible above/below cursor when scrolling')
+vd.option('disp_scroll_context', 0, 'minimum number of lines to keep visible above/below cursor when scrolling')
 vd.optalias('disp_scrolloff', 'disp_scroll_context')
 
 @Sheet.after

visidata/loaders/f5log.py

@@ -43,6 +43,7 @@ def __new__(cls, value, *args, **kwargs):
     "f5log_object_regex",
     None,
     "A regex to perform on the object name, useful where object names have a structure to extract. Use the (?P<foo>...) named groups form to get column names.",
+    help=vd.help_regex
 )
 vd.option(
     "f5log_log_year",

visidata/optionssheet.py

@@ -52,7 +52,9 @@ def editOption(self, row):
             vd.options.set(row.name, not currentValue, self.source)
         else:
             helpstr = f'# options.{self.cursorRow.name}\n'
-            helpstr += vd.options._get(self.cursorRow.name, 'default').helpstr
+            opt = vd.options._get(self.cursorRow.name, 'default')
+            helpstr += opt.helpstr
+            helpstr += '\n'+opt.extrahelp
             valcolidx = self.visibleCols.index(self.column(self.valueColName))
             v = self.editCell(valcolidx, value=currentValue, help=helpstr)
             vd.options.set(row.name, v, self.source)

visidata/path.py

@@ -10,8 +10,11 @@
 from visidata import vd
 from visidata import VisiData, Progress
 
-vd.option('encoding', 'utf-8-sig', 'encoding passed to codecs.open when reading a file', replay=True)
-vd.option('encoding_errors', 'surrogateescape', 'encoding_errors passed to codecs.open', replay=True)
+vd.help_encoding = 'HELPTODO'
+vd.help_encoding_errors = 'HELPTODO'
+
+vd.option('encoding', 'utf-8-sig', 'encoding passed to codecs.open when reading a file', replay=True, help=vd.help_encoding)
+vd.option('encoding_errors', 'surrogateescape', 'encoding_errors passed to codecs.open', replay=True, help=vd.help_encoding_errors)
 
 @VisiData.api
 def pkg_resources_files(vd, package):

visidata/save.py

@@ -5,7 +5,7 @@
 from visidata import Sheet, BaseSheet, VisiData, IndexSheet, Path, Progress, TypedExceptionWrapper
 
 vd.option('safe_error', '#ERR', 'error string to use while saving', replay=True)
-vd.option('save_encoding', 'utf-8', 'encoding passed to codecs.open when saving a file', replay=True)
+vd.option('save_encoding', 'utf-8', 'encoding passed to codecs.open when saving a file', replay=True, help=vd.help_encoding)
 
 @Sheet.api
 def safe_trdict(vs):

visidata/search.py

@@ -61,7 +61,7 @@ def findMatchingColumn(sheet, row, columns, func):
             vd.status('%s matches for /%s/' % (matchingRowIndexes, regex.pattern))
 
 
-help_regex_flags = '''# regex flags
+vd.help_regex_flags = '''# regex flags
 
 - `A` (ASCII) ASCII-only matching (not unicode)
 - `I` (IGNORECASE): case-insensitive matching
@@ -70,19 +70,17 @@ def findMatchingColumn(sheet, row, columns, func):
 - `X` (VERBOSE): allow verbose regex
 '''
 
-help_regex = 'regex help goes here'
-
 @Sheet.api
 def searchInputRegex(sheet, action:str, columns:str='cursorCol'):
-    r = vd.inputMultiple(regex=dict(prompt=f"{action} regex: ", type="regex", defaultLast=True, help=help_regex),
-                         flags=dict(prompt="regex flags: ", type="regex_flags", value=sheet.options.regex_flags, help=help_regex_flags))
+    r = vd.inputMultiple(regex=dict(prompt=f"{action} regex: ", type="regex", defaultLast=True, help=vd.help_regex),
+                         flags=dict(prompt="regex flags: ", type="regex_flags", value=sheet.options.regex_flags, help=vd.help_regex_flags))
 
     return vd.searchRegex(sheet, regex=r['regex'], regex_flags=r['flags'], columns=columns)
 
 @Sheet.api
 def moveInputRegex(sheet, action:str, type="regex", **kwargs):
-    r = vd.inputMultiple(regex=dict(prompt=f"{action} regex: ", type=type, defaultLast=True, help=help_regex),
-                         flags=dict(prompt="regex flags: ", type="regex_flags", value=sheet.options.regex_flags, help=help_regex_flags))
+    r = vd.inputMultiple(regex=dict(prompt=f"{action} regex: ", type=type, defaultLast=True, help=vd.help_regex),
+                         flags=dict(prompt="regex flags: ", type="regex_flags", value=sheet.options.regex_flags, help=vd.help_regex_flags))
 
     return vd.moveRegex(sheet, regex=r['regex'], regex_flags=r['flags'], **kwargs)
 

visidata/settings.py

@@ -106,10 +106,12 @@ def __init__(self, longname, execstr, helpstr='', module=''):
 
 
 class Option:
-    def __init__(self, name, value, helpstr='', module='', max_help=10):
+    def __init__(self, name, value, description='', module='', help='', max_help=10):
+        # description gets shows on the manpage and the optionssheet; help is shown on the sidebar while editing
         self.name = name
         self.value = value
-        self.helpstr = helpstr
+        self.helpstr = description
+        self.extrahelp = help
         self.replayable = False
         self.sheettype = BaseSheet
         self.module = module
@@ -287,7 +289,7 @@ def _resolve_optalias(vd, optname, optval):
 
 
 @VisiData.api
-def option(vd, name, default, helpstr, replay=False, sheettype=BaseSheet, max_help=10):
+def option(vd, name, default, description, replay=False, sheettype=BaseSheet, help:str='', max_help=10):
     '''Declare a new option.
 
    - `name`: name of option
@@ -296,16 +298,19 @@ def option(vd, name, default, helpstr, replay=False, sheettype=BaseSheet, max_he
    - `replay`: ``True`` if changes to the option should be stored in the **Command Log**
    - `sheettype`: ``None`` if the option is not sheet-specific, to make it global on CLI
     '''
-    opt = vd.options.setdefault(name, default, helpstr, vd.importingModule)
+    opt = vd.options.setdefault(name, default, description, vd.importingModule)
     opt.replayable = replay
     opt.sheettype=sheettype
+    opt.extrahelp = help
     opt.max_help = max_help
     return opt
 
 
 @VisiData.api
-def theme_option(vd, *args, **kwargs):
-    return vd.option(*args, **kwargs, max_help=-1)
+def theme_option(vd, name, *args, **kwargs):
+    if name.startswith('color_'):
+        kwargs.setdefault('help', vd.help_color)
+    return vd.option(name, *args, **kwargs, max_help=-1)
 
 
 @BaseSheet.class_api

visidata/text_source.py

@@ -2,8 +2,9 @@
 
 from visidata import vd, BaseSheet
 
+vd.help_regex = 'HELPTODO'
 
-vd.option('regex_skip', '', 'regex of lines to skip in text sources')
+vd.option('regex_skip', '', 'regex of lines to skip in text sources', help=vd.help_regex)
 
 class FilterFile:
     def __init__(self, fp, regex:str, regex_flags:int=0):

visidata/type_currency.py

@@ -1,6 +1,6 @@
 from visidata import vd, Sheet, Column
 
-vd.option('disp_currency_fmt', '%.02f', 'default fmtstr to format for currency values', replay=True)
+vd.option('disp_currency_fmt', '%.02f', 'default fmtstr to format for currency values', replay=True, help=vd.help_float_fmt)
 vd.theme_option('color_currency_neg', 'red', 'color for negative values in currency displayer', replay=True)
 
 

visidata/type_date.py

@@ -11,8 +11,23 @@ def date_parse(vd):
         vd.warning('install python-dateutil for date type')
         return str
 
-
-vd.option('disp_date_fmt','%Y-%m-%d', 'default fmtstr to strftime for date values', replay=True)
+vd.help_date = '''
+- RFC3339: `%Y-%m-%d %H:%M:%S.%f %z`
+- `%A`  Weekday as locale’s full name.
+- `%w`  Weekday as a decimal number, where 0 is Sunday and 6 is Saturday.
+- `%d`  Day of the month as a zero-padded decimal number.
+- `%b`  Month as locale’s abbreviated name.
+- `%B`  Month as locale’s full name.
+- `%p`  Locale’s equivalent of either AM or PM.
+- `%c`  Locale’s appropriate date and time representation.
+- `%x`  Locale’s appropriate date representation.
+- `%X`  Locale’s appropriate time representation.
+- `%Z`  Time zone name (empty string if the object is naive).
+
+See [:onclick https://strftime.org]Python strftime()[/] for a full list of format codes.
+'''
+
+vd.option('disp_date_fmt','%Y-%m-%d', 'default fmtstr passed to strftime for date values', replay=True, help=vd.help_date)
 
 
 @vd.numericType('@', '', formatter=lambda fmtstr,val: val.strftime(fmtstr or vd.options.disp_date_fmt))