Some documentation issues

[anihm136]

Output of awesome --version:

awesome v4.3-1216-g5f29d6d0 (Too long) • Compiled against Lua 5.3.6 (running with Lua 5.3) • API level: 4 • D-Bus support: yes • xcb-errors support: yes • execinfo support: yes • xcb-randr version: 1.6 • LGI version: 0.9.2 • Transparency enabled: yes • Custom search paths: no

How to reproduce the issue: Certain items were a little confusing in the documentation (mainly pertaining to notifications), and I'd like to list them here in case there is scope for improving the documentation for these

1. I did not see anywhere in the docs that certain tables in naughty.config cannot be set directly, only the attributes of those tables can be set (the no_clear table). This required some digging in the code to figure out
2. When moving from the legacy notification handler to the new one, some things tripped me up regarding how the widget template interacts with the config options set in naughty.config. For example, earlier setting naughty.config.defaults.width would ensure that notifications have a certain width, but now since the default strategy for the wibox.container.constraints is 'max', it behaves differently. Similarly, setting naughty.config.defaults.shape does not work directly, since the widget box will still be a rectangle. Thus, the shape of the widget box also needs to be set accordingly

(might add a few more as I face/recall)

In general, I'm a little confused as to what the recommended way of configuring these options is, since there are multiple ways of doing it (setting naughty.config, setting theme variables, modifying the widget template in request::display etc)

For reference, I'm attaching the relevant part of my configs. Do let me know if I'm making any obvious mistakes and making things complex unnecessarily.

local naughty = require('naughty')
local beautiful = require('beautiful')
local gears = require('gears')
local wibox = require('wibox')
local awful = require('awful')
local dpi = beautiful.xresources.apply_dpi
local utils = require('utils') -- Custom version of menubar.utils

-- ===================================================================
-- Theme Definitions
-- ===================================================================

-- These are no-clear settings: cannot set the entire table at once
local defaults = {
	ontop = true,
	icon_size = dpi(24),
	timeout = 5,
	title = 'Notification',
	margin = dpi(10),
	position = 'top_right',
	width = dpi(500),
	border_width = 0,
	max_height = dpi(150),
	shape = function(cr, w, h)
		gears.shape.rounded_rect(cr, w, h, dpi(10))
	end,
}
for k, v in pairs(defaults) do
	naughty.config.defaults[k] = v
end

local presets = {
	normal = {
		font = beautiful.title_font,
		fg = beautiful.fg_normal,
		bg = beautiful.bg_normal,
	},
	low = {
		font = beautiful.title_font,
		fg = beautiful.fg_normal,
		bg = beautiful.bg_normal,
		-- fg = '#ffffff',
		-- bg = '#ff0000',
		timeout = 2,
	},
	critical = {
		font = beautiful.title_font,
		fg = '#ffffff',
		bg = '#ff0000',
	},
}

for preset, settings in pairs(presets) do
	for k, v in pairs(settings) do
		naughty.config.presets[preset][k] = v
	end
end

naughty.config.padding = dpi(30)
naughty.config.spacing = dpi(30)
naughty.config.icon_dirs =
	{
		'/usr/share/icons/Sardi/scalable/actions/',
		'/usr/share/icons/Sardi/scalable/animations/',
		'/usr/share/icons/Sardi/scalable/apps/',
		'/usr/share/icons/Sardi/scalable/categories/',
		'/usr/share/icons/Sardi/scalable/devices/',
		'/usr/share/icons/Sardi/scalable/emblems/',
		'/usr/share/icons/Sardi/scalable/mimetypes/',
		'/usr/share/icons/Sardi/scalable/notifications/',
		'/usr/share/icons/Sardi/scalable/panel/',
		'/usr/share/icons/Sardi/scalable/places/',
		'/usr/share/icons/Sardi/scalable/status/',
	}

naughty.config.notify_callback = function(args)
	if args.actions ~= nil and #args.actions > 0 then
		args.timeout = 0.0
		args.ignore_suspend = true
	end
	return args
end

naughty.connect_signal('request::display', function(notif, _, args)
	args.screen = awful.screen.focused()
	local bound_strategy
	if args.width or args.height or (args.preset and args.preset.width) or (args.preset and args.preset.height) then
		bound_strategy = 'max'
	else
		bound_strategy = 'exact'
	end
	naughty.layout.box{
		notification = notif,
		widget_template = {
			{
				{
					{
						{
							naughty.widget.icon,
							{
								naughty.widget.title,
								naughty.widget.message,
								spacing = 4,
								layout = wibox.layout.fixed.vertical,
							},
							fill_space = true,
							spacing = 4,
							layout = wibox.layout.fixed.horizontal,
						},
						naughty.list.actions,
						spacing = 10,
						layout = wibox.layout.fixed.vertical,
					},
					widget = wibox.container.margin,
					margins = defaults.margin
				},
				id = 'background_role',
				widget = naughty.container.background,
			},
			strategy = (args.width or (args.preset and args.preset.width)) and 'max' or 'exact',
			widget = wibox.container.constraint,
		},
		shape = defaults.shape,
	}
end)

naughty.connect_signal('request::icon', function(notif, context, hints)
	if context ~= 'app_icon' then return end

	local path =
		utils.lookup_icon(
			hints.app_icon,
			naughty.config.icon_dirs
		) or utils.lookup_icon(hints.app_icon:lower(), naughty.config.icon_dirs)

	if path then
		notif.icon = path
	end
end)
naughty.connect_signal('request::action_icon', function(action, _, hints)
	local path =
		utils.lookup_icon(
			hints.app_icon,
			naughty.config.icon_dirs
		) or utils.lookup_icon(hints.app_icon:lower(), naughty.config.icon_dirs)
	if path then
		action.icon = path
	end
end)

-- ===================================================================
-- Error Handling
-- ===================================================================

if awesome.startup_errors then
	naughty.notification({
		preset = naughty.config.presets.critical,
		title = 'Oops, there were errors during startup!',
		text = awesome.startup_errors,
	})
end

do
	local in_error = false
	awesome.connect_signal('debug::error', function(err)
		if in_error then return end
		in_error = true

		naughty.notification({
			preset = naughty.config.presets.critical,
			title = 'Oops, an error happened!',
			text = tostring(err),
		})
		in_error = false
	end)
end