Dogcows Code - chaz/openbox/blob - README.bsetbg

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