[PATCH] Weston: weston.ini.man page

Wed Jan 16 13:47:17 PST 2013

Updates since last patch:

 - The weston.ini.5 is now generated from weston.ini.man by automake
 - 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
 - Use key= instead of option=
 - Fix US english
 - Call it output instead of monitor
 - Transparent instead opaque
 - Window open animation
 - modifier key
 - output section, name, mode key
   - explain that they are processed differently by backends
---
 man/Makefile.am    |    9 +-
 man/weston.ini.man |  310 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 316 insertions(+), 3 deletions(-)
 create mode 100644 man/weston.ini.man

diff --git a/man/Makefile.am b/man/Makefile.am
index 71d2073..32ad9ec 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,14 +1,17 @@
-man_MANS = weston.1
+man_MANS = weston.1 weston.ini.5
 
 MAN_SUBSTS = \
 	-e 's|__weston_modules_dir__|$(pkglibdir)|g' \
 	-e 's|__version__|$(PACKAGE_VERSION)|g'
 
-SUFFIXES = .1 .man
+SUFFIXES = .1 .man .5
 
 .man.1:
 	$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
 
-EXTRA_DIST = weston.man
+.man.5:
+	$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
+
+EXTRA_DIST = weston.man weston.ini.man
 
 CLEANFILES = $(man_MANS)
diff --git a/man/weston.ini.man b/man/weston.ini.man
new file mode 100644
index 0000000..0d826c4
--- /dev/null
+++ b/man/weston.ini.man
@@ -0,0 +1,310 @@
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH weston.ini 5 "2013-01-16" "Weston __version__"
+.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 environment 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 Key1=Value1
+.RI Key2=Value2
+    ...
+.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 "core           " "The core modules"
+.BR "shell          " "Desktop customization"
+.BR "launcher       " "Add launcher to the panel"
+.BR "screensaver    " "Screensaver selection"
+.BR "output         " "Output configuration"
+.BR "input-method   " "Onscreen keyboard input"
+.BR "keyboard       " "Keyboard layouts"
+.BR "terminal       " "Terminal application options"
+.fi
+.RE
+.PP
+Values are: string, integer (signed or unsigned) and boolean.
+.RE
+.SH "CORE SECTION"
+The
+.B core
+section is used to select the startup compositor modules.
+.TP 7
+.BI "modules=" desktop-shell.so,xwayland.so
+specifies the modules to load. Available modules in the
+.IR /lib/weston/
+directory are:
+.PP
+.RS 10
+.nf
+.BR desktop-shell.so
+.BR tablet-shell.so
+.BR xwayland.so
+.fi
+.RE
+.SH "SHELL SECTION"
+The
+.B shell
+section is used to customize 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 interface plugin
+provides the basic user environment displayed when the compositor starts.
+Available shells in the
+.IR "__weston_modules_dir__"
+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 transparency, red, green, and blue. Examples:
+.PP
+.RS 10
+.nf
+.BR "0xffff0000    " "Red"
+.BR "0xff00ff00    " "Green"
+.BR "0xff0000ff    " "Blue"
+.BR "0x00ffffff    " "Fully transparent"
+.fi
+.RE
+.TP 7
+.BI "locking=" true
+enables screen locking.
+.TP 7
+.BI "animation=" zoom
+sets the effect used for opening new windows. Can be either
+.B zoom
+or
+.B fade.
+.TP 7
+.BI "binding-modifier=" ctrl
+sets the modifier key used for common bindings, such as moving surfaces,
+resizing, rotating, switching, closing and setting the transparency for windows,
+controlling the backlight and zooming the desktop. 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 key 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 currently supported.
+.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(1)"
+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, each corresponding to one output. It is
+currently only recognized by the drm and x11 backends.
+.TP 7
+.BI "name=" name
+sets a name for the output. The backend uses the name to identify the output.
+All X11 output names start with a letter X. The available output names for DRM
+backend are listed in the
+.B "weston-launch(1)"
+log.
+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)"
+.fi
+.RE
+.TP 7
+.BI "mode=" mode
+the mode parameter is handled differently depending on the backend. On the X11
+backend, it just sets the WIDTHxHEIGHT of the weston window.
+The DRM backend accepts different modes:
+.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"
+.fi
+.RE
+.RS
+.PP
+Optionally, an user may specify a modeline, such as:
+.PP
+173.00  1920 2048 2248 2576  1080 1083 1088 1120 -hsync +vsync
+.PP
+It consists of the refresh rate in Hz, horizontal and vertical resolution,
+options for horizontal and vertical synchronisation. The program
+.B "cvt(1)"
+can provide suitable modeline string.
+.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 "INPUT-METHOD SECTION"
+.TP 7
+.BI "path=" "/usr/libexec/weston-keyboard"
+sets the path of the on screen keyboard input method.
+.RE
+.RE
+.SH "KEYBOARD SECTION"
+This section contains the following keys:
+.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=" "xterm-256color"
+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

