diff --git a/.gitignore b/.gitignore index 5595759f..d4810a31 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,4 @@ layoutgen.h awesome-version-internal.h awesome-message awesome-menu +uicbdocgen.txt diff --git a/Makefile.am b/Makefile.am index c6135956..42dc1d43 100644 --- a/Makefile.am +++ b/Makefile.am @@ -219,6 +219,7 @@ clean-local: SUFFIXES += .1.xml .1 SUFFIXES += .5.xml .5 +EXTRA_DIST += build-utils/extractdoc.py if HAVE_XMLTO .1.xml.1: $(XMLTO) man $< @@ -229,9 +230,11 @@ endif SUFFIXES += .1.txt .1.xml SUFFIXES += .5.txt .5.xml if HAVE_ASCIIDOC +uicbdocgen.txt: + $(top_srcdir)/build-utils/extractdoc.py $(top_srcdir)/*.c > uicbdocgen.txt .1.txt.1.xml: $(ASCIIDOC) -d manpage -b docbook -o $@ $< -.5.txt.5.xml: +.5.txt.5.xml: uicbdocgen.txt $(ASCIIDOC) -d manpage -b docbook -o $@ $< endif diff --git a/awesomerc.5.txt b/awesomerc.5.txt index c1f0f229..00b14ef1 100644 --- a/awesomerc.5.txt +++ b/awesomerc.5.txt @@ -246,101 +246,7 @@ In awesome, a lot of *functions* are available. These functions are called uicb (User Interface Call Backs). Each function can be bound to a key shortcut or a mouse button. -General -~~~~~~~ -*quit*:: - This function quits awesome. -*statusbar_toggle* statusbar-identifier:: - Hide or show statusbar (with no argument, toggle all). -*spawn* client:: - Execute an external program. -*exec* program:: - Replace awesome with another window manager. -*restart*:: - Restart awesome. -*widget_tell* widget-identifier data:: - Feed information to your widgets. - -Client -~~~~~~ -*client_kill*:: - Closes the focused client. -*client_moveresize* x y width height:: - Dynamically move and resize floating windows. - Coordinates can be relative or absolute. Relative values must begin with + or -. - E.g: to move a window 10 pixels up: "+0 \+10 +0 +0" To move a window - in the upper left corner and increase its width by 10px: "0 0 \+0 +10" -*client_settrans* float:: - Set client transparency, number can be a relative or absolute floating number in percentage. -*client_swapnext*:: - Swap window placement with the next displayed window. -*client_swapprev*:: - Swap window placement with the previous displayed window. -*client_focusnext*:: - Focus next window. -*client_focusprev*:: - Focus previous window. -*client_togglemax*:: - Set window fullscreen. Calling this function another time will reset the window to its previous state. -*client_togglehorizontalmax*:: - Set window's horizontal size to display width. Calling another time will reset the window to its previous state. -*client_toggleverticalmax*:: - Set window's vertical size to display height. Calling another time will reset the window to its previous state. -*client_togglefloating*:: - Set window floating or tiled. -*client_zoom*:: - Set window as master window. -*client_movetoscreen* relative or absolute integer:: - Move focused window to the nth screen, or next (+1) or previous (-1). If no screen_number is set, move to the next screen. -*client_tag* tag number:: - Tag focused window with this tag. -*client_toggletag*:: - Add or remove tag to focused window. -*client_movemouse*:: - Move client window with mouse. -*client_resizemouse*:: - Resize client window with mouse. -*client_setscratch*:: - Set or unset client as being the scratch window. -*client_togglescratch*:: - Toggle scratch window. -*client_toggletitlebar*:: - Toggle window titlebar. - -Tag -~~~ -*tag_setlayout* relative or absolute integer:: - Set layout number; or just switch to the next layout for current tag. -*tag_toggleview* tag:: - Add windows tagged with tag number to current display. -*tag_view* tag number:: - View windows tagged with tag number. -*tag_viewnext*:: - Show windows tagged with next tag in list. -*tag_viewprev*:: - Show windows tagged with previous tag in list. -*tag_prev_selected*:: - Switch back to the previously displayed set of tags. -*tag_setmwfact* relative or absolute float:: - Set master width factor. -*tag_setncol* relative or absolute integer:: - Set number of columns for non-master windows. -*tag_setnmaster* relative or absolute integer:: - Set number of master windows. -*tag_create* name:: - Create a new tag with that name. - -Focus -~~~~~ -*focus_client_byname* string:: - Give client focus by its name. -*focus_history* negative number:: - Focus the client that had focused nth focus switch earlier. - -Screen -~~~~~~ -*screen_focus* relative or absolute integer:: - Select Screen and focus first window and move mouse. +include::uicbdocgen.txt[] WIDGETS ------- diff --git a/build-utils/extractdoc.py b/build-utils/extractdoc.py new file mode 100755 index 00000000..2fbf0b1f --- /dev/null +++ b/build-utils/extractdoc.py @@ -0,0 +1,70 @@ +#!/usr/bin/python +# +# extractdoc.py - extract uicb documentation from awesome sour code +# Copyright ® 2008 Julien Danjou +# +# This indeed crappy. Any better version, even with awk, would be welcome. +# + +import sys +import os.path + +def extract_doc(file): + function_doc = {} + doc = [] + doc_begin = False + catch_name = 0 + + for line in file.readlines(): + if catch_name == 1: + catch_name = 2 + continue + if catch_name > 1: + # We only want functions with uicb + if line.startswith("uicb_"): + if line.endswith("arg __attribute__ ((unused)))\n"): + doc.append("No argument needed.") + uicb_name = line.split('_', 1)[1] + uicb_name = uicb_name.split('(', 1)[0] + function_doc[uicb_name] = doc + catch_name = False + else: + catch_name = 0 + doc = [] + if line.startswith("/**"): + doc_begin = True + doc.append(line[4:].replace("\n", "")) + if doc_begin and line.startswith(" * ") and not line.startswith(" * \\"): + doc.append(line[3:].replace("\n", "")) + if line.startswith(" */"): + doc_begin = False + catch_name = 1 + + return function_doc + +def doc_print(function_doc, filename): + if not len(function_doc): + return + filename = os.path.basename(filename) + # Special case + if filename == "uicb.c": + filename = "general.c" + # Print header + tmptitle = filename.replace(".c", "") + title = tmptitle[0].upper() + tmptitle[1:] + print title + i = 0 + underline = "" + while i < len(title): + underline += "~" + i += 1 + print underline + # Print documentation + for uicb, doc in function_doc.items(): + # Special case + print "*%s*::" % uicb + print " %s" % " ".join(doc) + print + +for f in sys.argv[1:]: + doc_print(extract_doc(file(f)), f) diff --git a/build-utils/uicbgen.sh b/build-utils/uicbgen.sh index 2905961d..4710768d 100755 --- a/build-utils/uicbgen.sh +++ b/build-utils/uicbgen.sh @@ -11,8 +11,6 @@ do do shortname=$(echo $uicb | cut -d _ -f2-) echo " {\"$shortname\", $uicb}," - grep -q "\*$shortname\*" ${top_srcdir}/awesomerc.5.txt || \ - echo " WARNING: $uicb NOT documented" >&2 done done diff --git a/client.c b/client.c index 107e2ea5..02ae3c80 100644 --- a/client.c +++ b/client.c @@ -848,8 +848,7 @@ client_find_visible(Client *sel, Bool reverse) * \ingroup ui_callback */ void -uicb_client_swapprev(int screen __attribute__ ((unused)), - char *arg __attribute__ ((unused))) +uicb_client_swapprev(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused))) { Client *prev; @@ -866,8 +865,7 @@ uicb_client_swapprev(int screen __attribute__ ((unused)), * \ingroup ui_callback */ void -uicb_client_swapnext(int screen __attribute__ ((unused)), - char *arg __attribute__ ((unused))) +uicb_client_swapnext(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused))) { Client *next; @@ -1128,8 +1126,7 @@ uicb_client_focusprev(int screen, char *arg __attribute__ ((unused))) * \ingroup ui_callback */ void -uicb_client_togglefloating(int screen __attribute__ ((unused)), - char *arg __attribute__ ((unused))) +uicb_client_togglefloating(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused))) { if(globalconf.focus->client) client_setfloating(globalconf.focus->client, !globalconf.focus->client->isfloating); @@ -1141,8 +1138,7 @@ uicb_client_togglefloating(int screen __attribute__ ((unused)), * \ingroup ui_callback */ void -uicb_client_setscratch(int screen, - char *arg __attribute__ ((unused))) +uicb_client_setscratch(int screen, char *arg __attribute__ ((unused))) { if(!globalconf.focus->client) return; @@ -1162,8 +1158,7 @@ uicb_client_setscratch(int screen, * \ingroup ui_callback */ void -uicb_client_togglescratch(int screen, - char *arg __attribute__ ((unused))) +uicb_client_togglescratch(int screen, char *arg __attribute__ ((unused))) { if(globalconf.scratch.client) { diff --git a/titlebar.c b/titlebar.c index 3733c2e0..04ad0730 100644 --- a/titlebar.c +++ b/titlebar.c @@ -449,8 +449,7 @@ titlebar_update_geometry(Client *c, area_t geometry) * \ingroup ui_callback */ void -uicb_client_toggletitlebar(int screen __attribute__ ((unused)), - char *arg __attribute__ ((unused))) +uicb_client_toggletitlebar(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused))) { Client *c = globalconf.focus->client; diff --git a/uicb.c b/uicb.c index 65664d27..0467fa9f 100644 --- a/uicb.c +++ b/uicb.c @@ -47,15 +47,14 @@ extern AwesomeConf globalconf; #include "uicbgen.h" /** Restart awesome with the current command line - * \param screen ID (unused) + * \param screen ID * \param arg arg (unused) * \ingroup ui_callback */ void -uicb_restart(int screen __attribute__ ((unused)), - char *arg __attribute__ ((unused))) +uicb_restart(int screen, char *arg __attribute__ ((unused))) { - uicb_exec(0, globalconf.argv); + uicb_exec(screen, globalconf.argv); } /** Execute another process, replacing the current instance of Awesome