                                                             tbsm v0.7, Nov 2022
Index
=======
1- Introduction
2- Things Of Interest
3- Post Install Tasks
4- Contact
5- Thanks To
6- Copying


1- Introduction
=================
tbsm is an application or session launcher, written in pure bash with no
ncurses or dialog dependencies. It is inspired by cdm, tdm, in some way by
krunner and related.

To became an overview of available options run:
  tbsm help

It was attempted to design the behavior of tbsm to be as less pesky as possible,
and to start daily tasks with as less key strokes.

To do so, tbsm saves the last run session and a default session. These both are
available by the quick menu where you can start the default session by simply
hit <enter> or the last session when you delete the bang ! previous. You can run
there any command tbsm knows without to remove the bang.

The last run session will not changed when you choose the default session.

You reach the quick menu from the full session menu by hitting <enter> on an
empty prompt. To go back you have to give the needed command which is 'm'.

You should know that there is not really any special at the 'full session menu'.
It is only a pimped out listing of your tbsm configuration where as the commands
'search' and 'list' show a poor list. In any way you have to use the listed
index numbers as argument for any command you like.

The quick menu on the other hand is a little special but still works with the
same intern list, of two entries only, default and last session. You can verify
this when you give 'l' at the quick menu prompt.

May you have a nice day, I run now 'q'


2- Things Of Interest
=======================
He only works with .desktop files to start something, there is no other
possibility. See 4-6- for a custom example.

The following statements assume a usual configuration. However there will
XDG_CONFIG_HOME and XDG_CONFIG_DIRS respected.

When running tbsm without any argument he is scanning for available .desktop
files in /usr/share/xsessions/ , /usr/share/wayland-sessions and
$configDir/whitelist but skip any file referenced in $configDir/blacklist.
Whereas $configDir is ~/.config/tbsm.

The latter will created if not exist but not filled with default files, do it
by yourself if needed. The former will searched for themes and the config file
but not for white or black listed files.

In the simplest form you can create a config file like so:
    echo "verboseLevel=2" > ~/.config/tbsm/tbsm.conf

Or perhaps:
    echo "theme=austere" > ~/.config/tbsm/tbsm.conf


When searching for any pattern he run a grep with the pattern on all .desktop
files in /usr/share/applications/

The first session ever started became the default session.

There may some option or command variant available which is not documented. They
are there to be more comfortable or due to the laziness of the coder.


3- Post Install Tasks
=======================
To auto start tbsm after login edit your ~/.bash_profile, or similar, and append
to the end something like:

  # Auto start tbsm after login on first two VTs
  [[ $XDG_VTNR -le 2 ]] && tbsm

This is only an suggestion, there may better ways. Look at section 4- how others
configured their system.

NOTE: Ensure you start no other display manager. Check your distribution's
      documentation how to disable system services or uninstall packages.


3-1- Customizing
------------------
Take a look at /etc/xdg/tbsm and subfolders.
Create your own theme files in ~/.config/tbsm/themes.

By default is tbsm a little chattering (--verbose) with the intend you become
familiar with it. But quickly you will be annoyed and therefore have all themes
a setting verboseLevel="2" (--info) which should be good for most cases.

Run the command 'tbsm doc conf' to become an idea what else you can customize.


3-2- Special Start X Configuration
------------------------------------
By default will X started this way:

  startx ${bin[@]} -- ${XserverArg[@]}

If that doesn't full fill your needs, you can create an own startup file in one
of the config directories. It must be named "start-x" and will be called with
the three shown arguments, but quoted. As the file is called, it must be
executable. Here the simplest possible example:

  $ cat ~/.config/tbsm/start-x
  #!/bin/bash
  # $@ contains: "${bin} -- ${XserverArg}" but all splitted, so $2 may "--"
  # but not for sure. $3 is typically ":1" (display) $4 typically "-nolisten"
  # and so on. Depending on your config settings.
  #
  # do something before
  startx $@
  # do something after

For a little more complex example see 4-5-


4- Tips & Tricks
==================
Here are some hints collected in order as they was reported. Should that list
grow in the future I should better enable the Wiki feature on GitHub.


4-1- tbsm together with tmux
------------------------------
When using tmux, tbsm will run with the above mentioned setup in each terminal
session. To solve this try the following:

  # Auto start tbsm only on tty1
  if [[ ! ${DISPLAY} && ${XDG_VTNR} == 1 ]]; then
      exec tbsm
  fi

Thanks to Anton, https://github.com/loh-tar/tbsm/issues/10


4-2- tbsm together with fish shell
------------------------------------
Add to .config/fish/config.fish

  if test "$DISPLAY" = "" -a "$XDG_VTNR" = 1
        tbsm
  end

If $DISPLAY is empty and XDG_VTR equals 1 then execute tbsm.
Works with tmux. Test in sway, alacritty.

Thanks to Anton, https://github.com/loh-tar/tbsm/issues/10


4-3- Prevent exiting out of twm for example
---------------------------------------------
Instead of just calling tbsm, "exec" it similar to 4-1-

  # Auto start tbsm after login on first two VTs
  [[ $XDG_VTNR -le 2 ]] && exec tbsm

Thanks to toke, https://github.com/loh-tar/tbsm/pull/12


4-4- To avoid trouble when also SSH access is needed
------------------------------------------------------

  [[ -n "$XDG_VTNR" && $XDG_VTNR -le 2 ]] && tbsm

Thanks to 0BAD-C0DE, https://aur.archlinux.org/packages/tbsm#comment-841043


4-5- Redirect Xorg output into custom logfile
-----------------------------------------------
With this redirection will the terminal not fluted with unreadable chatter from
the X server or the session. Interesting read! Of cause you can also dump it by
redirect to /dev/null

  $ cat ~/.config/tbsm/start-x
  #!/bin/bash
  ownLogfile="/tmp/$USER/tbsm/xorg-chatter.log"
  mkdir -p $(dirname $ownLogfile)
  # We also set an option to improve readability on high resolution displays in
  # a slightly strange way. Typical we would set XserverArg in the conf file
  # Just remember: $@ is like "${bin} -- ${XserverArg}"
  startx $@ -dpi 120 2> ${ownLogfile}


4-6- Add a shell session to the menu
--------------------------------------
In this example you will be dropped to a bash shell, other shells will have
similar options. When your are done type 'exit' and you came back to tbsm.

  $ cat ~/.config/tbsm/whitelist/bash-session.desktop
  [Desktop Entry]
  Name=Bash Session
  Exec=bash -i
  Terminal=true

Asked by bee-keeper, https://github.com/loh-tar/tbsm/issues/18


5- Contact
============
The home of tbsm
  https://github.com/loh-tar/tbsm

Arch forum talk
  https://bbs.archlinux.org/viewtopic.php?id=207817

The author of that all
  loh.tar@googlemail.com


6- Thanks To
==============
Ian Brunelli <ian@brunelli.me>,
  not only for adding Wayland support

Jan-Luca <build.opensuse.org/users/jlkDE>,
  for providing an openSUSE package

All contributors of cdm and tdm,
  without which I probably would not have started tbsm in the first place

stackexchange.com, bash-hackers.org,
  for their great knowledge base and tutorials

dict.cc, google.com (till v0.5) and deepl.com (since v0.6),
  who make my english much more understandable

Many more I have miss to note (sorry!), but not github.com for kindly hosting.
Last but not least: Mom & Dad and archlinux.org


7- Copying
============
Copyright (C) 2016-2019, 2022 loh.tar@googlemail.com

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
MA 02110-1301, USA.
