[PATCH v3] Weston: weston.ini man page
Scott Moreau
oreaus at gmail.com
Sat Jan 12 03:58:40 PST 2013
Hi Martin,
Thanks for working on this. A few comments below.
On Fri, Jan 11, 2013 at 9:40 PM, Martin Minarik <
minarik11 at student.fiit.stuba.sk> wrote:
> Track changes in weston.ini format: core, input-method sections.
> animation: make zoom, fade bold.
> More examples for keymap layous.
> Example for term=xterm-256color
> ---
> man/weston.ini.5 | 268
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 268 insertions(+)
> 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..a580242
> --- /dev/null
> +++ b/man/weston.ini.5
> @@ -0,0 +1,268 @@
> +.\" shorthand for double quote that works everywhere.
> +.ds q \N'34'
> +.TH weston.ini 5 "weston 0.95.0" "Wayland "
>
Shouldn't the version here reflect latest weston?
> +.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 one of the following places when the
> +server is started:
> +.PP
> +.RS 4
> +.nf
> +.BR "$XDG_CONFIG_HOME/weston.ini " "(if $XDG_CONFIG_HOME is set)"
> +.BR "$HOME/.config/weston.ini " "(if $HOME is set)"
> +.BR "<current dir>/weston.ini " "(if both variables were not set)"
> +.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
>
A minor nitpick, can we use Key instead of Option?
> + ...
> +.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"
>
I am curious if there is a preferred spelled for words such as customize
and optimizations. The discrepancy here is 's' vs 'z'.
> +.BR "launcher " "Add launcher to the panel"
> +.BR "screensaver " "Screensaver selection"
> +.BR "output " "Monitors setup"
>
The output device is not necessarily a monitor. For example with x11
backend, the outputs are x11 windows. Perhaps "Monitors setup" can become
"Output configuration"
> +.BR "keyboard " "Keyboard layouts"
> +.BR "terminal " "Terminal application options"
> +.fi
> +.RE
> +.PP
> +Values are: string, integer (signed or unsigned) and boolean.
> +.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 shell plugin. The shell user inteface
> plugin
> +provides the basic user enviroment displayed when the compositor starts.
> +Available shells in the
> +.IR /lib/weston/
> +directory are:
> +.PP
> +.RS 11
> +.nf
> +.IR desktop-shell.so
> +.fi
> +.IR tablet-shell.so
> +.TP 7
> +.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 opacity, red, green, and blue. Examples:
> +.PP
> +.RS 10
> +.nf
> +.BR "0xffff0000 " "Red"
> +.BR "0xff00ff00 " "Green"
> +.BR "0xff0000ff " "Blue"
> +.BR "0x00ffffff " "Fully opaque"
>
Wouldn't this be fully transparent? Opaque means neither translucent nor
transparent.
> +.fi
> +.RE
> +.TP 7
> +.BI "locking=" true
> +enables screen locking.
> +.TP 7
> +.BI "animation=" zoom
> +sets the effect used for switching workspaces. Can be either zoom or fade
>
Doesn't this set the surface (open) animation? I don't think workspace
switching animation is configurable.
> +.TP 7
> +.BI "binding-modifier=" ctrl
> +sets the compositor binding modifier hot key. This key is used for moving,
> +resizing, rotating, switching, closing and setting the opacity for
> windows,
> +controlling the backlight and zooming the desktop. Users running under
> Unity
> +desktop may want to use something else than the default.
This mod key is the main modifier used for many common bindings. Having the
word "Unity" in the man page feels wrong. I don't think we need to mention
any specific names here.
> Possible values:
> +ctrl, alt, super (default)
> +.TP 7
> +.BI "num-workspaces=" 6
> +defines the number of workspaces. The user can switch workspaces by using
> the
> +binding+F1, F2 keys. If this option is not set, fall back to one
> workspace.
> +.TP 7
> +.BI "lockscreen-icon=" path
> +sets the path to lock screen icon image. (tablet shell only)
> +.TP 7
> +.BI "lockscreen=" path
> +sets the path to lock screen background image. (tablet shell only)
> +.TP 7
> +.BI "homescreen=" path
> +sets the path to home screen background image. (tablet shell only)
> +.RE
> +.SH "LAUNCHER SECTION"
> +.TP 7
> +.BI "icon=" icon
> +sets the path to icon image. Svg images are not supported.
>
This statement makes it sound like svg will never be supported. Perhaps
"Svg images are not currently supported." would make it clear that svg is
not strictly prohibited.
> +.TP 7
> +.BI "path=" program
> +sets the path to the program that is run by clicking on this launcher.
> +.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 disappears in order to
> save power.
> +.SH "OUTPUT SECTION"
> +There can be multiple output sections, one for each computer screen.
> +.TP 7
> +.BI "name=" name
> +sets a name for the screen. A backend recognizes these names and uses the
> whole
> +screen section for its screen.
This does not convey the correct information. The output section is
currently only recognized by the x11 and drm backends. The name key is used
to identify an output. There is no screen concept or screen section at all.
> Examples of usage:
> +.PP
> +.RS 10
> +.nf
> +.BR "LVDS1 " "LVDS mode, DRM backend"
> +.BR "VGA1 " "VGA mode, DRM backend"
> +.BR "X1 " "X11 backend (running weston on X server)"
>
We need to make it clear that the name key is parsed differently by drm and
x11 backend. For drm, the name key must be an output name listed in the
output of weston-launch (drm backend). For x11, the name key must start
with an 'X'.
> +.fi
> +.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. Consists of the
> +refresh rate in Hz, horizontal and vertical resolution, options to for
> +horizontal and vertical synchronisation. The program
> +.B cvt
> +can provide suitable modeline string. Alternative formats:
> +.PP
> +.RS 10
> +.nf
> +.BR "WIDTHxHEIGHT " "Resolution size width and height in pixels"
> +.BR "preferred " "Uses the preferred mode"
> +.BR "current " "Uses the current crt controller mode"
> +.BR "off " "Disables the output"
>
Same with the mode here. We need to convey that fact that it's parsed
differently by drm and x11 backends, respectively. For drm backend, the
mode must be a mode already listed by the output of weston-launch (drm
backend) or, one of the other valid textual key values. For x11 backend,
raw modelines are not accepted and the width/height can be any values.
> +.fi
> +.RE
> +.TP 7
> +.BI "transform=" normal
> +The transformation applied to screen output. The transform key can be one
> of
> +the following 8 strings:
> +.PP
> +.RS 10
> +.nf
> +.BR "normal " "Normal output."
> +.BR "90 " "90 degrees clockwise."
> +.BR "180 " "Upside down."
> +.BR "270 " "90 degrees counter clockwise."
> +.BR "flipped " "Horizontally flipped"
> +.BR "flipped-90 " "Flipped and 90 degrees clockwise"
> +.BR "flipped-180 " "Flipped upside down"
> +.BR "flipped-270 " "Flipped and 90 degrees counter clockwise"
> +.fi
> +.RE
> +.SH "KEYBOARD SECTION"
> +This section contains the following options:
> +.TP 7
> +.BI "keymap_rules=" "evdev"
> +sets the keymap rules file. Used to map layout and model to input device.
> +.RE
> +.RE
> +.TP 7
> +.BI "keymap_model=" "pc105"
> +sets the keymap model. See the Models section in
> +.B "xkeyboard-config(7)."
> +.RE
> +.RE
> +.TP 7
> +.BI "keymap_layout=" "us,de,gb"
> +sets the comma separated list of keyboard layout codes. See the Layouts
> section
> +in
> +.B "xkeyboard-config(7)."
> +.RE
> +.RE
> +.TP 7
> +.BI "keymap_variant=" "euro,,intl"
> +sets the comma separated list of keyboard layout variants. The number of
> variants
> +is be the same as the number of layouts above. See the Layouts section in
> +.B "xkeyboard-config(7)."
> +.RE
> +.RE
> +.TP 7
> +.BI "keymap_options=" "grp:alt_shift_toggle,grp_led:scroll"
> +sets the keymap options. See the Options section in
> +.B "xkeyboard-config(7)."
> +.RE
> +.RE
> +.SH "TERMINAL SECTION"
> +Contains settings for the weston terminal application (weston-terminal).
> It
> +allows to customize the font and shell of the command line interface.
> +.TP 7
> +.BI "font=" "DejaVu Sans Mono"
> +sets the font of the terminal. For a good experience it is recommend to
> use
> +monospace fonts. In case the font is not found, the default one is used.
> +.RE
> +.RE
> +.TP 7
> +.BI "font-size=" "14"
> +sets the size of the terminal font.
> +.RE
> +.RE
> +.TP 7
> +.BI "term=" "term"
> +The terminal shell. Sets the $TERM variable.
> +.RE
> +.RE
> +.SH "SEE ALSO"
> +.BR weston (1),
> +.BR weston-launch (1)
> +.BR xkeyboard-config (7)
> --
> 1.7.10.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Thanks,
Scott
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130112/78e0c5df/attachment.html>
More information about the wayland-devel
mailing list