diff --git a/CMakeLists.txt b/CMakeLists.txt index 4e6a93c7..275e8e03 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -277,6 +277,7 @@ if(GENERATE_DOC) COMMAND ${LDOC_EXECUTABLE} . 3>&1 1>&2 2>&3 | awk "{ fail=1 \; print } END { exit fail }" WORKING_DIRECTORY ${AWE_DOC_DIR} DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/06-appearance.md + ${BUILD_DIR}/docs/05-awesomerc.md ) endif() diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index c17362e4..19286506 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -329,7 +329,6 @@ set(AWESOME_CONFIGURE_FILES ${awesome_lua_configure_files} config.h docs/config.ld - awesomerc.lua awesome-version-internal.h) foreach(file ${AWESOME_CONFIGURE_FILES}) @@ -347,6 +346,15 @@ add_custom_command( ${BUILD_DIR}/docs/06-appearance.md ) +add_custom_command( + OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md + COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua + ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua + ${BUILD_DIR}/awesomerc.lua +) + +#}}} + # {{{ Copy additional files file(GLOB awesome_md_docs RELATIVE ${SOURCE_DIR} ${SOURCE_DIR}/docs/*.md) diff --git a/awesomerc.lua b/awesomerc.lua index 7edb2827..287a916d 100755 --- a/awesomerc.lua +++ b/awesomerc.lua @@ -1,3 +1,4 @@ +-- @DOC_REQUIRE_SECTION@ -- Standard awesome library local gears = require("gears") local awful = require("awful") @@ -12,6 +13,7 @@ local menubar = require("menubar") local hotkeys_popup = require("awful.hotkeys_popup").widget -- {{{ Error handling +-- @DOC_ERROR_HANDLING@ -- Check if awesome encountered an error during startup and fell back to -- another config (This code will only ever execute for the fallback config) if awesome.startup_errors then @@ -37,9 +39,11 @@ end -- }}} -- {{{ Variable definitions +-- @DOC_LOAD_THEME@ -- Themes define colours, icons, font and wallpapers. beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua") +-- @DOC_DEFAULT_APPLICATIONS@ -- This is used later as the default terminal and editor to run. terminal = "xterm" editor = os.getenv("EDITOR") or "nano" @@ -52,6 +56,7 @@ editor_cmd = terminal .. " -e " .. editor -- However, you can use another modifier like Mod1, but it may interact with others. modkey = "Mod4" +-- @DOC_LAYOUT@ -- Table of layouts to cover with awful.layout.inc, order matters. awful.layout.layouts = { awful.layout.suit.floating, @@ -89,6 +94,7 @@ end -- }}} -- {{{ Menu +-- @DOC_MENU@ -- Create a launcher widget and a main menu myawesomemenu = { { "hotkeys", function() return false, hotkeys_popup.show_help end}, @@ -113,7 +119,7 @@ menubar.utils.terminal = terminal -- Set the terminal for applications that requ -- Keyboard map indicator and switcher mykeyboardlayout = awful.widget.keyboardlayout() --- {{{ Wibox +-- {{{ Wibar -- Create a textclock widget mytextclock = wibox.widget.textclock() @@ -122,6 +128,7 @@ mywibox = {} mypromptbox = {} mylayoutbox = {} mytaglist = {} +-- @TAGLIST_BUTTON@ mytaglist.buttons = awful.util.table.join( awful.button({ }, 1, function(t) t:view_only() end), awful.button({ modkey }, 1, function(t) @@ -140,6 +147,7 @@ mytaglist.buttons = awful.util.table.join( ) mytasklist = {} +-- @TASKLIST_BUTTON@ mytasklist.buttons = awful.util.table.join( awful.button({ }, 1, function (c) if c == client.focus then @@ -165,7 +173,9 @@ mytasklist.buttons = awful.util.table.join( awful.client.focus.byidx(-1) end)) +-- @DOC_WALLPAPER@ local function set_wallpaper(s) + -- Wallpaper if beautiful.wallpaper then local wallpaper = beautiful.wallpaper -- If wallpaper is a function, call it with the screen @@ -179,6 +189,7 @@ end -- Re-set wallpaper when a screen's geometry changes (e.g. different resolution) screen.connect_signal("property::geometry", set_wallpaper) +-- @DOC_FOR_EACH_SCREEN@ awful.screen.connect_for_each_screen(function(s) -- Wallpaper set_wallpaper(s) @@ -202,9 +213,11 @@ awful.screen.connect_for_each_screen(function(s) -- Create a tasklist widget mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons) + -- @DOC_WIBAR@ -- Create the wibox mywibox[s] = awful.wibar({ position = "top", screen = s }) + -- @DOC_SETUP_WIDGETS@ -- Add widgets to the wibox mywibox[s]:setup { layout = wibox.layout.align.horizontal, @@ -227,6 +240,7 @@ end) -- }}} -- {{{ Mouse bindings +-- @DOC_ROOT_BUTTONS@ root.buttons(awful.util.table.join( awful.button({ }, 3, function () mymainmenu:toggle() end), awful.button({ }, 4, awful.tag.viewnext), @@ -235,6 +249,7 @@ root.buttons(awful.util.table.join( -- }}} -- {{{ Key bindings +-- @DOC_GLOBAL_KEYBINDINGS@ globalkeys = awful.util.table.join( awful.key({ modkey, }, "s", hotkeys_popup.show_help, {description="show help", group="awesome"}), @@ -333,6 +348,7 @@ globalkeys = awful.util.table.join( {description = "show the menubar", group = "launcher"}) ) +-- @DOC_CLIENT_KEYBINDINGS@ clientkeys = awful.util.table.join( awful.key({ modkey, }, "f", function (c) @@ -365,6 +381,7 @@ clientkeys = awful.util.table.join( {description = "maximize", group = "client"}) ) +-- @DOC_NUMBER_KEYBINDINGS@ -- Bind all key numbers to tags. -- Be careful: we use keycodes to make it works on any keyboard layout. -- This should map on the top row of your keyboard, usually 1 to 9. @@ -415,6 +432,7 @@ for i = 1, 9 do ) end +-- @DOC_CLIENT_BUTTONS@ clientbuttons = awful.util.table.join( awful.button({ }, 1, function (c) client.focus = c; c:raise() end), awful.button({ modkey }, 1, awful.mouse.client.move), @@ -426,7 +444,9 @@ root.keys(globalkeys) -- {{{ Rules -- Rules to apply to new clients (through the "manage" signal). +-- @DOC_RULES@ awful.rules.rules = { + -- @DOC_GLOBAL_RULE@ -- All clients will match this rule. { rule = { }, properties = { border_width = beautiful.border_width, @@ -440,6 +460,7 @@ awful.rules.rules = { } }, + -- @DOC_FLOATING_RULE@ -- Floating clients. { rule_any = { instance = { @@ -466,6 +487,7 @@ awful.rules.rules = { } }, properties = { floating = true }}, + -- @DOC_DIALOG_RULE@ -- Add titlebars to normal clients and dialogs { rule_any = {type = { "normal", "dialog" } }, properties = { titlebars_enabled = true } @@ -479,6 +501,7 @@ awful.rules.rules = { -- {{{ Signals -- Signal function to execute when a new client appears. +-- @DOC_MANAGE_HOOK@ client.connect_signal("manage", function (c) -- Set the windows at the slave, -- i.e. put it at the end of others instead of setting it master. @@ -492,6 +515,7 @@ client.connect_signal("manage", function (c) end end) +-- @DOC_TITLEBARS@ -- Add a titlebar if titlebars_enabled is set to true in the rules. client.connect_signal("request::titlebars", function(c) -- buttons for the titlebar @@ -542,6 +566,7 @@ client.connect_signal("mouse::enter", function(c) end end) +-- @DOC_BORDER@ client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end) client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end) -- }}} diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua new file mode 100644 index 00000000..9e41f88b --- /dev/null +++ b/docs/05-awesomerc.md.lua @@ -0,0 +1,241 @@ +local filename, rcfile, new_rcfile = ... + +local f = io.open(filename, "w") + +f:write[[# Default configuration file documentation + +This document explain the default `rc.lua` file provided by Awesome. + +]] + +-- Document sections of the file to guide new users to the right doc pages + +local sections = {} + +sections.DOC_REQUIRE_SECTION = [[ +Awesome API is distributed across many libraries (also called modules). + +Here is the modules being imported: + + + + + + + + +
`gears`Utilities such as color parsing and objects
`wibox`Awesome own generic widget framework
`awful`Everything related to window managment
`naughty`Notifications
`menubar`XDG (application) menu implementation
`beautiful`Awesome theme module
+ +]] + +sections.DOC_ERROR_HANDLING = [[ +Awesome is a window managing framework. It allows its users great (ultimate?) +flexibility. However, it also allows the user to write invalid code. There is +multiple "levels" of problems: + + * Syntax: There is an `awesome -k` option available in the command line to + check this. Awesome cannot start with an invalid `rc.lua` + * Invalid APIs and type errors: Lua is a dynamic language. It doesn't have much + support for static/compile time checks. There is the `luacheck` utility to + help find some categories of errors. Those errors will cause Awesome to + "drop" the current call stack and start over. Note that if the config cannot + reach the end of the `rc.lua` without errors, it will fallback to the + original file. + * Invalid logic: It is possible to write fully valid code that will leave + Awesome unusable (like an infinite loop or blocking commands). In that case, + the best way to debug this is either using `print()` or using `gdb`. For + this, see the [Debugging tips Readme section](../documentation/01-readme.md.html) + * Deprecated APIs: Awesome API is not frozen for eternity. While after a + decade and recent changes to enforce consistency, it doesn't change as much, + it will likely be changed in the future. When possible, changes wont cause + errors but will instead print a deprecation message in Awesome logs. Those + logs are placed in various places depending on the distribution. By default, + Awesome will print this on stderr and stdout. + + +]] + + +sections.DOC_LOAD_THEME = [[ +To create custom themes, the easiest way is to copy the `default` theme folder +from `/usr/share/awesome/themes/` into `~/.config/awesome` and modify it. + +Awesome currently doesn't behave well without a theme containing all the "basic" +variables such as `bg_normal`. To get a list of all official variables, see +the [appearance guide](../documentation/06-appearance.md.html). +]] + + +sections.DOC_DEFAULT_APPLICATIONS = [[ +   +]] + + +sections.DOC_LAYOUT = [[ +   +]] + + +sections.DOC_MENU = [[ +   +]] + + +sections.TAGLIST_BUTTON = [[ +   +]] + + +sections.TASKLIST_BUTTON = [[ +   +]] + + +sections.DOC_FOR_EACH_SCREEN = [[ +   +]] + + +sections.DOC_WIBAR = [[ +   +]] + + +sections.DOC_SETUP_WIDGETS = [[ +   +]] + + +sections.DOC_ROOT_BUTTONS = [[ +   +]] + + +sections.DOC_GLOBAL_KEYBINDINGS = [[ +   +]] + + +sections.DOC_CLIENT_KEYBINDINGS = [[ +   +]] + + +sections.DOC_NUMBER_KEYBINDINGS = [[ +   +]] + + +sections.DOC_CLIENT_BUTTONS = [[ +   +]] + + +sections.DOC_RULES = [[ +   +]] + + +sections.DOC_GLOBAL_RULE = [[ +   +]] + + +sections.DOC_FLOATING_RULE = [[ +   +]] + + +sections.DOC_DIALOG_RULE = [[ +   +]] + + +sections.DOC_MANAGE_HOOK = [[ +   +]] + + +sections.DOC_TITLEBARS = [[ +   +]] + + +sections.DOC_BORDER = [[ +   +]] + +-- Ask ldoc to generate links + +local function add_links(line) + for _, module in ipairs { + "awful", "wibox", "gears", "naughty", "menubar", "beautiful" + } do + if line:match(module.."%.") then + line = line:gsub("("..module.."[.a-zA-Z]+)", "`%1`") + end + end + + return " "..line.."\n" +end + +-- Parse the default awesomerc.lua + +local rc = io.open(rcfile) + +local doc_block = false + +local output = {} + +for line in rc:lines() do + local tag = line:match("@([^@]+)@") + + if not tag then + local section = line:match("--[ ]*{{{[ ]*(.*)") + if line == "-- }}}" or line == "-- {{{" then + -- Hide some noise + elseif section then + -- Turn Vim sections into markdown sections + if doc_block then + f:write("\n") + doc_block = false + end + f:write("## "..section.."\n") + elseif line:sub(1,2) == "--" then + -- Display "top level" comments are normal text. + if doc_block then + f:write("\n") + doc_block = false + end + f:write(line:sub(3).."\n") + else + -- Write the code in sections + if not doc_block then + f:write("\n") + doc_block = true + end + f:write(add_links(line)) + end + table.insert(output, line) + else + -- Take the documentation found in this file and append it + if doc_block then + f:write("\n") + doc_block = false + end + + if sections[tag] then + f:write(sections[tag]) + else + f:write(" \n\n") + end + end +end + +f:write("\n") + +f:close() + +local rc_lua = io.open(new_rcfile, "w") +rc_lua:write(table.concat(output, "\n")) +rc_lua:close() diff --git a/docs/config.ld b/docs/config.ld index 939b74de..72505c8b 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -21,6 +21,7 @@ topics={ '02-contributing.md', '03-declarative-layout.md', '04-new-widgets.md', + '05-awesomerc.md', '06-appearance.md', '16-using-cairo.md', '90-FAQ.md',