Docs: Move all docs to a `docs` folder.

This moves all of the documentation into a separate folder, which keeps
everything in one place and avoids unnecessary clutter.

This will pay off when proper guides are written for various aspects of
using awesome or contributing to it.

This also updates the building system, so that the docs are properly
generated with new directories.

Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>

AUTHORS

@@ -1,62 +0,0 @@
-
-    awesome - awesome window manager
-
-Author:
-
-    © 2007-2009 Julien Danjou <julien@danjou.info>
-
-Contributors:
-
-    © 2007-2009 Nikos Ntarmos <ntarmos@ceid.upatras.gr>
-    © 2007-2009 Arnaud Fontaine <arnau@debian.org>
-    © 2008-2009 Damien Leone <damien.leone@gmail.com>
-    © 2008-2009 Gregor Best <farhaven@googlemail.com>
-    © 2008-2009 Maarten Maathuis <madman2003@gmail.com>
-    © 2008-2009 koniu <gkusnierz@gmail.com>
-    © 2009 Uli Schlachter <psychon@znc.in>
-
-Past contributors:
-
-    © 2007-2008 Marco Candrian <mac@calmar.ws>
-    © 2008 Lucas de Vries <lucasdevries@gmail.com>
-    © 2008 Pierre Habouzit <madcoder@debian.org>
-    © 2008 Félix C. Morency <felix.morency@gmail.com>
-    © 2008 Michael Gehring <mg@ebfe.org>
-    © 2008 Hans Ulrich Niedermann <hun@n-dimensional.de>
-    © 2007 Aldo Cortesi <aldo@nullcube.com>
-
-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 <garbeam at gmail dot com>
-    © 2006-2007 Sander van Dijk <a dot h dot vandijk at gmail dot com>
-    © 2006-2007 Jukka Salmi <jukka at salmi dot ch>
-    © 2007 Premysl Hruby <dfenze at gmail dot com>
-    © 2007 Szabolcs Nagy <nszabolcs at gmail dot com>
-
-    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.

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
+    ${AWE_DOC_DIR}/00-authors.md
-    ${SOURCE_DIR}/BUGS
+    ${AWE_DOC_DIR}/01-readme.md
-    ${SOURCE_DIR}/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}
+        WORKING_DIRECTORY ${AWE_DOC_DIR}
-        DEPENDS ${AWE_LUA_FILES})
+        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

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

docs/00-authors.md

@@ -0,0 +1,64 @@
+# Authors
+
+
+## awesome - awesome window manager
+
+**Author**:
+
+ * © 2007-2009 Julien Danjou <julien@danjou.info>
+
+**Contributors**:
+
+ * © 2007-2009 Nikos Ntarmos <ntarmos@ceid.upatras.gr>
+ * © 2007-2009 Arnaud Fontaine <arnau@debian.org>
+ * © 2008-2009 Damien Leone <damien.leone@gmail.com>
+ * © 2008-2009 Gregor Best <farhaven@googlemail.com>
+ * © 2008-2009 Maarten Maathuis <madman2003@gmail.com>
+ * © 2008-2009 koniu <gkusnierz@gmail.com>
+ * © 2009 Uli Schlachter <psychon@znc.in>
+
+**Past contributors**:
+
+ * © 2007-2008 Marco Candrian <mac@calmar.ws>
+ * © 2008 Lucas de Vries <lucasdevries@gmail.com>
+ * © 2008 Pierre Habouzit <madcoder@debian.org>
+ * © 2008 Félix C. Morency <felix.morency@gmail.com>
+ * © 2008 Michael Gehring <mg@ebfe.org>
+ * © 2008 Hans Ulrich Niedermann <hun@n-dimensional.de>
+ * © 2007 Aldo Cortesi <aldo@nullcube.com>
+
+## 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 <garbeam at gmail dot com>
+ * © 2006-2007 Sander van Dijk <a dot h dot vandijk at gmail dot com>
+ * © 2006-2007 Jukka Salmi <jukka at salmi dot ch>
+ * © 2007 Premysl Hruby <dfenze at gmail dot com>
+ * © 2007 Szabolcs Nagy <nszabolcs at gmail dot com>
+
+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.

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)).

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;

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.

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.

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.

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.

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.

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.

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.

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
 
 ---

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.

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

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.

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]

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.

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.

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'
+format='discount'
-dir='doc'
+dir='../doc'
 
 -- Make the docs prettier
 pretty='lua'
@@ -14,8 +14,9 @@ style="!pale"
 backtick_references=true
 merge=true
 topics={
-    'README.md',
+    '00-authors.md',
-    'CONTRIBUTING.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/',
+    'capi/',
-    'lib/',
+    '../lib/',
     exclude = {
         -- exclude these modules, as they do not contain any written
         -- documentation
-        'lib/awful/autofocus.lua',
+        '../lib/awful/autofocus.lua',
-        'lib/awful/dbus.lua',
+        '../lib/awful/dbus.lua',
-        'lib/awful/ewmh.lua',
+        '../lib/awful/ewmh.lua',
-        'lib/awful/remote.lua',
+        '../lib/awful/remote.lua',
-        'lib/awful/startup_notification.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/'
     }
 }
 

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

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