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>
This commit is contained in:
Ignas Anikevicius (gns_ank) 2014-05-26 20:26:52 +01:00 committed by Daniel Hahler
parent 6ab86b5d03
commit b96b3ef31c
23 changed files with 137 additions and 118 deletions

62
AUTHORS
View File

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

View File

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

View File

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

64
docs/00-authors.md Normal file
View File

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

View File

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

View File

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

View File

@ -1,6 +1,7 @@
--- awesome core API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module awesome
--- awesome global table.

View File

@ -1,6 +1,7 @@
--- awesome button API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @classmod button
--- Button object.

View File

@ -1,6 +1,7 @@
--- awesome client API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @classmod client
--- Client object.

View File

@ -1,6 +1,7 @@
--- awesome D-Bus API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module dbus
--- Register a D-Bus name to receive message from.

View File

@ -1,6 +1,7 @@
--- awesome drawable API
-- @author Uli Schlachter &lt;psychon@znc.in&gt;
-- @copyright 2012 Uli Schlachter
-- @release @AWESOME_VERSION@
-- @classmod drawable
--- Drawable object.

View File

@ -1,6 +1,7 @@
--- awesome drawin API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @classmod drawin
--- Drawin object.

View File

@ -1,6 +1,7 @@
--- awesome key API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @classmod key
--- Key object.

View File

@ -1,6 +1,7 @@
--- awesome keygrabber API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module keygrabber
---

View File

@ -1,6 +1,7 @@
--- awesome mouse API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module mouse
--- Mouse library.

View File

@ -1,6 +1,7 @@
--- awesome mousegrabber API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module mousegrabber
--- Grab the mouse pointer and list motions, calling callback function at each

View File

@ -1,6 +1,7 @@
--- awesome root window API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module root
--- Get or set global mouse bindings.

View File

@ -1,6 +1,7 @@
--- awesome screen API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module screen
--- Screen is a table where indexes are screen number. You can use screen[1]

View File

@ -1,6 +1,7 @@
--- awesome selection (clipboard) API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module selection
--- Get the selection (clipboard) content.

View File

@ -1,6 +1,7 @@
--- awesome tag API
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @classmod tag
--- Tag object.

View File

@ -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/'
}
}

View File

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

View File

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