Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[doc] Add autogeneration of options documentation 

Signed-off-by: Julien Danjou <julien@danjou.info>
This commit is contained in:
Julien Danjou 2008-03-27 16:48:52 +01:00
parent c834134cc8
commit 25b22a7cb9
7 changed files with 123 additions and 674 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -28,3 +28,4 @@ awesome-version-internal.h
awesome-message
awesome-menu
uicbdocgen.txt
optsdocgen.txt

14
Makefile.am
View File

@ -215,11 +215,12 @@ dist_iconslayouts_DATA += icons/layouts/tiletopw.png
dist_iconslayouts_DATA += icons/layouts/tilew.png
clean-local:
rm -f awesome*.1 awesome*.1.xml awesome*.5 awesome*.5.xml
rm -f awesome*.1 awesome*.1.xml awesome*.5 awesome*.5.xml optsdocgen.txt uicbdocgen.txt
SUFFIXES += .1.xml .1
SUFFIXES += .5.xml .5
EXTRA_DIST += build-utils/extractdoc.py
EXTRA_DIST += build-utils/extractuicbdoc.py
EXTRA_DIST += build-utils/extractoptsdoc.py
if HAVE_XMLTO
.1.xml.1:
$(XMLTO) man $<
@ -230,11 +231,16 @@ endif
SUFFIXES += .1.txt .1.xml
SUFFIXES += .5.txt .5.xml
if HAVE_ASCIIDOC
optsdocgen.txt:
$(top_srcdir)/build-utils/extractoptsdoc.py \
$(top_srcdir)/common/configopts.c > optsdocgen.txt
uicbdocgen.txt:
$(top_srcdir)/build-utils/extractdoc.py $(top_srcdir)/*.c > uicbdocgen.txt
$(top_srcdir)/build-utils/extractuicbdoc.py \
$(top_srcdir)/*.c > uicbdocgen.txt
.1.txt.1.xml:
$(ASCIIDOC) -d manpage -b docbook -o $@ $<
.5.txt.5.xml: uicbdocgen.txt
awesomerc.5.xml: optsdocgen.txt uicbdocgen.txt
.5.txt.5.xml:
$(ASCIIDOC) -d manpage -b docbook -o $@ $<
endif

684
awesomerc.5.txt
View File

@ -8,236 +8,40 @@ awesomerc - Configuration file for the 'awesome window manager'
SYNOPSIS
--------
<item> [<argument>]
..........................
<section> [title]
{
<option> = <value>
<item> [<argument>] { <option> = <value>, ... }
....
<section> [title]
{
<option> = <value>
...
}
...
}
<option> = <value>
include(file.conf)
..........................
DESCRIPTION
-----------
The awesomerc file contains configuration informations for *awesome*. It can
The *awesomerc* file contains configuration informations for *awesome*. It can
be used to configure the behaviour and look of awesome in a variety of ways.
It is read at startup.
OPTIONS
--------
awesomerc contains 4 global sections: *screen*, *rules*, *keys* and *mouse* which
*awesomerc* contains 5 global sections: *screen*, *rules*, *keys*, *mouse* and *menu* which
are described here.
screen
~~~~~~
This is the global section for a physical screen. It must have a title with screen number,
starting at 0. It contains several subsections, which are *general*, *tags*, *layouts*, *styles*,
*padding* and *statusbar*.
All this sections contain options which may be string, integer, float, or even sections again.
general
^^^^^^^
General is a section containing some general options for this screen.
titlebar::
This section defines the parameters of the windows titlebar.
border::
This defines the window borders size in pixel.
new_become_master::
If this is set to true, new windows will become the master window.
new_get_focus::
If this is set to true, new windows will get focus.
opacity_unfocused::
If this is set to a float value between 0 and 1, non-focused windows will have this opacity.
This requires an external XComposite manager.
opacity_focused::
If this is set to a float value between 0 and 1, focused windows will have this opacity.
This requires an external XComposite manager.
resize_hints::
If this is set to true, resize hints given by the window will be respected.
If this is set to false, window size will be forced.
If you dislike gaps between windows, you should try to set it to false.
sloppy_focus::
If this is set to true, focus will be set to the window under the mouse. If not,
you will have to click on a window to set it focused.
sloppy_focus_raise::
If this is set to true with sloppy_focus, when a window is focused with the mouse
it will be raised on top of the windows stack.
snap::
Snap windows to the screen border when it is this pixel away only from the border.
floating_placement::
Select the floating placement algorithm to use when placing window.
tags
^^^^
Tags is a section containing one or more tag sections, which defines a tag.
tag
+++
Tag is a section which contains several options defining a tag.
layout::
Layout is a name of an available layout which will be set by default on this tag.
mwfact::
Set the default master width factor for this tag.
ncol::
Set the default number of columns for non-master windows for this tag.
nmaster::
Set the default number of windows which will be treated as master for this tag.
layouts
^^^^^^^
Layouts is a section containing a layout list, where each layout is a layout section.
layout
++++++
Layout is a section which define a layout. It has a title which is the algorithm to use.
image::
Set the image path used to describe this layouts, useful in layoutinfo widget.
styles
^^^^^^
Styles is a section containing the style parameters which is composed of a normal, focus and urgent
subsection each ones containing:
font::
The font to use.
fg::
Set the foreground color.
bg::
Set the background color.
border::
Set the window's border color.
shadow::
Set the shadow color.
shadow_offset::
Set the shadow offset in pixel.
padding
^^^^^^^
Padding is a section containing screen padding parameters.
top::
Set the top padding in pixel.
bottom::
Set the bottom padding in pixel.
left::
Set the left padding in pixel.
right::
Set the right padding in pixel.
statusbar
^^^^^^^^^
Statusbar are sections containing statusbars parameters. Each statusbar section
must have a title which is the statusbar name. Each statusbar can have none or
several widgets (see WIDGETS section for more details) each one identified by its
name.
position::
Default statusbar position.
height::
Statusbar height. By default, is auto computed with font size.
width::
Statusbar width. By default, it will be whole screen.
rules
~~~~~
Rules is a section containing a rule list to automatically configure windows.
rule
^^^^
Rule are sections containing the auto-configuration options for one window.
name::
Set the window name for name matching as a regular expression.
xproperty_name::
Set the name of the XProperty for XProperty matching.
xproperty_value::
Set the regular expression to match against the named XProperty's value.
float::
Set the window to be floating. One of auto, true or false. Defaults to auto.
master::
Set the window to be the master. One of auto, true or false. Defaults to
auto.
tags::
Set the tags to be assigned to the window as a regular expression.
screen::
Set the screen the window should show up on.
icon::
Set the window's icon.
opacity::
Set the window's opacity.
keys
~~~~
Keys is the section to define your keybindings in. It may consist of multiple
key and keylist entries.
key
^^^
In a key section you define a single keybinding.
key::
The keysym you want to bind.
mod::
Modifiers that need to be pressed for this binding.
command::
The *uicb function* to call.
arg::
The argument to the *uicb function*, if needed.
keylist
^^^^^^^
In a keylist you can define multiple very similar keybindings at once. For
example you can define <Mod1>-{1..9} to switch the view to tag 1..9
respectively.
keylist::
The list of keysyms to bind.
modkey::
Modifiers that need to be pressed for these bindings.
command::
The *uicb function* to call.
arglist::
The list of arguments to the *uicb function*, if needed. *Must* match the
length of *keylist*.
mouse
~~~~~
In the mouse section you may define mouse button bindings for the root and
client windows.
client
^^^^^^
Defines a mouse button binding for events on clients.
button::
The mouse button you want to bind.
modkey::
Modifiers that need to be pressed for this binding.
command::
The *uicb function* to call.
arg::
The argument to the *uicb function*, if needed.
root
^^^^
Defines a mouse button binding for events on the root window.
button::
The mouse button you want to bind.
modkey::
Modifiers that need to be pressed for this binding.
command::
The *uicb function* to call.
arg::
The argument to the *uicb function*, if needed.
include::optsdocgen.txt[]
UICB FUNCTIONS
--------------
@ -248,467 +52,18 @@ or a mouse button.
include::uicbdocgen.txt[]
WIDGETS
-------
Statusbars can be customized by modifying widgets names, order and options.
taglist
~~~~~~~
This widget shows the tag list.
*mouse*::
Set mouse bindings.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
layoutinfo
~~~~~~~~~~
This widget shows a icon for the selected layout.
*mouse*::
Set mouse bindings.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
focusicon
~~~~~~~~~
This widget shows a icon for the focused window using NET_WM_ICON or icon file set in rule.
*mouse*::
Set mouse bindings.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
tasklist
~~~~~~~~
This widget shows a list of running windows.
*mouse*::
Set mouse bindings.
*styles*::
Style section with normal, focus and urgent subsections.
*text_align*::
Text alignement.
*show_icons*::
Show applications icons.
*show*::
Show all windows from all tags, tags clients only or focused client.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
textbox
~~~~~~~
This widget shows a text.
*mouse*::
Set mouse bindings.
*width*::
Set width.
*style*::
Style section with <style section>
*text*::
Text to change.
*text_align*::
Text alignement.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
iconbox
~~~~~~~
This widget shows an icon.
*mouse*::
Set mouse bindings.
*image*::
Image file.
*resize*::
Resize icon to fit into statusbar.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
progressbar
~~~~~~~~~~~
This widget shows one or more progress-bars.
*data*::
Draws a bar for each data section;
Options: reverse, fg, fg_center, fg_end, fg_off, bg, bordercolor.
*reverse*::
Reverse/mirror the bar.
*fg*::
Foreground color.
*fg_center*::
Foreground color in the center of the bar (as gradient).
*fg_end*::
Foreground color at the end of a bar (as gradient).
*fg_end*::
Foreground color of not filled bar.
*bg*::
Background color (between bar and border).
*bordercolor*::
Border color.
*mouse*::
Set mouse bindings.
*width*::
Set width.
*height*::
Set height (i.e. 0.9 = 90%)
*padding*::
Empty space on both sides.
*vertical*::
Draw the bar(s) vertically/standing up.
*ticks_count*::
Number of 'ticks' to draw.
*ticks_gap*::
Distance between the ticks.
*border_width*::
Border width in pixels.
*border_padding*::
Padding between border and ticks/bar.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
graph
~~~~~
This widget shows a graph.
*data*::
Defines a data-stream section;
Options: max, scale, fg, fg_center, fg_end and draw_style.
*max*::
This value prints a full graph (default = 100).
*scale*::
Re-scales when input > max (see below).
*fg*::
Foreground color.
*fg_center*::
Foreground color in the center of the bar (as gradient).
*fg_end*::
Foreground color at the end of a bar (as gradient).
*vertical_gradient*
If true, create a gradient from 0 > full instead of new > old values
*draw_style*::
bottom (fills from bottom to top), top, or line.
*mouse*::
Set mouse bindings.
*width*::
Set width.
*height*::
Set height (i.e. 0.9 = 90%).
*padding_left*::
Empty space on the left.
*grow*::
Put new values onto the 'left' or 'right'.
*bg*::
Background color.
*bordercolor*::
Border color.
*x*::
Horizontal offset (auto-alignment if not set).
*y*::
Vertical offset (auto-alignment if not set).
*align*::
Widget alignment.
FORMAT
------
Here is the global configuration file format, with a list of options
and possible values.
..............................................
Note: when there is no whitespace, quotes are optional.
<boolean> -> "true" or "false"
<color> -> #ff9933 (hexadecimal color notation: #red green blue)
<float> -> 0.3, 0,8 (often values between 0 and 1 are useful)
<font> -> Pango font: sans 10, sans italic 10, fixed 12, ...
<identifier> -> foobar (choose a name/string)
<image> -> "/home/awesome/pics/icon.png" (path to image)
<integer> -> 1, 10, -3 (positive numbers are required mostly)
<key> -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
or a keycode beginning with #
<mod> -> "Mod1", "Mod4", "Control" (modifiers)
<regex> -> regular expression
<string> -> "foo bar"
<uicb-arg> -> prog, 3... (argument to a uicb function, where required)
<uicb-cmd> -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
<position> -> list of position: off, top, right, left, bottom, auto
<{.., ...}> -> list of available options
<style section> -> a section with font, fg, bg, border, shadow and shadow_offset options.
{ font = <font> fg = <color> bg = <color> border = <color>
shadow = <color> shadow_offset = <integer> }
<titlebar> -> a section with position and icon position.
{ position = <position> icon = <position> text_align = <{center,right,left}>
height = <integer> width = <integer> styles { } }
[MULTI] means, you can use an item multiple times.
screen <integer> [MULTI]
{
general
{
border = <integer>
new_become_master = <boolean>
new_get_focus = <boolean>
opacity_unfocused = <integer>
opacity_focused = <integer>
resize_hints = <boolean>
sloppy_focus = <boolean>
sloppy_focus_raise = <boolean>
snap = <integer>
floating_placement = <{smart,under_mouse}>
mwfact_lower_limit = <float>
mwfact_upper_limit = <float>
}
titlebar
{
<titlebar>
}
tags
{
tag <identifier> [MULTI]
{
layout = <{dwindle,floating,max,
spiral,tile,tileleft,tilebottom,tiletop}>
mwfact = <float>
nmaster = <integer>
ncol = <integer>
}
}
layouts
{
layout <{dwindle,floating,max,
spiral,tile,tileleft,
tilebottom,tiletop}> { image = <image> } [MULTI]
}
styles
{
normal { <style section> }
focus { <style section> }
urgent { <style section> }
}
padding
{
top = <integer>
bottom = <integer>
left = <integer>
right = <integer>
}
statusbar <identifier> [MULTI]
{
position = <{top,bottom,left,right,off}>
height = <integer>
width = <integer>
taglist <identifier> [MULTI]
{
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
layoutinfo <identifier>
{
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
focusicon <identifier>
{
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
tasklist <identifier>
{
styles
{
normal { <style section> }
focus { <style section> }
}
show_icons = <boolean>
show = <{all,tags,focus}>
text_align = <{center,left,right}>
x = <integer> y = <integer>
mouse [MULTI]
{
command = <uicb-cmd> arg = <uicb-arg>
button = <integer> modkey = {<mod>, ...}
}
}
textbox <identifier> [MULTI]
{
style { <style section> }
text = <string>
width = <integer>
text_align = <{center,left,right}>
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
iconbox <identifier> [MULTI]
{
image = <image>
resize = <boolean>
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
progressbar <identifier> [MULTI]
{
data [MULTI]
{
reverse = <boolean> bg = <color> bordercolor = <color>
fg = <color> fg_center = <color> fg_end = <color> fg_off = <color>
}
gap = <integer>
width = <integer>
height = <float>
padding = <integer>
vertical = <boolean>
ticks_count = <integer>
ticks_gap = <integer>
border_width = <integer>
border_padding = <integer>
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
graph <identifier> [MULTI]
{
data [MULTI]
{
scale = <boolean> max = <float> draw_style = <{bottom, top, line}>
fg = <color> fg_center = <color> fg_end = <color>
vertical_gradient = <boolean>
}
width = <integer>
height = <float>
padding_left = <integer>
grow = <{left, right}>
bg = <color>
bordercolor = <color>
x = <integer> y = <integer>
align = <{auto,right,left}>
mouse [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
}
}
rules
{
rule [MULTI]
{
name = <regex>
xproperty_name = <string>
xproperty_value = <regex>
float = <{auto,true,false}>
master = <{auto,true,false}>
tags = <regex>
screen = <integer>
icon = <image>
opacity = <float>
titlebar
{
<titlebar>
}
}
}
keys
{
key [MULTI]
{
key = <key> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
keylist [MULTI]
{
keylist = {<key>, ...}
modkey = {<mod>, ...}
command = <uicb-cmd>
arglist = {<uicb-arg>, ...}
}
}
mouse
{
client [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
root [MULTI]
{
button = <integer> modkey = {<mod>, ...}
command = <uicb-cmd> arg = <uicb-arg>
}
}
..............................................
EXAMPLES
--------
Check awesome's wiki: http://awesome.naquadah.org/wiki/
More examples are available on awesome's wiki:
http://awesome.naquadah.org/wiki/
Simple textbox example
~~~~~~~~~~~~~~~~~~~~~~
..............................................
1. Add an include directive into ~/.awesomerc
screen 0 {
include(~/.awesome/bottom-status-bar)
screen 0 { include(~/.awesome/bottom-status-bar) }
2. Create ~/.awesome/bottom-status-bar
@ -760,10 +115,7 @@ Simple progressbar example
1. Add an include directive into ~/.awesomerc
screen 0
{
include(~/.awesome/bottom-status-bar)
}
screen 0 { include(~/.awesome/bottom-status-bar) }
2. Create ~/.awesome/bottom-status-bar
@ -821,7 +173,7 @@ $ chmod a+x ~/bin/awesome-diskusage
SEE ALSO
--------
awesome(1) awesome-client(1)
awesome(1) awesome-client(1) awesome-menu(1) awesome-message(1)
AUTHORS

81
build-utils/extractoptsdoc.py Executable file
View File

@ -0,0 +1,81 @@
#!/usr/bin/python
#
# extractoptsdoc.py - extract options documentation from awesome sour code
# Copyright (C) 2008 Julien Danjou <julien@danjou.info>
#
# This indeed crappy. Any better version, even with awk, would be welcome.
#
import sys
def section_print(section, options):
print section
i = 0
underline = ""
while i < len(section):
underline += "~"
i += 1
print underline
for option, format in options.items():
print "%s::" % option
print " %s" % format
print
def sections_print(sections):
section_print("Base sections", sections['awesome'])
keylist = sections.keys()
keylist.sort()
for key in keylist:
if key != "awesome":
section_print(key, sections[key])
def sections_get(file):
sections = {}
section_doc = {}
section_begin = False
for line in file.readlines():
if line.startswith("cfg_opt_t"):
section_name = (line.split(" ", 1)[1]).split("_opts")[0]
section_begin = True
continue
if section_begin and line.startswith("};"):
section_begin = False
sections[section_name] = section_doc
section_doc = {}
continue
if section_begin and line.startswith(" CFG_"):
if line.startswith(" CFG_AWESOME_END"):
continue
option_title = line.split("\"")[1].split("\"")[0]
if lastline.startswith(" /**"):
section_doc[option_title] = lastline[8:-3]
else:
section_doc[option_title] = "Undocumented option. "
if line.startswith(" CFG_INT"):
section_doc[option_title] += "This option must be an integer value."
elif line.startswith(" CFG_BOOL"):
section_doc[option_title] += "This option must be a boolean value."
elif line.startswith(" CFG_FLOAT"):
section_doc[option_title] += "This option must be a float value."
elif line.startswith(" CFG_ALIGNMENT"):
section_doc[option_title] += "This option must be an alignment value."
elif line.startswith(" CFG_POSITION"):
section_doc[option_title] += "This option must be a position value."
elif line.startswith(" CFG_STR"):
section_doc[option_title] += "This option must be string value."
elif line.startswith(" CFG_SEC"):
secname = (line.split(", ")[1]).split("_opts", 1)[0]
section_doc[option_title] += "This option must be a section `%s'" % secname
if line.find("CFGF_MULTI") != -1:
section_doc[option_title] += ", can be specified multiple times"
if line.find("CFGF_NO_TITLE_DUPES") != -1:
section_doc[option_title] += ", must have a unique title"
elif line.find("CFGF_TITLE") != -1:
section_doc[option_title] += ", must have a title"
section_doc[option_title] += "."
lastline = line
return sections
sections_print(sections_get(file(sys.argv[1])))

4
build-utils/extractdoc.py → build-utils/extractuicbdoc.py
View File

@ -1,7 +1,7 @@
#!/usr/bin/python
#
# extractdoc.py - extract uicb documentation from awesome sour code
# Copyright ® 2008 Julien Danjou <julien@danjou.info>
# extractuicbdoc.py - extract uicb documentation from awesome sour code
# Copyright (C) 2008 Julien Danjou <julien@danjou.info>
#
# This indeed crappy. Any better version, even with awk, would be welcome.
#

2
build-utils/widgetgen.sh
View File

@ -11,8 +11,6 @@ do
do
shortname=$(echo $widget | cut -d_ -f1)
echo " {\"$shortname\", $widget},"
grep -q "^$shortname" ${top_srcdir}/awesomerc.5.txt || \
echo " WARNING: $uicb NOT documented" >&2
done
done

11
common/configopts.c
View File

@ -155,20 +155,31 @@ cfg_getposition(cfg_t *cfg, const char *name)
return cfg_getnposition(cfg, name, 0);
}
/** This section is used to defined a style. */
cfg_opt_t style_opts[] =
{
/** This defines the border color. */
CFG_STR((char *) "border", NULL, CFGF_NONE),
/** This defines the background color. */
CFG_STR((char *) "bg", NULL, CFGF_NONE),
/** This defines the foreground color. */
CFG_STR((char *) "fg", NULL, CFGF_NONE),
/** This defines the shadow color. */
CFG_STR((char *) "shadow", NULL, CFGF_NONE),
/** This defines the shadow offset in pixel. */
CFG_INT((char *) "shadow_offset", 0, CFGF_NONE),
/** This defines the font being used */
CFG_STR((char *) "font", NULL, CFGF_NONE),
CFG_AWESOME_END()
};
/** This section is used to defined several styles in a row */
cfg_opt_t styles_opts[] =
{
/** This defines a normal style. */
CFG_SEC((char *) "normal", style_opts, CFGF_NONE),
/** This defines a focus style. */
CFG_SEC((char *) "focus", style_opts, CFGF_NONE),
/** This defines an urgent style. */
CFG_SEC((char *) "urgent", style_opts, CFGF_NONE),
CFG_AWESOME_END()
};