neysx 09/01/29 17:50:20 Added: openbox.xml Log: #256693 initial commit
Revision Changes Path 1.1 xml/htdocs/doc/en/openbox.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openbox.xml?rev=1.1&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openbox.xml?rev=1.1&content-type=text/plain Index: openbox.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openbox.xml,v 1.1 2009/01/29 17:50:20 neysx Exp $ --> <guide disclaimer="draft"> <title>The Openbox Configuration HOWTO</title> <author title="Author"> <mail link="kalos"/> </author> <abstract> This guide shows you how to install the Openbox window manager, and references many potential programs to be used in conjunction with an Openbox session. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1</version> <date>2009-01-29</date> <chapter> <title>Introduction</title> <section> <title>What is Openbox?</title> <body> <p> So, you've installed <uri link="/doc/en/xorg-config.xml">The X Server</uri> and realised that TWM just isn't going to cut it for your needs. You may have also had some experience with big desktop environments like <uri link="/proj/en/desktop/kde/kde-config.xml">KDE</uri>, <uri link="/doc/en/gnome-config.xml">GNOME</uri>, and <uri link="/doc/en/xfce-config.xml">Xfce</uri>. One component of those larger desktop suites is called the window manager (or WM for short). A window manager is responsible for the appearance and placement of the containers (or "windows") inside which programs run. Openbox is a minimalistic, no-frills-attached window manager. </p> </body> </section> <section> <title>Why should I use it?</title> <body> <p> Openbox, unlike the larger desktop environments, depends on very few libraries. For that reason, it can provide a lightweight graphic environment that runs very quickly, even on older hardware. Whether your hardware is old or new, Openbox also provides a highly customisable and unobtrusive working environment. That means that if you don't want or need a panel, taskbar, clock, or any other program, that choice is yours! </p> </body> </section> </chapter> <chapter> <title>Installation and configuration</title> <section> <title>Initial installation</title> <body> <p> After you have emerged xorg-x11 and configured all of your <path>xorg.conf</path> settings, installing Openbox can be done in one simple command: </p> <pre caption="Installing Openbox"> <comment>(Use <i>emerge -av openbox</i> to preview which packages will be installed)</comment> # <i>emerge openbox</i> </pre> <p> Just like with other window managers and desktop environments, you will need to tell the X Server to load Openbox automatically, by adding it to your <path>.xinitrc</path>. </p> <pre caption="Adding Openbox to your .xinitrc"> # <i>echo "exec openbox-session" >> ~/.xinitrc</i> </pre> <p> This will automatically start your Openbox session when you type <c>startx</c> at the terminal. </p> <impo> As each user has his or her own <path>.xinitrc</path>, you need to make sure to issue that command as <e>your user</e>, not as root. </impo> <note> You can also replace the KDE, GNOME, or Xfce default window manager with Openbox by following the <uri link="#inside-desktop-env">Openbox inside desktop environments</uri> directions. </note> <p> Now that you have emerged Openbox and added it to your <path>.xinitrc</path>, go ahead and issue the <c>startx</c> command to see Openbox in action. As you can see, the desktop is simply a cluttered mess! In following with the Openbox philosophy, what you will see is a barebones environment from which you can build your desktop completely to your liking. </p> <p> Since you're looking at nothing more than a black screen, you may be wondering where the menu is. If you click your right mouse button, you will notice that a menu pops up in the location of your cursor. This menu is nothing more than an example to illustrate the style of an Openbox menu. Since it <e>is</e> just an example, none of the items in the menu will work unless you have actually emerged those programs. In the next section, you will see how to create your own menu that contains links to <e>your</e> programs. </p> </body> </section> <section> <title>Menu configuration</title> <body> <p> Since the default Openbox menu is essentially useless to you for the reasons mentioned above, it's time that we create one that will work. Everything in the Openbox menu is written in the appropriately named <path>menu.xml</path> file, which can be in the user-specific location of <path>~/.config/openbox/menu.xml</path>, or in the system-wide location of <path>/etc/xdg/openbox/menu.xml</path>. By default, the only <path>menu.xml</path> file that is created is the system-wide one which applies to all users on the system. </p> <p> An easy way to get a basic menu file which you can modify is to use MenuMaker, which will generate a <path>menu.xml</path> file based on the programs which you currently have installed on your system. To do so, you must firstly emerge it: </p> <pre caption="Installing MenuMaker"> # <i>emerge menumaker</i> </pre> <p> Once it is installed, you need to tell it that you want a menu specifically using the Openbox XML syntax: </p> <pre caption="Using MenuMaker to generate a basic Openbox menu.xml"> # <i>mmaker -v OpenBox3</i> </pre> <p> The generated menu will be located at <path>/root/.config/openbox/menu.xml</path>. You can then copy the file, and overwrite either your user-specific <path>menu.xml</path> or the system-wide one (both mentioned above): </p> <pre caption="Overwriting the default menu.xml files"> <comment>(Creating or overwriting your user-specific menu)</comment> # <i>mv /root/.config/openbox/menu.xml /home/$USER/.config/openbox/menu.xml</i> OR <comment>(Overwriting your system-wide menu)</comment> # <i>mv /root/.config/openbox/menu.xml /etc/xdg/openbox/menu.xml</i> </pre> <impo> It is a good idea to use MenuMaker to generate a default menu, as it will have the Openbox root-menu items. These items include a virtual desktop switcher, and the commands to restart and exit your Openbox session. </impo> <p> When you open up the <path>menu.xml</path> file in your favourite editor (nano, for example), you will notice that the XML tags used are very human-readable and easily understandable. You may choose to modify the default file to fit your needs, or you may want to write it from scratch (don't worry, it's really not that difficult). The basic syntax for the menu XML is as follows: </p> <pre caption="Editing the menu.xml file"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <openbox_menu> <separator label="<i>NAME_OF_SEPARATOR</i>"> <menu id="<i>IDENTIFIER</i>" label="<i>NAME_OF_MENU</i>"> <item label="<i>NAME_OF_PROGRAM</i>"> <action name="execute"><execute><i>/LOCATION/OF/BINARY</i></execute></action> </item> </menu> </openbox_menu> ]]></pre> <p> Simply replace anything in <c>BLUE CAPS</c> with your information. </p> </body> </section> <section> <title>Openbox theme and behaviour configuration</title> <body> <p> Aside from being minimalistic and lightweight, Openbox is also surprisingly customisable and flexible. As a user, you can easily change various settings related to theme, appearance, window placement, docking, and more. There are two options for configuring these settings within Openbox. You may either manually edit the <path>~/.config/openbox/rc.xml</path> file, or you may want a GUI to help you quickly change settings. </p> <p> If you want to manually edit the <path>rc.xml</path> file, you simply open up your favourite text editor and start making changes. You might want to make a backup of the original file just in case, and store it in a location like <path>~/.config/openbox/rc.xml.default</path>. There are plenty of comments within the document itself that should help you with editing. Alternatively, you may want to look at the <uri link="http://icculus.org/openbox/index.php/Help:Contents#Configuration";>Openbox configuration guides</uri>. </p> <p> If manually editing the <path>rc.xml</path> file doesn't sound like your cup of tea, you may want to use the GTK+ application to manage your themes and behaviours in Openbox. The application that you will use is called ObConf, and can be installed on your system just as easily as was Openbox itself. </p> <pre caption="Installing ObConf"> # <i>emerge obconf</i> </pre> <p> You can then open the configurator by typing <c>obconf</c> in your terminal. Next, you can go and add an entry for ObConf into your <path>menu.xml</path> so it will show up in your Openbox menu. </p> </body> </section> <section> <title>Autostart configuration</title> <body> <p> As mentioned above, you don't see a whole lot when you issue the <c>startx</c> command for the first time after installing Openbox. In addition to customising your menus and changing the behaviour of the window manager, you will probably want to have some programs automatically start with your Openbox session. There is an easily-editable <path>autostart.sh</path> script that allows you to do just that. Just like with the <path>menu.xml</path> file, there are two different locations of the <path>autostart.sh</path> script--the system-wide (<path>/etc/xdg/openbox/autostart.sh</path>), and the user-defined (<path>~/.config/openbox/autostart.sh</path>). </p> <p> In the default <path>autostart.sh</path>, you will notice a bunch of lines calling for programs like the gnome-settings-daemon, XDG, and others. These lines will generate errors upon logout if you don't have the programs installed and configured. The easiest thing to do when getting started with Openbox is to just comment out these lines by using the # symbol.</p> <pre caption="Commenting out lines in autostart.sh"> # Run XDG autostart things. By default don't run anything desktop-specific # DESKTOP_ENV="" # if which /usr/lib/openbox/xdg-autostart >/dev/null; then # /usr/lib/openbox/xdg-autostart $DESKTOP_ENV # fi </pre> <p> In the above example, the comment symbol (#) was added before each line. The commenting method is preferred to just deleting the lines because you may want to add support for some of those startup items at a later time. Thus, leaving the default lines in place could ease that process. </p> <p> Adding your own programs to the <path>autostart.sh</path> script is as easy as writing in the program name for many applications. For instance, if you have Conky (a lightweight system monitor) installed, and want it to start automatically with your Openbox session, you simply add the following line to your <path>autostart.sh</path>: </p> <pre caption="Adding Conky to your autostart.sh"> conky & </pre> <p> The ampersand (&) after the command allows that application to load up in the background. You will most likely want to load all the applications in your <path>autostart.sh</path> script in the background because doing so will let Openbox and other programs load without the previous one finishing. </p> </body> </section> <section> <title>Setting the background</title> <body> <p> Some things that you might take for granted in bigger desktop environments are not included by default in Openbox. One such thing is setting your desktop background. In order to place an image as your wallpaper, you will need to emerge a program like feh or nitrogen. Feh is a simple image viewer that can also set the background, <e>and</e> it can easily be put into the autostart script. Once you have emerged feh, you can issue the following command to set the background: </p> <pre caption="Using feh to set the background image"> <comment>(feh has many other options instead of --bg-scale (which will scale the image to the screen dimensions). Consult the feh documentation.)</comment> $ <i>feh --bg-scale /path/to/image.jpg</i> </pre> <p> Once you have set the background manually, a file called <path>.fehbg</path> will be created in your home directory. This file simply contains the above command that you just entered in the terminal, and is automatically updated when you issue a different background command. Now, to set your background automatically upon login, you can add the following line to your <path>autostart.sh</path> script: </p> <pre caption="Using feh to set the background image"> source $HOME/.fehbg & </pre> </body> </section> </chapter> <chapter> <title>Programs to use with Openbox</title> <section> <title>This list</title> <body> <p> The following is a list of some programs which you might want to use within your Openbox environment. While the list contains numerous terminal emulators, file managers, panels, and more, it should by no means be considered exhaustive. If none of the programs listed fit your needs, please check the appropriate categories in Portage for more options. </p> </body> </section> <section> <title>Terminal emulators</title> <body> <ul> <li> <uri link="http://packages.gentoo.org/package/x11-terms/evilvte";> EvilVTE</uri> is an extremely lightweight terminal emulator based on (you guessed it) VTE. It supports tabs, multiple encodings, as well as an easy and extensible configuration file. </li> <li> <uri link="http://packages.gentoo.org/package/x11-terms/mrxvt";>Mrxvt</uri> is a multi-tabbed rxvt clone with XFT, transparent background and CJK support. It also features session support for each tab. </li> <li> <uri link="http://packages.gentoo.org/package/x11-terms/aterm";>Aterm</uri> supports transparency and backwards compatibility with rxvt. It was originally designed for the AfterStep window manager, but easily integrates with other environments. </li> <li> <uri link="http://packages.gentoo.org/package/x11-terms/eterm";>Eterm</uri> is a terminal based on vt102 and designed to be a more feature-rich replacement for xterm. </li> <li> <uri link="http://packages.gentoo.org/package/x11-terms/rxvt-unicode";>Rxvt-unicode</uri> is a clone of rxvt that supports Unicode, daemons, embedded perl, and multiple fonts simultaneously. </li> <li> <uri link="http://packages.gentoo.org/package/x11-terms/terminal";>Terminal</uri> is the VTE-based default for the Xfce desktop environment. It is a little on the bloated side for use with Openbox, as it pulls in many libraries for Xfce. </li> </ul> </body> </section> <section> <title>Desktop management</title> <body> <ul> <li> Though <uri link="http://packages.gentoo.org/package/x11-misc/pcmanfm";>PCManFM</uri> is mainly a file manager, it also gives you the option to manage the desktop background (instead of using feh or nitrogen) and draw desktop icons. It should be noted that with the current release (0.5), it is not readily possible to get rid of the default "My Documents" icon on the desktop. </li> <li> <uri link="http://packages.gentoo.org/package/x11-misc/idesk";>iDesk</uri> is a simple program used to draw desktop icons. It supports shadowed and anti-aliased fonts, PNG images, "snap-to-grid" placement, and changing the desktop background. </li> </ul> </body> </section> <section> <title>Panels</title> <body> <ul> <li> Currently not in the official tree, <uri link="http://code.google.com/p/tint2/";>Tint2</uri> is a simple panel and taskbar specifically made for Openbox3 (based on the ttm code). It supports colour/transparency, a clock, and drag and drop between virtual desktops. Currently, it is not available in the official Portage tree, but is available in overlays. </li> <li> <uri link="http://packages.gentoo.org/package/x11-misc/pypanel";>PyPanel</uri> is an easily customised panel written in Python and C. It features transparency, shading, tinting, location and layout configuration, font type, autohiding, application launcher, clock, and more. </li> <li> <uri link="http://packages.gentoo.org/package/lxde-base/lxpanel";>LXPanel</uri> is the default panel and taskbar from LXDE. It features a launcher, menu, clock, and a GUI-based configurator. It is feature-rich while depending on very few packages, making it a good choice for a lean system. </li> <li> <uri link="http://packages.gentoo.org/package/xfce-base/xfce4-panel";>Xfce4-panel</uri> is the default panel from the Xfce desktop environment. It supports application launchers, detachable menus, a pager, tasklist, clock, and more. It does, however, require a few of the Xfce libraries which are not dependencies of some other panels. </li> </ul> </body> </section> <section> <title>File Managers</title> <body> <ul> <li> <uri link="http://packages.gentoo.org/package/x11-misc/pcmanfm";>PCManFM</uri> is the lightweight filemanager from LXDE. It supports tabbed browsing, drag and drop, thumnails for images, bookmarks, volume management, searching, and more. It also provides supports for managing the desktop background and drawing desktop icons (both optionally). </li> <li> <uri link="http://packages.gentoo.org/package/xfce-base/thunar";>Thunar</uri> is the standard file manager from Xfce. It features a bulk renamer, user-customisable actions, and an extension framework. Since it depends on many Xfce libraries, it isn't as lightweight as PCManFM, but it's still slimmed down by comparison to other file managers like Nautilus (from GNOME), and Konqueror (from KDE). </li> <li> <uri link="http://packages.gentoo.org/package/gnome-base/nautilus";>Nautilus</uri> is the powerful file manager from the GNOME desktop environment. It features volume management, thumbnails for images, searching, and some system configuration. As it depends on many of the GNOME libraries for proper function, it can seem a heavy compared to some of the other file managers. </li> <li> <uri link="http://packages.gentoo.org/package/app-misc/gentoo";>Gentoo</uri> (no relation to this glorious Linux distribution) is a two-pane style file manager based on GTK+ 1.x. It is incredibly lightweight, but lacks a majority of the features now prominent in modern file managers. It should definitely be considered for older hardware, or if you are wanting a barebones setup. </li> <li> <uri link="http://packages.gentoo.org/package/app-misc/emelfm2";>emelFM2</uri> is another file manager in the vein of Midnight Commander. It features a three-pane window, and is requires GTK+ 2.6.x or higher. As with the Gentoo file manager (listed above), it is barebones and does not include many features prevalent in newer file managers. </li> </ul> </body> </section> <section> <title>Miscellaneous</title> <body> <ul> <li> <uri link="http://packages.gentoo.org/package/app-admin/conky";>Conky</uri> is a lightweight system monitor that can natively display over 250 objects, including date and time, CPU usage, memory usage, IMAP/POP3 email, top processes, and even info from your music player. It is highly customisable both in appearance and data display. </li> <li> <uri link="http://packages.gentoo.org/package/media-gfx/feh";>feh</uri> is a simple image viewer that runs from the terminal, but it also has many other features. It can display a slideshow of images, create an index print, dynamically zoom, and set the desktop background (detailed instructions above). </li> </ul> </body> </section> </chapter> <chapter id="inside-desktop-env"> <title>Openbox inside desktop environments</title> <section> <title>LXDE (default)</title> <body> <p> If installing each component of a working environment sounds like a little <e>too</e> much customisation, but you still want the flexibility of Openbox, you may want to look into a desktop environment that uses Openbox as its default window manager. That environment is <uri link="http://www.lxde.org/";>LXDE</uri>, the Lightweight X Desktop Environment. Designed to require even less system resources than Xfce, it is built around Openbox and some of the packages mentioned above (like PCManFM and LXpanel). </p> </body> </section> <section> <title>Openbox inside GNOME</title> <body> <p> If you already have a GNOME environment installed, you may just want to replace the Metacity window manager with Openbox. Fortunately, this is quite a simple task! You will need to fire up your favourite editor, open your <path>~/.xinitrc</path> file, and put the following command inside it: </p> <pre caption="Adding an Openbox-GNOME session to your .xinitrc"> exec openbox-gnome-session </pre> <p> If you use GDM or another graphic login manager, you will see a new "GNOME/Openbox" option in your session menu. You can simply select that option instead of manually editing your <path>~/.xinitrc</path>. </p> <note> This method of using Openbox with GNOME has been tested with the GNOME 2.22 release. While it seems highly likely that it will work with GNOME 2.24 and above, it has not been thoroughly tested as of yet. </note> </body> </section> <section> <title>Openbox inside KDE</title> <body> <p> Say you have KDE installed and like it, but you want more flexibility with your window management than KWin offers. You can use Openbox as your window manager inside of KDE by simply editing your <path>~/.xinitrc</path> file, and replacing your current exec command with the following: </p> <pre caption="Adding an Openbox-KDE session to your .xinitrc"> exec openbox-kde-session </pre> <p> Now when you issue <c>startx</c> you will see KDE, but instead of KWin, you will have the customisability of the Openbox window manager. </p> <p> If you use KDM or another graphic login manager, you will see a new "KDE/Openbox" option in your session menu. You can simply select that option instead of manually editing your <path>~/.xinitrc</path>. </p> <note> This method of using Openbox with KDE has been tested with the KDE 3.x releases. While it seems highly likely that it will work with the KDE 4.x series, it has not been thoroughly tested as of yet. </note> </body> </section> <section> <title>Openbox inside Xfce</title> <body> <p> If you use Xfce4 and would like to replace xfwm4 with Openbox, you will need to go about it a little differently than with KDE or GNOME. Firstly, you need to start your normal Xfce session, and open up a terminal. From the terminal, issue the following command: </p> <pre caption="Killing xfwm4 and replacing it with Openbox"> $ <i>killall xfwm4 ; openbox & exit</i> </pre> <p> Secondly, you need to exit out of your Xfce session, and make sure to tick the checkbox that says "Save session for future login." This will keep Openbox as your default window manager. Thirdly, you will notice that you can't logout properly when using the default menu action. To fix this problem, open up your <path>menu.xml</path>, and locate this line: </p> <pre caption="Finding the exit action in menu.xml"><![CDATA[ <item label="Exit"> <action name="Exit"/> </item> </pre> <br /> and change it to this: <br /> <pre caption="Replacing the exit action in menu.xml"> <item label="Exit"> <action name="Execute"> <command>xfce4-session-logout</command> </action> </item> ]]></pre> <note> With Xfce4, the root-menu provided by Xfdesktop will be used instead of the Openbox root-menu. </note> </body> </section> </chapter> <chapter> <title>Further documentation</title> <section> <title>External resources</title> <body> <p> While this document will easily take you through the inital installation and customisation of Openbox, it is by no means the only reference on the topic. There are several other resources that will aid you in creating your perfect Openbox setup. Some of them are listed below: </p> <ul> <li> On <uri link="http://icculus.org/openbox/index.php/Main_Page";>The Official Openbox website</uri> you will find more detailed information regarding theming, creating menus (including pipe menus), autostart scripting, and much more. This site also has information regarding new releases, upgrades, and instructions on how you can contribute to development. </li> <li> The <uri link="http://urukrama.wordpress.com/openbox-guide/";>Urukrama's Guide to Openbox</uri> blog contains a plethora of information about switching GTK+ themes, setting up keybindings, desktop effects, and other programs to use in conjunction with Openbox. Though the tutorial was originally written for use with Ubuntu, everything should be applicable to Gentoo (and other Linux distributions for that matter). </li> <li> <uri link="http://www.box-look.org/";>Box-Look</uri> provides numerous themes, icons, wallpapers, fonts, and tools to be used with Openbox (as well as the other *box window managers like Fluxbox, Blackbox, PekWM, etc.) </li> </ul> </body> </section> </chapter> </guide>
