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