README.bsetbg

   1 README for bsetbg
   2
   3 ### introduction ###
   4
   5 bsetbg is a shell script that is intended to provide a standard root image
   6 application for the blackbox window manager (although it will work under any
   7 other window manager as well). bsetbg acts as a wrapper both to bsetroot and
   8 to whatever application(s) you prefer to use for setting images on the root
   9 window.
  10
  11 ### installation ###
  12
  13 (o) copy the script to a directory in your path.
  14 (o) chmod it to make it executable (chmod 755 /path/to/bsetbg).
  15
  16 If you're lazy, do nothing. bsetbg will work out of the box for 99% of the
  17 population.
  18
  19 If you're at least vaguely curious, run bsetbg in an xterm without any
  20 arguments.  This way, you can watch what it does.
  21
  22 If you're a "power user", read the 'configuration' section below.
  23
  24 ### configuration ###
  25
  26 bsetbg reads it's configuration from ~/.bsetbgrc . If it can't find this file,
  27 it will search for a list of applications in the system path and use the
  28 positive matches to create it. If you would prefer for this not to happen, you
  29 can create your own config file using the included sample.config .
  30 ~/.bsetbgrc should contain the following variables:
  31
  32 CENTER=  application and arguments for centering an image on the root window
  33 FULL=    application and arguments for stretching/contracting an image to fill
  34          the root window
  35 TILE=    application and arguments to tile the root window
  36 DEFAULT= action to take place by default if none of the above have been
  37 specified.
  38
  39 If you let bsetbg create the configuration file, the only applications that
  40 will be included in it are the ones that were found in your path. bsetbg will
  41 choose one of them to be the default and comment out the rest, so if you don't
  42 like what it chooses, edit the file and change the default values to whatever
  43 you like.
  44
  45 ### usage ###
  46
  47 ** normal usage:
  48
  49   bsetbg -full|-tile|-center <image>
  50
  51 Running bsetbg without any arguments except the name of the image will cause
  52 it to set the image with the default values, which will vary from person to
  53 person. For the ultimate control over your theme, always tell bsetbg what you
  54 want it to do.
  55
  56 ** advanced usage:
  57
  58 If you use a certain program or set of arguments to achieve a particular
  59 effect  that goes beyond the scope of bsetbg's normal functionality, you can
  60 include the application and its necessary command line options after the
  61 -app flag:
  62
  63   bsetbg -app <application> <"command line options"> <image>
  64
  65 Here is an example in which bsetbg will try to run xv to center the image
  66 against a colored background:
  67
  68   bsetbg -app xv "-rbg rgb:27/40/8b -root -rmode 5 -quit" <image>
  69
  70 Note that you MUST enclose the application's options in quotes. If you don't,
  71 bsetbg will bail out and give you an error message.
  72
  73 Before bsetbg runs the command, it will check to make sure that the application
  74 (xv in our example) is present on the target system. If it's not, bsetbg will
  75 fall back to setting the image using the default values from the
  76 configuration. If you want to control what the fallback option will be, use
  77 either -center, -tile, or -full after the options for the application:
  78
  79   bsetbg -app xv "-rbg rgb:20/2b/32 -root -rmode 5 -quit" -center <image>
  80
  81 In the above example, bsetbg will fall back to setting the image in centered
  82 mode if xv isn't available.
  83
  84 ** other usage:
  85
  86 bsetbg can also be used in place of bsetroot. Just give bsetbg the same
  87 arguments that you would normally pass to bsetroot. Example:
  88
  89   rootCommand:   bsetbg -gradient flatinterlaced -from rgb:46/51/5c -to rgb:34/3c/45
  90
  91   rootCommand:   bsetbg -solid SteelBlue
  92
  93 ** informational usage:
  94
  95 'bsetbg -help' does what you'd expect it to.
  96
  97 'bsetbg -info' will output information about bsetbg's current configuration
  98 values. Use this when you're debugging an incorrect configuration.
  99
 100 ### troubleshooting ###
 101
 102 This section is sort of a FAQ.
 103
 104 (o) Help! My background is messed up when I try to use a png image!
 105
 106 If you are using xv, your version probably hasn't been patched to include png
 107 support. You have two options:
 108 1), you can download the source and the patches and compile xv yourself (see
 109 the url at the end of this document), or
 110 2), you can try to hunt down a binary version of xv that was compiled with the
 111 png patch.  The one in most Linux distributions should be fine.
 112
 113 If you aren't using xv, then whatever it is that you are using is having a
 114 problem with png images. consult the documentation on it.
 115
 116
 117 (o) When I switch to a new blackbox style, the background doesn't change.
 118
 119 Most likely, there's an error with bsetbg. If you alt+f[1-5] to go back to your
 120 console, you can see bsetbg's error message. Alternatively, run bsetbg from an
 121 xterm and look at its output.
 122
 123 In most instances, there will be a problem with your config file. You can
 124 either try to fix it yourself, or you can rename your ~/.bsetbgrc to something
 125 else and then run bsetbg without any arguments in order to force the creation
 126 of a new configuration file.
 127
 128
 129 (o) When I try to set an image in full/tiled/centered mode, the image is not
 130     full/tiled/centered.
 131
 132 You've probably given the values in the config file the wrong arguments for
 133 what they are meant to do. Either let bsetbg create a new file (see above), or
 134 else read the "configuration" section if this document.
 135
 136
 137 (o) I'm a moron who can't be bothered to read your fine and well-written
 138     README.  Can I email you with my stupid questions?
 139
 140 Don't even think about it.
 141
 142 ### other stuff ###
 143
 144 qiv lives at:
 145    http://www.klografx.de/software/qiv.shtml
 146
 147 xli can be found at:
 148    http://pantransit.reptiles.org/prog/#xli
 149
 150 display (part of ImageMagick) can be found at:
 151    http://www.imagemagick.org/
 152
 153 wmsetbg is a part of the Window Maker window manager. Window Maker can be
 154 found at:
 155    http://windowmaker.org/
 156
 157 Esetroot is a part of the Enlightenment window manager:
 158    http://enlightenment.org/
 159
 160 xv can be found at:
 161    http://www.trilon.com/xv/downloads.html
 162
 163 blackbox homepage:
 164    http://blackboxwm.sourceforge.net/
 165
 166 and lastly, bsetbg:
 167    http://lordzork.com/blackbox/
 168
 169
 170 ### more other stuff ###
 171
 172 many thanks are due to:
 173 youngjun han, for the inspiration to do it in the first place
 174 zak johnson, for invaluable suggestions
 175 brad hughes, for help in debugging (not to mention, creating a smashing window
 176 manager)
 177 and last but not least, mycat, mr. man.
 178
 179 send all comments/suggestions/constructive criticism/blueprints for futuristic
 180 weapons/etc to lordzork@lordzork.com
 181
 182 bsetbg has only been tested under Linux and FreeBSD. If it doesn't work on
 183 your system, email me the details and I'll try to fix it.
 184
 185 Copyright (c) 2000, 2002 Timothy M. King (tmk@lordzork.com)