diff --git a/AUTHORS b/AUTHORS deleted file mode 100644 index 9e594f76..00000000 --- a/AUTHORS +++ /dev/null @@ -1,62 +0,0 @@ - - awesome - awesome window manager - -Author: - - © 2007-2009 Julien Danjou - -Contributors: - - © 2007-2009 Nikos Ntarmos - © 2007-2009 Arnaud Fontaine - © 2008-2009 Damien Leone - © 2008-2009 Gregor Best - © 2008-2009 Maarten Maathuis - © 2008-2009 koniu - © 2009 Uli Schlachter - -Past contributors: - - © 2007-2008 Marco Candrian - © 2008 Lucas de Vries - © 2008 Pierre Habouzit - © 2008 Félix C. Morency - © 2008 Michael Gehring - © 2008 Hans Ulrich Niedermann - © 2007 Aldo Cortesi - -License: - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Originally based on dwm code: - - MIT/X Consortium License - - © 2006-2007 Anselm R. Garbe - © 2006-2007 Sander van Dijk - © 2006-2007 Jukka Salmi - © 2007 Premysl Hruby - © 2007 Szabolcs Nagy - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. diff --git a/CMakeLists.txt b/CMakeLists.txt index e97361f9..3609687a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -27,10 +27,12 @@ set(AWE_CONF_FILE rc.lua) set(AWE_ICON_DIR ${SOURCE_DIR}/icons) set(AWE_THEMES_DIR ${SOURCE_DIR}/themes) +set(AWE_DOC_DIR ${BUILD_DIR}/docs) + set(AWE_DOC_FILES - ${SOURCE_DIR}/AUTHORS - ${SOURCE_DIR}/BUGS - ${SOURCE_DIR}/README.md + ${AWE_DOC_DIR}/00-authors.md + ${AWE_DOC_DIR}/01-readme.md + ${AWE_DOC_DIR}/02-contributing.md ${SOURCE_DIR}/LICENSE) set(AWE_SRCS @@ -237,12 +239,13 @@ if(GENERATE_DOC) file(MAKE_DIRECTORY ${BUILD_DIR}/lib) endif() - file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua ${BUILD_DIR}/luadoc/*.lua) + file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua ${AWE_DOC_DIR}/capi/*.lua) + file(GLOB_RECURSE AWE_MD_FILES ${AWE_DOC_DIR}/*.md) add_custom_target(ldoc ALL COMMAND ${LDOC_EXECUTABLE} . - WORKING_DIRECTORY ${BUILD_DIR} - DEPENDS ${AWE_LUA_FILES}) + WORKING_DIRECTORY ${AWE_DOC_DIR} + DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES}) endif() # }}} @@ -335,4 +338,4 @@ if(BUSTED_EXECUTABLE) endif() # }}} -# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 +# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index 79a856d7..c4763496 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -272,11 +272,16 @@ set(AWESOME_THEMES_PATH ${AWESOME_DATA_PATH}/themes) # }}} # {{{ Configure files -file(GLOB_RECURSE awesome_lua_configure_files RELATIVE ${SOURCE_DIR} ${SOURCE_DIR}/lib/*.lua.in ${SOURCE_DIR}/themes/*/*.lua.in) +file(GLOB_RECURSE awesome_lua_configure_files RELATIVE + ${SOURCE_DIR} + ${SOURCE_DIR}/lib/*.lua.in + ${SOURCE_DIR}/docs/capi/*.lua.in + ${SOURCE_DIR}/docs/*.md + ${SOURCE_DIR}/themes/*/*.lua.in) set(AWESOME_CONFIGURE_FILES ${awesome_lua_configure_files} config.h.in - config.ld.in + docs/config.ld.in awesomerc.lua.in awesome-version-internal.h.in awesome.doxygen.in) @@ -295,4 +300,4 @@ foreach(file ${AWESOME_CONFIGURE_FILES}) endforeach() #}}} -# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 +# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/docs/00-authors.md b/docs/00-authors.md new file mode 100644 index 00000000..2f2bf158 --- /dev/null +++ b/docs/00-authors.md @@ -0,0 +1,64 @@ +# Authors + + +## awesome - awesome window manager + +**Author**: + + * © 2007-2009 Julien Danjou + +**Contributors**: + + * © 2007-2009 Nikos Ntarmos + * © 2007-2009 Arnaud Fontaine + * © 2008-2009 Damien Leone + * © 2008-2009 Gregor Best + * © 2008-2009 Maarten Maathuis + * © 2008-2009 koniu + * © 2009 Uli Schlachter + +**Past contributors**: + + * © 2007-2008 Marco Candrian + * © 2008 Lucas de Vries + * © 2008 Pierre Habouzit + * © 2008 Félix C. Morency + * © 2008 Michael Gehring + * © 2008 Hans Ulrich Niedermann + * © 2007 Aldo Cortesi + +## License: + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +## Originally based on dwm code: + +MIT/X Consortium License + + * © 2006-2007 Anselm R. Garbe + * © 2006-2007 Sander van Dijk + * © 2006-2007 Jukka Salmi + * © 2007 Premysl Hruby + * © 2007 Szabolcs Nagy + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. diff --git a/README.md b/docs/01-readme.md similarity index 77% rename from README.md rename to docs/01-readme.md index 5a7503c5..243444f1 100644 --- a/README.md +++ b/docs/01-readme.md @@ -1,10 +1,8 @@ -awesome -======= +# awesome awesome is a highly configurable, next generation framework window manager for X. -Building and installation -------------------------- +## Building and installation After extracting the dist tarball, run: @@ -16,8 +14,7 @@ After building is finished, you can install: make install # you might need root permissions -Running awesome ---------------- +## Running awesome You can directly select awesome from your display manager. If not, you can add the following line to your .xinitrc to start awesome using startx @@ -32,16 +29,14 @@ the `DISPLAY` environment variable is set correctly, e.g.: (This will start awesome on display `:1` of the host foo.bar.) -Configuration -------------- +## Configuration The configuration of awesome is done by creating a `$XDG_CONFIG_HOME/awesome/rc.lua` file. An example configuration named `awesomerc.lua.in` is provided in the source. -Troubleshooting ---------------- +## Troubleshooting In most systems any message printed by awesome (including warnings and errors) are written to `$HOME/.xsession-errors`. @@ -50,8 +45,14 @@ If awesome does not start or the configuration file is not producing the desired results the user should examine this file to gain insight into the problem. -Reporting issues ----------------- +## Reporting issues + Please report any issues you may find on [our bugtracker](https://github.com/awesomeWM/awesome/issues). You can submit pull requests on the [github repository](https://github.com/awesomeWM/awesome). -Please read the @{CONTRIBUTING.md} guide for any coding, documentation or patch guidelines. +Please read the @{02-contributing.md} guide for any coding, documentation or patch guidelines. + +## License + +The project is licensed under GNU General Publice License v2 or later. +You can read it online at ([v2](http://www.gnu.org/licenses/gpl-2.0.html) +or [v3](http://www.gnu.org/licenses/gpl.html)). diff --git a/CONTRIBUTING.md b/docs/02-contributing.md similarity index 97% rename from CONTRIBUTING.md rename to docs/02-contributing.md index 9948f717..2e9b88fb 100644 --- a/CONTRIBUTING.md +++ b/docs/02-contributing.md @@ -1,10 +1,11 @@ -Bugs -=== +# Contrubuting + + +## Bugs Please look at http://awesome.naquadah.org/bugs/ -Style -=== +## Style If you intend to patch and contribute to awesome, please respect the following guidelines. @@ -39,13 +40,11 @@ Imitate the existing code style. For concrete rules: A vim modeline is set in each file to respect this. -Patches -=== +## Patches If you plan to submit patches, you should follow the following guidelines. -Commits ---- +### Commits - make commits of logical units; - do not modify piece of code not related to your commit; @@ -61,8 +60,7 @@ Commits commit message (or just use the option `-s` when commiting); - make sure that you have tests for the bug you are fixing. -Patches ---- +### Patches - use `git format-patch -M` to create the patch; - do *not* PGP sign your patch; diff --git a/luadoc/awesome.lua b/docs/capi/awesome.lua.in similarity index 98% rename from luadoc/awesome.lua rename to docs/capi/awesome.lua.in index 0aae3fd9..2b27b2b4 100644 --- a/luadoc/awesome.lua +++ b/docs/capi/awesome.lua.in @@ -1,6 +1,7 @@ --- awesome core API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module awesome --- awesome global table. diff --git a/luadoc/button.lua b/docs/capi/button.lua.in similarity index 96% rename from luadoc/button.lua rename to docs/capi/button.lua.in index 4f2a7563..2d6b7985 100644 --- a/luadoc/button.lua +++ b/docs/capi/button.lua.in @@ -1,6 +1,7 @@ --- awesome button API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @classmod button --- Button object. diff --git a/luadoc/client.lua b/docs/capi/client.lua.in similarity index 99% rename from luadoc/client.lua rename to docs/capi/client.lua.in index 0de0ff34..4464425d 100644 --- a/luadoc/client.lua +++ b/docs/capi/client.lua.in @@ -1,6 +1,7 @@ --- awesome client API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @classmod client --- Client object. diff --git a/luadoc/dbus.lua b/docs/capi/dbus.lua.in similarity index 98% rename from luadoc/dbus.lua rename to docs/capi/dbus.lua.in index 5f4bcb02..a55f43b0 100644 --- a/luadoc/dbus.lua +++ b/docs/capi/dbus.lua.in @@ -1,6 +1,7 @@ --- awesome D-Bus API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module dbus --- Register a D-Bus name to receive message from. diff --git a/luadoc/drawable.lua b/docs/capi/drawable.lua.in similarity index 97% rename from luadoc/drawable.lua rename to docs/capi/drawable.lua.in index 39fd28ca..5737522f 100644 --- a/luadoc/drawable.lua +++ b/docs/capi/drawable.lua.in @@ -1,6 +1,7 @@ --- awesome drawable API -- @author Uli Schlachter <psychon@znc.in> -- @copyright 2012 Uli Schlachter +-- @release @AWESOME_VERSION@ -- @classmod drawable --- Drawable object. diff --git a/luadoc/drawin.lua b/docs/capi/drawin.lua.in similarity index 98% rename from luadoc/drawin.lua rename to docs/capi/drawin.lua.in index 2303f2d0..0a7d2f66 100644 --- a/luadoc/drawin.lua +++ b/docs/capi/drawin.lua.in @@ -1,6 +1,7 @@ --- awesome drawin API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @classmod drawin --- Drawin object. diff --git a/luadoc/key.lua b/docs/capi/key.lua.in similarity index 97% rename from luadoc/key.lua rename to docs/capi/key.lua.in index d7945995..f340c9e0 100644 --- a/luadoc/key.lua +++ b/docs/capi/key.lua.in @@ -1,6 +1,7 @@ --- awesome key API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @classmod key --- Key object. diff --git a/luadoc/keygrabber.lua b/docs/capi/keygrabber.lua.in similarity index 97% rename from luadoc/keygrabber.lua rename to docs/capi/keygrabber.lua.in index d4edd3c7..321ee46c 100644 --- a/luadoc/keygrabber.lua +++ b/docs/capi/keygrabber.lua.in @@ -1,6 +1,7 @@ --- awesome keygrabber API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module keygrabber --- diff --git a/luadoc/mouse.lua b/docs/capi/mouse.lua.in similarity index 96% rename from luadoc/mouse.lua rename to docs/capi/mouse.lua.in index a467db93..cc8aef9f 100644 --- a/luadoc/mouse.lua +++ b/docs/capi/mouse.lua.in @@ -1,6 +1,7 @@ --- awesome mouse API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module mouse --- Mouse library. diff --git a/luadoc/mousegrabber.lua b/docs/capi/mousegrabber.lua.in similarity index 96% rename from luadoc/mousegrabber.lua rename to docs/capi/mousegrabber.lua.in index 02ac9de5..54a2586f 100644 --- a/luadoc/mousegrabber.lua +++ b/docs/capi/mousegrabber.lua.in @@ -1,6 +1,7 @@ --- awesome mousegrabber API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module mousegrabber --- Grab the mouse pointer and list motions, calling callback function at each diff --git a/luadoc/root.lua b/docs/capi/root.lua.in similarity index 98% rename from luadoc/root.lua rename to docs/capi/root.lua.in index dd667d00..1f5f0095 100644 --- a/luadoc/root.lua +++ b/docs/capi/root.lua.in @@ -1,6 +1,7 @@ --- awesome root window API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module root --- Get or set global mouse bindings. diff --git a/luadoc/screen.lua b/docs/capi/screen.lua.in similarity index 97% rename from luadoc/screen.lua rename to docs/capi/screen.lua.in index a2c40fb4..a52303f9 100644 --- a/luadoc/screen.lua +++ b/docs/capi/screen.lua.in @@ -1,6 +1,7 @@ --- awesome screen API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module screen --- Screen is a table where indexes are screen number. You can use screen[1] diff --git a/luadoc/selection.lua b/docs/capi/selection.lua.in similarity index 90% rename from luadoc/selection.lua rename to docs/capi/selection.lua.in index 636b61a1..c5f13b7a 100644 --- a/luadoc/selection.lua +++ b/docs/capi/selection.lua.in @@ -1,6 +1,7 @@ --- awesome selection (clipboard) API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @module selection --- Get the selection (clipboard) content. diff --git a/luadoc/tag.lua b/docs/capi/tag.lua.in similarity index 97% rename from luadoc/tag.lua rename to docs/capi/tag.lua.in index d0144565..15840ecd 100644 --- a/luadoc/tag.lua +++ b/docs/capi/tag.lua.in @@ -1,6 +1,7 @@ --- awesome tag API -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou +-- @release @AWESOME_VERSION@ -- @classmod tag --- Tag object. diff --git a/config.ld.in b/docs/config.ld.in similarity index 68% rename from config.ld.in rename to docs/config.ld.in index aba802a0..810a3cbb 100644 --- a/config.ld.in +++ b/docs/config.ld.in @@ -5,8 +5,8 @@ title='awesome API documentation' description='highly configurable X window manager' -- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support -format='markdown' -dir='doc' +format='discount' +dir='../doc' -- Make the docs prettier pretty='lua' @@ -14,8 +14,9 @@ style="!pale" backtick_references=true merge=true topics={ - 'README.md', - 'CONTRIBUTING.md', + '00-authors.md', + '01-readme.md', + '02-contributing.md', } -- Setup @client to be an alias for "@tparam client.client" @@ -24,25 +25,24 @@ tparam_alias('tag', 'tag') -- Should be default, but is not. Sets up "@tab" => "@tparam table". tparam_alias('tab', 'table') --- file={ 'lib/', '@SOURCE_DIR@/luadoc' } file = { -- LUA libraries - 'luadoc/', - 'lib/', + 'capi/', + '../lib/', exclude = { -- exclude these modules, as they do not contain any written -- documentation - 'lib/awful/autofocus.lua', - 'lib/awful/dbus.lua', - 'lib/awful/ewmh.lua', - 'lib/awful/remote.lua', - 'lib/awful/startup_notification.lua', + '../lib/awful/autofocus.lua', + '../lib/awful/dbus.lua', + '../lib/awful/ewmh.lua', + '../lib/awful/remote.lua', + '../lib/awful/startup_notification.lua', -- Ignore some parts of the widget library - 'lib/awful/widget/common.lua', + '../lib/awful/widget/common.lua', -- exclude layout, but we need an extra bit of documentation elsewhere. - 'lib/awful/layout/suit/' + '../lib/awful/layout/suit/' } } diff --git a/lib/beautiful.lua.in b/lib/beautiful.lua.in index 736de485..b7609012 100644 --- a/lib/beautiful.lua.in +++ b/lib/beautiful.lua.in @@ -35,10 +35,9 @@ local descs = setmetatable({}, { __mode = 'k' }) local fonts = setmetatable({}, { __mode = 'v' }) local active_font ---- Load a font name +-- Load a font name -- -- @param Font name, which can be a string or a table --- @local here local function load_font(name) name = name or active_font if name and type(name) ~= "string" and descs[name] then @@ -65,10 +64,9 @@ local function load_font(name) return font end ---- Set an active font +-- Set an active font -- -- @param name The font --- @local here local function set_font(name) active_font = load_font(name).name end diff --git a/lib/naughty/core.lua.in b/lib/naughty/core.lua.in index e846e7ed..d22eae78 100644 --- a/lib/naughty/core.lua.in +++ b/lib/naughty/core.lua.in @@ -167,7 +167,7 @@ function naughty.toggle() end end ---- Evaluate desired position of the notification by index - internal +-- Evaluate desired position of the notification by index - internal -- -- @param idx Index of the notification -- @param position top_right | top_left | bottom_right | bottom_left @@ -175,7 +175,6 @@ end -- @param height Popup height -- @param width Popup width (optional) -- @return Absolute position and index in { x = X, y = Y, idx = I } table --- @local here local function get_offset(screen, position, idx, width, height) local ws = capi.screen[screen].workarea local v = {} @@ -215,10 +214,9 @@ local function get_offset(screen, position, idx, width, height) return v end ---- Re-arrange notifications according to their position and index - internal +-- Re-arrange notifications according to their position and index - internal -- -- @return None --- @local here local function arrange(screen) for p,pos in pairs(naughty.notifications[screen]) do for i,notification in pairs(naughty.notifications[screen][p]) do @@ -258,7 +256,7 @@ function naughty.destroy(notification, reason) end end ---- Get notification by ID +-- Get notification by ID -- -- @param id ID of the notification -- @return notification object if it was found, nil otherwise