README.rst

   1 ..
   2   ###################################################################
   3   Copyright 2015, Pierre Gentile (p.gen.progs@gmail.com)
   4
   5   This Source Code Form is subject to the terms of the Mozilla Public
   6   License, v. 2.0. If a copy of the MPL was not distributed with this
   7   file, You can obtain one at https://mozilla.org/MPL/2.0/.
   8   ###################################################################
   9
  10 .. image:: smenu.gif
  11
  12 |
  13
  14 .. image:: simple_menu.gif
  15
  16 What is it?
  17 ===========
  18 **smenu** is a selection filter just like ``sed`` is an editing filter.
  19
  20 This tool reads words from standard input or from a file, and presents
  21 them to the terminal screen in different layouts in a scrolling window.
  22 A cursor, easily moved using the **keyboard** and/or the **mouse**,
  23 makes it possible to select one or more words.
  24
  25 Note that the screen is not cleared at the start and end of **smenu**
  26 execution.
  27 The selection window is displayed at the cursor position, and the
  28 previous contents of the terminal are neither modified nor lost.
  29
  30 I've tried to make it as easy to use as possible.
  31 It should work on all terminals managed in the ``terminfo`` database.
  32
  33 ``UTF-8`` encoding is supported.
  34 This support includes double-width characters and extended grapheme
  35 clusters. The latter is still experimental, however, and works much
  36 better if appropriate terminals such as WezTerm or iTerm are used.
  37
  38 The encoding of ``UTF-8`` glyphs must also be in canonical form, as no
  39 effort will be made to put them in this form.
  40
  41 Please refer to the included man page to find out more about this little
  42 program.
  43
  44 The `wiki <https://github.com/p-gen/smenu/wiki>`_ contains screenshots and
  45 animations that detail some concepts and features of **smenu**.
  46
  47 How to build it?
  48 ================
  49 Some Linux distributions already provide **smenu** as a package,
  50 if not, **smenu** can be built on any system on which a functional
  51 ``terminfo`` development platform is available.
  52 This includes all Unix and Unix-like systems that I know of.
  53
  54 Please use the provided ``build.sh`` script to build the executable.
  55 This script uses and accepts the same arguments as the GNU ``configure``
  56 script, type ``build.sh --help`` to see them.
  57
  58 How to install it?
  59 ==================
  60 Once the build process is complete, a simple ``make install`` with the
  61 appropriate privileges will do it.
  62
  63 Issue vs Discussion.
  64 ====================
  65 I have enabled `discussions <https://github.com/p-gen/smenu/discussions>`_
  66 on this repository.
  67
  68 I am aware there may be some confusion when deciding where you should
  69 communicate when reporting issues, asking questions or raising feature
  70 requests so this section aims to help us align on that.
  71
  72 Please `raise an issue <https://github.com/p-gen/smenu/issues>`_ if:
  73
  74 - You have found a bug.
  75 - You have a feature request and can clearly describe your request.
  76
  77 Please `open a discussion <https://github.com/p-gen/smenu/discussions>`_ if:
  78
  79 - You have a question.
  80 - You're not sure how to achieve something with smenu.
  81 - You have an idea but don't quite know how you would like it to work.
  82 - You have achieved something cool with smenu and want to show it off.
  83 - Anything else!
  84
  85 Some examples.
  86 ==============
  87
  88 Linux example.
  89 --------------
  90 This program should work on most Unix but if you are using Linux,
  91 try to type the following line at a shell prompt (here: ``"$ "`` ):
  92
  93 ::
  94
  95   $ R=$(grep Vm /proc/$$/status \
  96         | smenu -n20 -W $':\t\n' -q -c -b -g -s /VmH)
  97   $ echo $R
  98
  99 Something like this should now be displayed with the program waiting
 100 for commands: (numbers are mine, yours will be different)
 101
 102 ::
 103
 104   VmPeak¦    23840 kB
 105   VmSize¦    23836 kB
 106   VmLck ¦        0 kB
 107   VmHWM ¦     2936 kB
 108   VmRSS ¦     2936 kB
 109   VmData¦     1316 kB
 110   VmStk ¦      136 kB
 111   VmExe ¦       28 kB
 112   VmLib ¦     3956 kB
 113   VmPTE ¦       64 kB
 114   VmSwap¦        0 kB
 115
 116 A cursor should be under ``"VmHWM "``.
 117
 118 After having moved the cursor to ``"      136 kB"`` and ended the program
 119 with ``<Enter>``, the shell variable R should contain: ``"      136 kB"``.
 120
 121 Unix example.
 122 -------------
 123 The following command, which is Unix brand agnostic, should give you a
 124 scrolling window if you have more than 10 accounts on your Unix with a
 125 UID lower than 100:
 126
 127 ::
 128
 129   $ R=$(awk -F: '$3 < 100 {print $1,$3,$4,$NF}' /etc/passwd \
 130         | smenu -n10 -c)
 131   $ echo $R
 132
 133 On mine (``LANG`` and ``LC_ALL`` set to ``POSIX``) it displays:
 134
 135 ::
 136
 137   at      25 25  /bin/bash      \
 138   sys     0  3   /usr/bin/ksh   +
 139   bin     1  1   /bin/bash      |
 140   daemon  2  2   /bin/bash      |
 141   ftp     40 49  /bin/bash      |
 142   games   12 100 /bin/bash      |
 143   lp      4  7   /bin/bash      |
 144   mail    8  12  /bin/false     |
 145   named   44 44  /bin/false     |
 146   ntp     74 108 /bin/false     v
 147
 148 Note the presence of a scroll bar.
 149
 150 Bash example (CTRL-R replacement)
 151 ---------------------------------
 152 Just add the following in your ``.bashrc``
 153
 154 ::
 155
 156   EOL=$'\n'
 157   bind -x '"\C-r": READLINE_LINE=$(fc -lr 1                         \
 158                                    | sed "s/[1-9][0-9]*..//"        \
 159                                    | smenu -Q -l -a c:7/4,b -W"$EOL")
 160                    READLINE_POINT=${#READLINE_LINE}'
 161
 162 Launch or relaunch **bash** and hit ``CTRL-R`` (``CTRL-C`` or ``q``
 163 to exit), enjoy!
 164
 165 You can also add the parameter **-d** to instruct **smenu** to clean
 166 the selection window after selecting an entry.
 167
 168 Warning for post v0.9.15 versions.
 169 ----------------------------------
 170 These versions use a new options system called **ctxopt** which
 171 may contain bugs.
 172 Please report them so they can be fixed in the next release of **smenu**
 173 or **ctxopt** (https://github.com/p-gen/ctxopt).
 174
 175 Command line arguments may also need to be rearranged in some cases
 176 because of this new option management system.
 177 Sorry for the extra work this might entail.
 178
 179 Bugs.
 180 -----
 181
 182 Right-alignment of lines written in right-to-left languages, such as Farsi
 183 or Hebrew, is not respected.
 184
 185 Testing and reporting.
 186 ----------------------
 187 The included testing system is relatively young, please be indulgent.
 188
 189 **IMPORTANT** the testing system has some dependencies, please read the
 190 ``test/README.rst`` before going further.
 191
 192 **NOTE** running all the tests by running ``./tests.sh`` in the
 193 ``tests`` directory will take some time (around 21 min for now).
 194
 195 **NOTE** on some systems like \*BSD some tests may fail. This can be
 196 explained by differences in posix/libc/... implementations.  This can
 197 notably occur when some specific regular expressions or uncommon ``UTF-8``
 198 byte sequences are used.
 199
 200 If a test fails for an unknown reason, please send me the name of its
 201 directory and the corresponding ``.bad`` file.
 202
 203 If you are hit by a bug that no test covers, then you can create a new
 204 test in the ``tests`` directory in an existing or new directory: read the
 205 ``tests/README.rst`` file, use an existing test as model, create an
 206 ``.in`` file and a ``.tst`` file and send them to me as well as the
 207 produced files.
 208
 209 Contributions.
 210 --------------
 211 Contributions are welcome but discuss your proposal in an issue first,
 212 or with the maintainer.
 213
 214 Special thanks.
 215 ---------------
 216 I want to thank those who took the time to package **smenu** for their
 217 preferred operating system or distribution.
 218 You will find their names here: https://repology.org/project/smenu/information