Added fluxbox-apps(5) manpage

This now shares the CLIENT PATTERNS section in common with fluxbox-keys(5), so I
split this out into a client-patterns.txt which is included by both
fluxbox-apps.txt and fluxbox-keys.txt.

1 files changed, 269 insertions, 0 deletions

diff --git a/doc/asciidoc/fluxbox-apps.txt b/doc/asciidoc/fluxbox-apps.txt
new file mode 100644
index 0000000..a2776fa
--- /dev/null
+++ b/doc/asciidoc/fluxbox-apps.txt
@@ -0,0 +1,269 @@
+fluxbox-apps(5)
+===============
+Jim Ramsay <i.am@jimramsay.com>
+v1.1.1, 10 February 2009
+:man source:   fluxbox-apps.txt
+:man version:  {revision}
+:man manual:   Fluxbox Manual
+
+NAME
+----
+fluxbox-apps - per-window attribute configuration for fluxbox(1)
+
+SYNOPSIS
+--------
+~/.fluxbox/apps
+
+SYNTAX
+------
+Variable parameters are shown in emphasis: 'argument'
+
+All other characters shown are required verbatim. Whitespce is only required to
+delimit words, but it is fine to add more whitespace.
+
+DESCRIPTION
+-----------
+It is possible to force an application to always have the same dimensions,
+position, and other settings when it is first launched. These settings are saved
+in the `apps' file.
+
+Most simple settings can be saved using the `Remember' submenu of the window
+menu, which can usually be opened with a right-click on the titlebar. More
+advanced features require manually editing the `apps' file. This may include
+using *GROUP SECTIONS* to set up automatic window tab groups.
+
+The file is made up of two main types of sections, apps and groups, detailed
+below.
+
+APP SECTIONS
+------------
+*[app]* sections provide settings for individual application windows.
+
+These sections begin with a line of the format:::
+        *[app]* *(*'pattern'*)* *{*'count'*}*
+
+The 'pattern' can be one or more patterns which match windows. For more
+details, see *CLIENT PATTERNS*. If you specify more than one 'pattern', they
+must ALL match for the settings to be applied.
+
+The *{*'count'*}* is optional. If specified, then the entry will only match at
+most that many windows at any time. If omitted, the default is to apply the
+settings to all matching windows.
+
+This opening *[apps]* line is followed by any number of settings for the
+application. See *SETTINGS* for more details.
+
+Each of these sections ends with the single line:::
+        *[end]*
+
+GROUP SECTIONS
+--------------
+The primary purpose of *[group]* sections is to group windows together. All
+windows in a group will be tabbed together automatically.
+
+These sections begin with a line of the format:::
+        *[group]* *(*'pattern'*)*
+
+Where the 'pattern' item is optional. If specified, this pattern must match for
+the group to take effect. It is common to use non-window-specific patterns such
+as *(workspace)* here. See *CLIENT PATTERNS* for more details.
+
+This is followed by any number of *[app]* lines. These have a simiar format to
+the *[app]* section detailed above in *APP SECTIONS*, but do not contain any
+settings and do not have an associated *[end]* line.
+
+Like this:::
+        *[app]* *(*'pattern'*)*
+
+This section may also contain settings that are applied to every window in the
+group. See the *SETTINGS* section for details.
+
+As with *[app]* sections, each of these sections ends with the single line:::
+        *[end]*
+
+SETTINGS
+--------
+These settings may be stored in the `apps' file. A settings line must appear
+inside either an *[app]* or *[group]* section.
+
+The general format is:::
+        *[*'setting'*]* *{*'value'*}*
+
+All allowed values are described below, except for 'bool' which can simply have
+the value *yes* or *no*, which enables or disables the associated setting,
+respectively.
+
+*[Workspace]* {'number'}::
+        Forces the application to open on the 'number' workspace specified.
+        Workspaces are set by number, beginning with 0.
+
+*[Jump]* {'bool'}::
+        Changes the active workspace to the remembered one when the application is
+        opened. This is only useful when used in conjunction with '[Workspace]'. See
+        *EXAMPLES*.
+
+*[Head]* {'number'}::
+        Forces the application to open on the 'number' head specified (Xinerama
+        only).
+
+*[Layer]* {'number'}::
+        Specify the layer to open the window on (by number). Each layer has a
+        number. The named ones are: 2-AboveDock, 4-Dock, 6-Top, 8-Normal, 10-Bottom,
+        12-Desktop.
+
+*[Dimensions]* {'width' 'height'}::
+        Opens the application with the specified 'width' and 'height', in pixels.
+
+*[Position]* ('anchor') {'X' 'Y'}::
+Position the application at a particular spot. By default the upper-left corner
+is placed at screen coordinates ('X','Y'). If you specify an 'anchor', say
+BottomRight, then the lower-right corner of the window is positioned ('X','Y')
+pixels from the lower-right corner of the screen.
++
+'anchor' may be set to one of:;;
+*TopLeft Left BottomLeft Top Center Bottom TopRight Right BottomRight*
+
+*[Deco]* {'value'}::
+Specify the decoration state. There are several predefined 'value' sets:;;
++
+--
+        *NORMAL*;;
+                Standard decorations
+        *NONE*;;
+                No decorations
+        *TAB*
+                Like TAB except keep the tabs
+        *Border*;;
+                Like NONE except keep the X window border
+        *TINY*;;
+                Titlebar with only an iconify button
+        *TOOL*;;
+                Titlebar only
+
+--
++
+The 'value' may also be a bitmask for finer-grained control. The bits are, from
+(1<<0) to (1<<10): Titlebar, Handle/Grips, Border, Iconify Button, Maximize
+Button, Close Button, Menu Enabled, Sticky Button, Shade Button, Tabbing
+enabled, Focus Enabled.
+
+*[Shaded]* {'bool'}::
+        Whether the window is Shaded (rolled-up) or not.
+
+*[Tab]* {'bool'}::
+        Whether the window has tabs enabled.
+
+*[FocusHidden]* {'bool'}::
+        If enabled, the window will not appear in 'NextWindow'/'PrevWindow' lists.
+
+*[IconHidden]* {'bool'}::
+        If enabled, the window will not appear in the icon area of the toolbar.
+
+*[Hidden]* {'bool'}::
+        A shortcut for setting both *FocusHidden* and *IconHidden* at the same time.
+
+*[Sticky]* {'bool'}::
+        Specify if an application should be sticky (shown on all workspaces) or not.
+
+*[Minimized]* {'bool'}::
+        Application should start minimized
+
+*[Maximized]* {'value'}::
+Application should start maximized. 'value' may be:;;
++
+--
+        *yes*;;
+                Fully maximized
+        *horz*;;
+                Horizontally maximized
+        *vert*;;
+                Vertically maximized
+        *no*;;
+                Not maximized
+
+--
+
+*[Fullscreen]* {'bool'}::
+        Application should start in fullscreen mode (fully maximized without any
+        decorations).
+
+*[Close]* {'bool'}::
+        Save settings on close. By default, application settings are not updated when
+        a window is closed.
+
+*[Alpha]* {'value' ['value']}::
+        Set the alpha value for this window. If two values are given, they
+        correspond to the focused and unfocused transparency, respectively. One
+        number only will be used for both values. 'value' is an integer between 0
+        and 255.
+
+CLIENT PATTERNS
+---------------
+include::client-patterns.txt[]
+
+FILES
+-----
+*~/.fluxbox/apps*::
+        This is the default location for the application settings.
+
+RESOURCES
+---------
+*session.appsFile:* 'location'::
+        This may be set to override the location of the application settings.
+
+EXAMPLES
+--------
+Here are some interesting and/or useful examples you can do with your apps
+file.
+
+..................
+# Put the first two windows which end with 'term' on workspace 1
+[app] (name=.*[tT]erm) {2}
+  [Workspace]   {1}
+[end]
+
+# Center kate with a specific size, and update these values when the window is
+# closed.
+[app] (name=kate)
+  [Dimensions]  {1022 747}
+  [Position]    (CENTER) {0 0}
+  [Close]       {yes}
+[end]
+
+# When starting konqueror, jump to workspace 1 first and start it there.
+[app] (name=konqueror)
+  [Workspace]   {1}
+  [Jump]        {yes}
+[end]
+
+# start all aterm without decorations
+[app] (name=aterm)
+  [Deco]        {NONE}
+[end]
+
+# a group with the gimp dock and toolbox
+# appears on layer 4 (bottom)
+[group]
+  [app] (name=gimp) (role=gimp-dock)
+  [app] (name=gimp) (role=gimp-toolbox)
+  [Layer]       {4}
+[end]
+..................
+
+AUTHOR and CREDITS
+------------------
+This manpage is the combined work of:
+
+- Jim Ramsay <i.am at jimramsay com> (>fluxbox-1.0.0)
+- Curt Micol <asenchi at asenchi com> (>fluxbox-0.9.11)
+- Tobias Klausmann <klausman at users sourceforge net> (<=fluxbox-0.9.11)
+- Grubert <grubert at users sourceforge net> (fluxbox)
+- Matthew Hawkins <matt at mh dropbear id au> (blackbox)
+- Wilbert Berendsen <wbsoft at xs4all nl> (blackbox)
+
+- Numerous other languages could be available if someone jumps in.
+
+SEE ALSO
+--------
+fluxbox(1), xev(1), xkill(1), regex(7)
+