diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2018-04-16 17:09:58 +0200 |
---|---|---|
committer | Sven Eden <yamakuzure@gmx.net> | 2018-08-24 16:47:08 +0200 |
commit | d1dbf40d47cfa883c4c9fa264dfd84cd57a03b85 (patch) | |
tree | 639f9de5fd06cf9648241a9b8109c9bd37f58cbf | |
parent | 708eb0d64b2cf111713bdaa9f74c20b7eaa515eb (diff) |
man: add a new page with a general description of common syntax
We have a common parser, but for the user it might be
completely unobvious that the same general rules apply
to all those files. Let's add a page about the basic syntax
so that the more specific pages don't have to repeat those
details.
-rw-r--r-- | man/elogind.syntax.xml | 107 | ||||
-rw-r--r-- | man/logind.conf.xml | 8 | ||||
-rw-r--r-- | man/rules/meson.build | 3 |
3 files changed, 113 insertions, 5 deletions
diff --git a/man/elogind.syntax.xml b/man/elogind.syntax.xml new file mode 100644 index 000000000..a6fc8bab6 --- /dev/null +++ b/man/elogind.syntax.xml @@ -0,0 +1,107 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="elogind.syntax"> + + <refentryinfo> + <title>elogind.syntax</title> + <productname>elogind</productname> + + <authorgroup> + <author> + <contrib>A. U. Thor</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>elogind.syntax</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>elogind.syntax</refname> + <refpurpose>General syntax of elogind configuration files</refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + + <para>This page describes the basic principles of configuration files used by + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and related programs for: + <itemizedlist> + <listitem><para>elogind unit files, see + <citerefentry><refentrytitle>elogind.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></para></listitem> + + <listitem><para>daemon config files, see + <citerefentry><refentrytitle>elogind-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-user.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para></listitem> + </itemizedlist> + </para> + + <para>The syntax is inspired by + <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG Desktop Entry Specification</ulink> + <filename>.desktop</filename> files, which are in turn inspired by Microsoft Windows + <filename>.ini</filename> files. + </para> + + <para>Each file is a plain text file divided into sections, with configuration entries in the + style <replaceable>key</replaceable>=<replaceable>value</replaceable>. + Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored, which may be used for commenting.</para> + + <para>Lines ending in a backslash are concatenated with the following line while reading and the + backslash is replaced by a space character. This may be used to wrap long lines. The limit on + line length is very large (currently 1 MB), but it is recommended to avoid such long lines and + use multiple directives, variable substitution, or other mechanism as appropriate for the given + file type.</para> + + <example><programlisting>[Section A] +KeyOne=value 1 +KeyTwo=value 2 + +# a comment + +[Section B] +Setting="something" "some thing" "…" +KeyTwo=value 2 \ + value 2 continued +</programlisting></example> + + <para>Various settings are allowed to be specified more than once, in which case the + interpretation depends on the setting. Often, multiple settings form a list, and setting to an + empty value "resets", which means that previous assignments are ignored. When this is allowed, + it is mentioned in the description of the setting. Note that using multiple assignments to the + same value makes the file incompatible with parsers for the XDG <filename>.desktop</filename> + file format.</para> + </refsect1> + +</refentry> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 4a9cc563a..82789cdcb 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -61,11 +61,11 @@ <refsect1> <title>Description</title> - <para>These files configure various parameters of the elogind <!-- 0 /// elogind does not need a service file. - login manager, - <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> + <para>These files configure various parameters of the systemd login manager, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. See + <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a general description of the syntax.</para> --><!-- else --> login manager.</para> <!-- // 0 --> diff --git a/man/rules/meson.build b/man/rules/meson.build index ce3a6c546..1adf73560 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -630,9 +630,9 @@ manpages = [ ['elogind-sysctl.service', '8', ['elogind-sysctl'], ''], ['elogind-system-update-generator', '8', [], ''], ['elogind-system.conf', - '8', 'elogind-sleep', 'elogind-suspend-then-hibernate.service'], + '8', ''], '5', ['system.conf.d', 'elogind-user.conf', 'user.conf.d'], @@ -703,6 +703,7 @@ manpages = [ ['elogind.time', '7', [], ''], ['elogind.timer', '5', [], ''], ['elogind.unit', '5', [], ''], + ['elogind.syntax', '7', [], ''], ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'], ['telinit', '8', [], ''], ['timedatectl', '1', [], 'ENABLE_TIMEDATED'], |