1
0
Fork 0
mirror of https://github.com/Cloudef/bemenu synced 2024-03-29 10:19:57 +01:00

Update manpage to use scdoc, document margin and width-factor

This also adds scdoc as a dependency.

scdoc is almost as easy as markdown and therefore it's much nicer to
write and maintain manpages making use of it instead of plain roff.
This commit is contained in:
Maxim Karasev 2021-12-27 19:53:57 +03:00 committed by Jari Vetoniemi
parent 43255bbbe8
commit 9cac33857d
5 changed files with 270 additions and 324 deletions

View File

@ -12,7 +12,7 @@ jobs:
steps:
- uses: actions/checkout@v2
- name: install build deps
run: sudo apt-get install libcairo2-dev libpango1.0-dev libxinerama-dev libwayland-dev wayland-protocols libxkbcommon-dev
run: sudo apt-get install scdoc libcairo2-dev libpango1.0-dev libxinerama-dev libwayland-dev wayland-protocols libxkbcommon-dev
- name: make
run: make PREFIX=install EXTRA_WARNINGS=-Werror
- name: make install

View File

@ -47,8 +47,8 @@ $(libs): %: VERSION .git/index
$(pkgconfigs): %: VERSION %.in
sed "s/@VERSION@/$(VERSION)/;s,@PREFIX@,$(PREFIX),;s,@LIBDIR@,$(libdir),;s,@INCLUDEDIR@,$(includedir)," $(addsuffix .in, $@) > $@
bemenu.1: man/bemenu.1.in
sed 's,@LIBDIR@,$(PREFIX)$(libdir),' $< > $@
bemenu.1: man/bemenu.1.scd.in
sed 's,@LIBDIR@,$(PREFIX)$(libdir),' $< | scdoc > $@
$(renderers): %: VERSION .git/index | $(libs)
$(LINK.c) -shared -fPIC $(filter %.c %.a,$^) $(LDLIBS) -L. -lbemenu -o $@

View File

@ -61,7 +61,12 @@ PKG_CONFIG_PATH="/usr/local/opt/ncurses/lib/pkgconfig" sh build-osx.sh curses
## Dependencies
All dependencies are searched with `pkg-config`
- C compiler
- scdoc to generate manpage
### Backend-specific
All dependencies below are searched with `pkg-config`
| Backend | Dependencies |
|----------|------------------------------------------------------------------------|
@ -76,7 +81,7 @@ Currently, pasting from clipboard is done at runtime with `wl-paste -t text/plai
#### Ubuntu 20.04
```sh
sudo apt install wayland-protocols libcairo-dev libpango1.0-dev libxkbcommon-dev libwayland-dev
sudo apt install scdoc wayland-protocols libcairo-dev libpango1.0-dev libxkbcommon-dev libwayland-dev
```
## Environment variables

View File

@ -1,319 +0,0 @@
.Dd November 1, 2021
.Dt BEMENU 1
.Os
.Sh NAME
.Nm bemenu
.Nd dynamic menu inspired by
.Xr dmenu 1
.Sh SYNOPSIS
.Nm
.Op Fl hivwx
.Op Fl I Ar index
.Op Fl l Ar lines
.Op Fl P Ar prefix
.Op Fl p Ar prompt
.Op Fl -ifne
.Op Fl -scrollbar Cm none | always | autohide
.Op Ar backend-options
.Nm bemenu-run
.Op Fl hivwx
.Op Fl I Ar index
.Op Fl l Ar lines
.Op Fl P Ar prefix
.Op Fl p Ar prompt
.Op Fl -ifne
.Op Fl -scrollbar Cm none | always | autohide
.Op Fl -fork
.Op Fl -no-exec
.Op Ar backend-options
.Sh DESCRIPTION
.Nm
is a dynamic menu for
.Xr tty 4
.Pq using Xr ncurses 3 ,
X11 and Wayland, inspired by
.Xr dmenu 1 .
It reads a list of newline-separated items from standard input and then
presents them as a list, where the user can select one or more of them.
When pressing
.Aq Cm carriage-return ,
the selected items are printed to standard output (one per line) and
.Nm
exits.
Entering text will filter the items to those that match the input.
If the number of items exceeds the size of the list,
the items will be paginated.
.Pp
.Nm bemenu-run
is a special-case invocation of
.Nm ,
where the input is the list of executables under
.Ev PATH
and the selected items are executed.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl h , -help
Print a help message to standard output and exit.
.It Fl I Ar index , Fl -index Ar index
Highlight the item at
.Ar index
at the start.
Indices start at 0.
By default, the first item is highlighted.
.It Fl i , -ignorecase
Filter items case-insensitively.
.It Fl l Ar number , Fl -list Ar number
List items vertically with the given
.Ar number
of lines.
.It Fl P Ar prefix , Fl -prefix Ar prefix
Display
.Ar prefix
before the highlighted item in a vertical list.
.It Fl p Ar prompt , Fl -prompt Ar prompt
Defines the
.Ar prompt
text to be displayed to the left of the input field.
Defaults to
.Ql bemenu .
.It Fl v , -version
Print the
.Nm
version number to standard output and exit.
.It Fl w , -wrap
Advancing past the end of the list returns you to the start.
.It Fl x , -password
Hide filter text.
.It Fl -fork
Always
.Xr fork 2
before executing the selections.
Disabled by default when using the terminal backend.
.It Fl -no-exec
Print the selected items to standard output instead of executing them.
.It Fl -scrollbar Cm none | always | autohide
Specify when to show a scrollbar for vertical lists:
.Bl -tag -width autohide
.It Cm none
Never display a scrollbar
.Pq the default .
.It Cm always
Always display a scrollbar.
.It Cm autohide
Only display a scrollbar when the number of items exceeds the number of
lines.
.El
.El
.Ss Backend Options
These options are only available on backends specified in the
parentheses:
.Bl -tag -width Ds
.It Fl b , -bottom Pq Wayland, X11
The list will appear at the bottom of the screen.
.It Fl f , -grab Pq Wayland, X11
Show the
.Nm
window whilst reading the items.
.It Fl H Ar height , Fl -line-height Ar height Pq Wayland, X11
Specify the
.Ar height
in point size to make each entry.
.It Fl m Ar index , Fl -monitor Ar index Pq Wayland, X11
Specify the monitor
.Ar index
where the list should appear.
Monitor indices start at zero.
The interpretation of the given argument depends on the utilized backend.
With X11 and Wayland, a value of
.Ql -1
or
.Cm focused
indicates that the current monitor should be used (the default).
With Wayland, the
.Ar index
should be a string specifying a specific monitor name. The value
.Ql -2
or
.Cm all
indicates that the list should appear on all monitors.
.It Fl n , -no-overlap Pq Wayland
Set the
.Nm
window to be on top of any other panels.
.It Eo
.Fl -fn Sq Ar name Op Ar size
.Pq Wayland , X11
.Ec
Specify the font family
.Ar name
and
.Ar size
to be used.
For more options, consult the
.%T Pango Reference Manual
for
.Fn pango_font_description_from_string .
.El
.Pp
The following options control the colours for various parts of the list
for the Wayland and X11 backends.
Each takes an argument in the form of:
.Pp
.Dl Cm # Ns Ar RGB Ns Op Ar A
.Pp
where
.Ar R, G, B
and
.Ar A
are hexadecimal integers from 00\(enFF that control the red, green, blue
and alpha-transparency channels.
.Bl -tag -width "--xxx color "
.It Fl -tb Ar color
Title background.
.It Fl -tf Ar color
Title foreground.
.It Fl -fb Ar color
Filter background.
.It Fl -ff Ar color
Filter foreground
.It Fl -nb Ar color
Normal background.
.It Fl -nf Ar color
Normal foreground.
.It Fl -hb Ar color
Highlighted background.
.It Fl -hf Ar color
Highlighted foreground.
.It Fl -sb Ar color
Selected background.
.It Fl -sf Ar color
Selected foreground.
.It Fl -scb Ar color
Scrollbar background.
.It Fl -scf Ar color
Scrollbar foreground.
.El
.Sh KEYBOARD COMMANDS
.Nm
supports keyboard commands to move around the list and edit the filter.
In the following examples,
.Cm C-x
means
.Aq Cm control-x ,
.Cm M-x
means
.Aq Cm alt-x
and
.Cm S-x
means
.Aq Cm shift-x :
.Bl -tag -width Ds
.It Eo
.Aq Cm cursor-up ,
.Cm S- Ns Aq Cm cursor-left ,
.Cm C-p , M-j , M-l Ec
Highlight the previous item.
.It Eo
.Aq Cm cursor-down ,
.Aq Cm tab ,
.Cm C-n , M-h , M-k Ec
Highlight the next item.
.It Cm PageUp , M-v , M-u
Show the previous page of items, preserving the offset of the currently
highlighted item, if possible.
.It Cm PageDown , C-v , M-d
Show the next page of items, preserving the offset of the currently
highlighted item, if possible.
.It Cm S-M-< , S-PageUp
Highlight the first item in the list.
.It Cm S-M-> , S-PageDown
Highlight the last item in the list.
.It Cm S- Ns Aq Cm tab
Copy the highlighted item to the filter.
.It Eo
.Aq Cm escape ,
.Cm C-g Ec
Terminate
.Nm
without printing items.
.It Cm C- Ns Aq Cm carriage-return
Select the highlighted item and continue highlighting.
.It Eo
.Cm S- Ns Aq Cm carriage-return ,
.Cm C-m Ec
Print selected items and the currently highlighted one, and exit.
Items are printed in the order they were selected,
with the currently highlighted item printed last.
.It Eo
.Cm S- Ns Aq Cm carriage-return ,
.Cm Insert Ec
Print the filter text to standard output and exit.
.It Cm C-l , Aq Cm cursor-left
Move cursor left.
.It Cm C-f , Aq Cm cursor-right
Move cursor right.
.It Cm C-a , Home
Move cursor to the start.
.It Cm C-e , End
Move cursor to the end.
.It Eo
.Aq Cm backspace
.Cm C-h Ec
Remove character before the cursor.
.It Aq Cm delete
Remove character at the cursor.
.It Cm C-u , S- Ns Aq Cm delete
Remove all characters before the cursor.
.It Cm C-k
Remove all characters after the cursor.
.It Cm C-w
Clear the filter.
.It Cm C-y
Paste the clipboard.
.It Cm M- Ns Op 0\(en9
Print selected items and exit with a custom error code.
See
.Sx EXIT STATUS .
.El
.Sh ENVIRONMENT
.Bl -tag -width "BEMENU_RENDERERS"
.It Ev BEMENU_OPTS
An alternative way to pass command line arguments to
.Nm .
.It Ev BEMENU_BACKEND
Force a backend to be used.
If empty, one of the GUI backends (Wayland, X11) will be selected
automatically.
The accepted values are
.Cm curses , wayland
and
.Cm x11 .
.It Ev BEMENU_RENDERER
Force a backend by loading its shared object from the set value.
.It Ev BEMENU_RENDERERS
Override the backend search path to the set value.
Defaults to
.Pa @LIBDIR@/bemenu .
.It Ev BEMENU_SCALE
Override the rendering scale factor for the GUI backends.
.El
.Sh EXIT STATUS
.Nm
exits 0 on success, 1 if the user exited without selecting or an error,
and if exiting with a custom error code, 10 plus the number specified.
.Sh SEE ALSO
.Xr dmenu 1 ,
.Xr fork 2 ,
.Xr ncurses 3 ,
.Xr tty 4
.Pp
.Rs
.%T Pango Reference Manual
.%D August 20, 2020
.%U https://developer.gnome.org/pango/1.46/
.%O Fonts \(em pango_font_description_from_string()
.Re
.Sh AUTHORS
.Nm
is written and maintained by
.An Jari Vetoniemi Aq Mt mailroxas@gmail.com .

260
man/bemenu.1.scd.in Normal file
View File

@ -0,0 +1,260 @@
bemenu(1)
# NAME
*bemenu* - dynamic menu inspired by *dmenu*(1)
# SYNOPSIS
*bemenu* [*-hivwx*] [*-I* <_index_>] [*-l* <_lines_>] [*-P* _prefix_]
\[*-p* <_prompt_>] [*--ifne*] [*--scrollbar* _none_|_always_|_autohide_]
\[_backend_options_]
*bemenu-run* [*-hivwx*] [*-I* <_index_>] [*-l* <_lines_>] [*-P* <_prefix_>]
\[*-p* <_prompt_>] [*--ifne*] [*--scrollbar* _none_|_always_|_autohide_]
\[*--fork*] [*--no-exec*] [_backend-options_]
# DESCRIPTION
*bemenu* is a dynamic menu for *tty*(4) (using *ncurses*(3)), X11 and Wayland,
inspired by *dmenu*(1).
It reads a list of newline-separated items from standard input and then presents
them as a list, where the user can select one or more of them. When pressing
*<carriage-return>*, the selected items are printed to standard output (one per
line) and *bemenu* exits.
Entering text will filter the items to those that match the input. If the number
of items exceeds the size of the list, the items will be paginated.
*bemenu-run* is a special-case invocation of *bemenu*, where the input is the
list of executables under PATH and the selected items are executed.
# OPTIONS
*-h, --help*
Print a help message to standard output and exit.
*-I, --index* <_index_>
Highlight the item at _index_ at the start. Indices start at 0. By
default, the first item is highlighted.
*-i, --ignorecase*
Filter items case-insensitively.
*-l, --list* <_number_>
List items vertically with the given _number_ of lines.
*-P, --prefix* <_prefix_>
Display _prefix_ before the highlighted item in a vertical list.
*-p, --prompt* <_prompt_>
Defines the _prompt_ text to be displayed to the left of the input
field. Defaults to bemenu.
*-v, --version*
Print the *bemenu* version number to standard output and exit.
*-w, --wrap*
Advancing past the end of the list returns you to the start.
*-x, --password*
Hide filter text.
*--fork*
Always *fork*(2) before executing the selections. Disabled by default
when using the terminal backend.
*--no-exec*
Print the selected items to standard output instead of executing them.
*--scrollbar* _none_|_always_|_autohide_
Specify when to show a scrollbar for vertical lists:
[[ *none*
:< Never display a scrollbar (the default).
| *always*
: Always display a scrollbar.
| *autohide*
: Only display a scrollbar when the number of items exceeds the number
of lines.
## Backend options
These options are only available on backends specified in the parentheses:
*-b, --bottom* (Wayland, X11)
The list will appear at the bottom of the screen.
*-f, --grab* (Wayland, X11)
Show the *bemenu* window whilst reading the items.
*-H, --line-height* <_height_> (Wayland, X11)
Specify the _height_ in point size to make each entry.
*-m, --monitor* <_index_> (Wayland, X11)
Specify the monitor _index_ where the list should appear. Monitor
indices start at zero. The interpretation of the given argument depends
on the utilized backend. With X11 and Wayland, a value of -1 or
*focused* indicates that the current monitor should be used (the
default). With Wayland, the _index_ should be a string specifying a
specific monitor name. The value -2 or *all* indicates that the list
should appear on all monitors.
*-n, --no-overlap* (Wayland)
Set the *bemenu* window to be on top of any other panels.
*-M, --margin* <_margin_> (Wayland, X11)
Specify the _margin_ (empty space) in pixels to leave between menu and
vertical view borders. *bemenu* will reduce it's size to fit in space
between gaps.
*-W, --width-factor* <_factor_> (Wayland, X11)
Specify the relative width factor as a floating point number. It makes
sense to set it between 0 and 1 to define how much of the screen width
*bemenu* will use. However, *bemenu* will still respect _margin_, so if
resulting size is greater than space between gaps, *bemenu* will ignore
_factor_ and use available space instead.
*--fn* <_name_ [_size_]> (Wayland, X11)
Specify the font family _name_ and _size_ to be used. For more options,
consult the _Pango Reference Manual_ for
*pango_font_description_from_string*().
The following options control the colours for various parts of the list
for the Wayland and X11 backends. Each takes an argument in the form of:
*#*_RGB_[_A_]
where _R_, _G_, _B_ and _A_ are hexadecimal integers from 00FF that
control the red, green, blue and alpha-transparency channels.
*--tb* <_color_> Title background.
*--tf* <_color_> Title foreground.
*--fb* <_color_> Filter background.
*--ff* <_color_> Filter foreground
*--nb* <_color_> Normal background.
*--nf* <_color_> Normal foreground.
*--hb* <_color_> Highlighted background.
*--hf* <_color_> Highlighted foreground.
*--sb* <_color_> Selected background.
*--sf* <_color_> Selected foreground.
*--scb* <_color_> Scrollbar background.
*--scf* <_color_> Scrollbar foreground.
# KEYBOARD COMMANDS
*bemenu* supports keyboard commands to move around the list and edit the filter.
In the following examples, *C-x* means *<control-x>*, *M-x* means *<alt-x>* and
*S-x* means *<shift-x>*:
*<cursor-up>, S-<cursor-left>, C-p, M-j, M-l*
Highlight the previous item.
*<cursor-down>, <tab>, C-n, M-h, M-k*
Highlight the next item.
*PageUp, M-v, M-u*
Show the previous page of items, preserving the offset of the currently
highlighted item, if possible.
*PageDown, C-v, M-d*
Show the next page of items, preserving the offset of the currently
highlighted item, if possible.
*S-M-<, S-PageUp*
Highlight the first item in the list.
*S-M->, S-PageDown*
Highlight the last item in the list.
*S-<tab>*
Copy the highlighted item to the filter.
*<escape>, C-g*
Terminate *bemenu* without printing items.
*C-<carriage-return>, C-m*
Print selected items and the currently highlighted one, and exit. Items
are printed in the order they were selected, with the currently
highlighted item printed last.
*S-<carriage-return>, Insert*
Print the filter text to standard output and exit.
*C-l, <cursor-left>*
Move cursor left.
*C-f, <cursor-right>*
Move cursor right.
*C-a, Home*
Move cursor to the start.
*C-e, End*
Move cursor to the end.
*<backspace> C-h*
Remove character before the cursor.
*<delete>*
Remove character at the cursor.
*C-u, S-<delete>*
Remove all characters before the cursor.
*C-k*
Remove all characters after the cursor.
*C-w*
Clear the filter.
*C-y*
Paste the clipboard.
*M-[0-9]*
Print selected items and exit with a custom error code. See _EXIT
STATUS_.
# ENVIRONMENT
[[ *BEMENU_OPTS*
:< An alternative way to pass command line arguments to *bemenu*.
| *BEMENU_BACKEND*
: Force a backend to be used. If empty, one of the GUI backends (Wayland, X11)
will be selected automatically. The accepted values are *curses*, *wayland*
and *x11*.
| *BEMENU_RENDERER*
: Force a backend by loading its shared object from the set value.
| *BEMENU_RENDERERS*
: Override the backend search path to the set value. Defaults to
_@LIBDIR@/bemenu_.
| *BEMENU_SCALE*
: Override the rendering scale factor for the GUI backends.
# EXIT STATUS
*bemenu* exits 0 on success, 1 if the user exited without selecting or an error,
and if exiting with a custom error code, 10 plus the number specified.
# SEE ALSO
*dmenu*(1), *fork*(2), *ncurses*(3), *tty*(4)
_Pango Reference Manual_, https://developer.gnome.org/pango/1.46/, August 20,
2020, Fonts — pango_font_description_from_string().
# AUTHORS
*bemenu* is written and maintained by Jari Vetoniemi <_mailroxas@gmail.com_>
with the help of various contributors.