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.

diff --git a/man/elogind.syntax.xml b/man/elogind.syntax.xml
new file mode 100644 (file)
index 0000000..a6fc8ba
--- /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 4a9cc563a297d621c5c29aaf99e38a3ab2061d65..82789cdcb4a63db846aa747dff8f4b09e184a8be 100644 (file)
--- 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 ce3a6c5466f967b48a0d6cd5c256f6bae19e7fda..1adf7356001531f0127677a883fc17e7b3e23791 100644 (file)
--- 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'],