[PATCH] Weston: weston.ini man page

Tue Oct 9 00:19:49 PDT 2012

On Mon, 8 Oct 2012 20:32:56 +0200
Martin Minarik <minarik11 at student.fiit.stuba.sk> wrote:

> The man page is not very detailed and exceptionally accurate, but
> it mentions the configuration options.
> ---

Hi Martin,

cool, comments below.

>  man/weston.ini.5 |  184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 184 insertions(+), 0 deletions(-)
>  create mode 100644 man/weston.ini.5
> 
> diff --git a/man/weston.ini.5 b/man/weston.ini.5
> new file mode 100644
> index 0000000..2b121de
> --- /dev/null
> +++ b/man/weston.ini.5
> @@ -0,0 +1,184 @@
> +.\" shorthand for double quote that works everywhere.
> +.ds q \N'34'
> +.TH weston.ini 5 "weston 0.95.0" "Wayland "
> +.SH NAME
> +weston.ini \- configuration file for
> +.B Weston
> +the reference Wayland compositor
> +.SH INTRODUCTION
> +.B Weston
> +obtains configuration from its command line parameters and the configuration
> +file described here.
> +.SH DESCRIPTION
> +.B Weston
> +uses a configuration file called
> +.I weston.ini
> +for its setup.
> +The
> +.I weston.ini
> +configuration file is searched for in the following places when the
> +server is started:
> +.PP
> +.RS 4
> +.nf
> +.IR $HOME/.config/weston.ini
> +.IR $XDG_CONFIG_HOME/weston.ini

This is a bit subtle. If you look on shared/config-parser.c, it goes
like this:
- if XDG_CONFIG_HOME is set, use $XDG_CONFIG_HOME/weston.ini
- otherwise, if HOME is set, use $HOME/.config/weston.ini
- otherwise, use weston.ini from cwd.

And this does not fall back to the next choice, if the file is not
found. I'm not sure if that is desired, but it is how it currently
works.

> +.fi
> +.RE
> +.PP
> +where enviroment variable
> +.B $HOME
> +is the user's home directory, and
> +.B $XDG_CONFIG_HOME
> +is the user specific configuration directory.
> +.PP
> +The
> +.I weston.ini
> +file is composed of a number of sections which may be present in any order,
> +or omitted to use default configuration values.
> +Each section has the form:
> +.PP
> +.RS 4
> +.nf
> +.BI [ SectionHeader ]
> +.RI "    " Option1=Value1
> +.RI "    " Option2=Value2

Indentation (leading spaces) in the config file is not allowed, AFAICS.

> +    ...
> +.fi
> +.RE
> +.PP
> +Comment lines are ignored:
> +.PP
> +.RS 4
> +.nf
> +.IR "#comment"
> +.fi
> +.RE
> +.PP
> +The section headers are:
> +.PP
> +.RS 4
> +.nf
> +.BR "shell          " "Desktop customisation"
> +.BR "launcher       " "Add launcher to the panel"
> +.BR "screensaver    " "Screensaver selection"
> +.BR "output         " "Monitors setup"

There are also sections: core, keyboard, terminal
As we have no examples of these, they are especially good to document,
with whatever keys they have.

> +.fi
> +.RE
> +.PP
> +Values are: string, integer and boolean.

Integers types have signed and unsigned, too, and they are 32-bit both.

> +.SH "SHELL SECTION"
> +The
> +.B shell
> +section is used to customise the compositor.
> +.PP
> +The entries that can appear in this section are:
> +.TP 7
> +.BI "type=" desktop-shell.so 
> +sets the file name of the desired desktop shell plugin.

Just "shell plugin" as it can be something else than a desktop shell
variant.

> The desktop shell
> +provides the basic user enviroment consisting of one or several predefined
> +screens. Available shells in the

What are predefined screens? I don't understand the sentence.

> +.IR /lib/weston/

This directory should be pulled from ./configure, just like
man/weston.man pulls __weston_modules_dir__ with the sed script. For
that you need to add a substitution in man/Makefile.am.

The sed script is also the reason why git has weston.man and the build
makes a weston.1 from it.

> +directory are:
> +.PP
> +.RS 11
> +.nf
> +.IR desktop-shell.so
> +.fi
> +.IR tablet-shell.so

This list depends on ./configure options, but it can be left for now.

> +.RE
> +.RE
> +.TP 7
> +.BI "background-image=" file
> +sets the path for the background image file. 
> +.TP 7
> +.BI "background-color=" 0xAARRGGBB
> +sets the color of the background. The hexadecimal
> +digit pairs are in order alpha, red, green, and blue.
> +.TP 7
> +.BI "panel-color=" 0xAARRGGBB
> +sets the color of the panel. The hexadecimal
> +digit pairs are in order alpha, red, green, and blue. The panel can be
> +transparent.
> +.TP 7
> +.BI "locking=" true
> +enables screen locking.
> +.TP 7
> +.BI "animation=" zoom
> +sets the effect used for switching workspaces

Other values for this key?

> +.TP 7
> +.BI "binding-modifier=" ctrl
> +Blabalbalba

Eh? :-)

> +.TP 7
> +.BI "num-workspaces=" 6
> +defines the number of workspaces. The user can switch workspaces by using the
> +Super+W shortcut. If this option 

...?

> +.TP 7
> +.BI "lockscreen-icon=" path
> +sets the path to lock screen icon image.
> +.TP 7
> +.BI "lockscreen=" path
> +sets the path to lock screen background image.
> +.TP 7
> +.BI "homescreen=" path
> +sets the path to home screen background image.
> +.RE
> +.SH "LAUNCHER SECTION"
> +.TP 7
> +.BI "icon=" icon
> +sets the path to icon image. 
> +.TP 7
> +.BI "path=" program
> +sets the path to program that is run by clicking on this launcher.

I think all the above should be sub-categorized between desktop-shell
and tablet-shell. Some options are used only by one of them.

> +.SH "SCREENSAVER SECTION"
> +The
> +.B screensaver
> +section is used to select and schedule a screensaver.
> +The
> +.B screensaver
> +section is optional, as are all of the entries that may be specified in
> +it.
> +.TP 7
> +.BI "path=" /usr/libexec/weston-screensaver
> +This instructs the compositor to use the selected screensaver client on
> +a given path. If
> +this line is missing or commented out, the screensaver in
> +.B weston
> +is disabled.
> +.RE
> +.TP 7
> +.BI "duration=" 600
> +The idle time in seconds until the screensaver appears.

Actually that is the idle time after which the screensaver disappears
to save power. The appearing time is the idle timeout for weston, set
with the -i command line switch.

> +.SH "OUTPUT SECTION"
> +There can be multiple output sections, one for each computer screen.
> +.TP 7
> +.BI "name=" /usr/libexec/weston-screensaver
> +sets a name for the screen. Can be arbitrary string.
> +.RE
> +.TP 7
> +.BI "mode=" 
> +173.00  1920 2048 2248 2576  1080 1083 1088 1120 -hsync +vsync
> +sets the resolution and the configuration of the monitor. In case of a LCD
> +screen, the resolution e.g. 800x600 may be enough. Users of CRT displays are
> +encouraged to provide a modeline string. This string consists of the refresh
> +rate in Hz, horisontal and vertical resolution, options to disable/enable
> +horisontal and vertical synchronisation. 
> +.RE
> +.TP 7
> +.BI "transform=" flipped
> +The transformation applied to screen output. It is done by shaders.
> +.SH "KEYBOARD SECTION"
> +Each
> +.B [keyboard]
> +has it's own keyboard layout. The keyboard layouts are provided by the 
> +libxkbcommon library. This section contains the following option: 
> +.TP 7
> +.BI "keymap_layout=" en
> +sets the keyboard layout code. The keymap codes are same ones as used
> +in the Xorg server.

There are also keymap_rules, _model, _variant, _options.

> +.SH "SEE ALSO"
> +.BR weston (1),
> +.BR weston-launch (1)
> +.SH AUTHORS
> +Wayland community - -
> +.IR <xx at xxx.xx> .

If there's nothing better for AUTHORS, we can leave it out, or at
least not put the fake email address.

Thanks,
pq