[systemd-devel] [PATCH 11/12] Add man page and references to it.
Zbigniew Jędrzejewski-Szmek
zbyszek at in.waw.pl
Wed Jan 28 07:06:50 PST 2015
On Wed, Jan 28, 2015 at 02:24:55PM +0100, Didier Roche wrote:
>
> From 6b13d8fb248bf4176f1ad7e1d4736683462bf196 Mon Sep 17 00:00:00 2001
> From: Didier Roche <didrocks at ubuntu.com>
> Date: Mon, 26 Jan 2015 17:34:59 +0100
> Subject: [PATCH 11/12] Add man page and references to it.
>
> Add man page explaining the plymouth theme protocol, usage of the daemon
> as well as the socket activation part.
> Adapt existing fsck man page.
> ---
> Makefile-man.am | 12 +++
> man/systemd-fsck at .service.xml | 6 +-
> man/systemd-fsckd.service.xml | 170 +++++++++++++++++++++++++++++++++++++++++
> units/systemd-fsckd.service.in | 1 +
> units/systemd-fsckd.socket | 2 +-
> 5 files changed, 188 insertions(+), 3 deletions(-)
> create mode 100644 man/systemd-fsckd.service.xml
>
> diff --git a/Makefile-man.am b/Makefile-man.am
> index 105853e..f2e13e8 100644
> --- a/Makefile-man.am
> +++ b/Makefile-man.am
> @@ -67,6 +67,7 @@ MANPAGES += \
> man/systemd-escape.1 \
> man/systemd-firstboot.1 \
> man/systemd-fsck at .service.8 \
> + man/systemd-fsckd.service.8 \
> man/systemd-fstab-generator.8 \
> man/systemd-getty-generator.8 \
> man/systemd-gpt-auto-generator.8 \
> @@ -210,6 +211,8 @@ MANPAGES_ALIAS += \
> man/systemd-firstboot.service.1 \
> man/systemd-fsck-root.service.8 \
> man/systemd-fsck.8 \
> + man/systemd-fsckd.8 \
> + man/systemd-fsckd.socket.8 \
> man/systemd-hibernate-resume.8 \
> man/systemd-hibernate.service.8 \
> man/systemd-hybrid-sleep.service.8 \
> @@ -323,6 +326,8 @@ man/systemd-ask-password-wall.service.8: man/systemd-ask-password-console.servic
> man/systemd-firstboot.service.1: man/systemd-firstboot.1
> man/systemd-fsck-root.service.8: man/systemd-fsck at .service.8
> man/systemd-fsck.8: man/systemd-fsck at .service.8
> +man/systemd-fsckd.8: man/systemd-fsckd.service.8
> +man/systemd-fsckd.socket.8: man/systemd-fsckd.service.8
> man/systemd-hibernate-resume.8: man/systemd-hibernate-resume at .service.8
> man/systemd-hibernate.service.8: man/systemd-suspend.service.8
> man/systemd-hybrid-sleep.service.8: man/systemd-suspend.service.8
> @@ -606,6 +611,12 @@ man/systemd-fsck-root.service.html: man/systemd-fsck at .service.html
> man/systemd-fsck.html: man/systemd-fsck at .service.html
> $(html-alias)
>
> +man/systemd-fsckd.html: man/systemd-fsckd.service.html
> + $(html-alias)
> +
> +man/systemd-fsckd.socket.html: man/systemd-fsckd.service.html
> + $(html-alias)
> +
> man/systemd-hibernate-resume.html: man/systemd-hibernate-resume at .service.html
> $(html-alias)
>
> @@ -1732,6 +1743,7 @@ EXTRA_DIST += \
> man/systemd-escape.xml \
> man/systemd-firstboot.xml \
> man/systemd-fsck at .service.xml \
> + man/systemd-fsckd.service.xml \
> man/systemd-fstab-generator.xml \
> man/systemd-getty-generator.xml \
> man/systemd-gpt-auto-generator.xml \
> diff --git a/man/systemd-fsck at .service.xml b/man/systemd-fsck at .service.xml
> index ee66f37..d366712 100644
> --- a/man/systemd-fsck at .service.xml
> +++ b/man/systemd-fsck at .service.xml
> @@ -87,8 +87,9 @@
> check, number of mounts, unclean unmount, etc.</para>
>
> <para><filename>systemd-fsck</filename> will forward
> - file system checking progress to the console. If a
> - file system check fails for a service without
> + file system checking progress to
> + <filename>systemd-fsckd.service</filename>
> + socket. If a file system check fails for a service without
> <option>nofail</option>, emergency mode is activated,
> by isolating to
> <filename>emergency.target</filename>.</para>
> @@ -142,6 +143,7 @@
> <para>
> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
> <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>systemd-fsckd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> <citerefentry><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> <citerefentry><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> diff --git a/man/systemd-fsckd.service.xml b/man/systemd-fsckd.service.xml
> new file mode 100644
> index 0000000..befcc45
> --- /dev/null
> +++ b/man/systemd-fsckd.service.xml
> @@ -0,0 +1,170 @@
> +<?xml version="1.0"?>
> +<!--*-nxml-*-->
> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
> +<!--
> + This file is part of systemd.
> +
> + Copyright 2015 Canonical
> +
> + systemd is free software; you can redistribute it and/or modify it
> + under the terms of the GNU Lesser General Public License as published by
> + the Free Software Foundation; either version 2.1 of the License, or
> + (at your option) any later version.
> +
> + systemd is distributed in the hope that it will be useful, but
> + WITHOUT ANY WARRANTY; without even the implied warranty of
> + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
> + Lesser General Public License for more details.
> +
> + You should have received a copy of the GNU Lesser General Public License
> + along with systemd; If not, see <http://www.gnu.org/licenses/>.
> +-->
> +<refentry id="systemd-fsckd.service" xmlns:xi="http://www.w3.org/2001/XInclude">
Please use 2ch indentation for new man pages.
> +
> + <refentryinfo>
> + <title>systemd-fsckd.service</title>
> + <productname>systemd</productname>
> +
> + <authorgroup>
> + <author>
> + <contrib>Developer</contrib>
> + <firstname>Didier</firstname>
> + <surname>Roche</surname>
> + <email>didrocks at ubuntu.com</email>
> + </author>
> + </authorgroup>
> + </refentryinfo>
> +
> + <refmeta>
> + <refentrytitle>systemd-fsckd.service</refentrytitle>
> + <manvolnum>8</manvolnum>
> + </refmeta>
> +
> + <refnamediv>
> + <refname>systemd-fsckd.service</refname>
> + <refname>systemd-fsckd.socket</refname>
> + <refname>systemd-fsckd</refname>
> + <refpurpose>File system check progress reporting</refpurpose>
> + </refnamediv>
> +
> + <refsynopsisdiv>
> + <para><filename>systemd-fsckd.service</filename></para>
> + <para><filename>systemd-fsckd.socket</filename></para>
> + <para><filename>/usr/lib/systemd/systemd-fsckd</filename></para>
> + </refsynopsisdiv>
> +
> + <refsect1>
> + <title>Description</title>
> +
> + <para><filename>systemd-fsckd.service</filename> is a
> + service responsible for fetching file system check
receiving, not fetching
> + progress, and communicating some consolidated data
> + to console and plymouth (if running). It also handles
> + possible check cancellations.</para>
> + <para><filename>systemd-fsck-root.service</filename> or
> + <filename>systemd-fsck at .service</filename> will get the
> + progress from fsck and send their individual progress to
> + <filename>systemd-fsckd</filename>, through socket activation
> + by <filename>systemd-fsckd.socket</filename>.</para>
I think we don't need this kind of detail in the man page. It might change anyway.
> +
> + <para><filename>systemd-fsckd</filename> accepts
> + <filename>systemd-fsck</filename> UNIX domain
> + sockets communication, fetches the lowest progress value of
> + all fsck running in parallel with the number of devices
> + being currently checked. It writes the result to
> + <filename>/dev/console</filename> if show status is enabled,
> + and communicates to the user translated strings to plymouth
> + ready to be used by scripted themes, not supporting i18n.
> + The compilted plymouth themes can use the raw data (see below)
> + to display their own custom messages.</para>
> +
> + <para>The first time it connects to plymouth, a request
> + to grab c or C keypresses is sent, as well as a text message.
> + When the cancel key is pressed, all running fscks are terminated.
> + It will also any new fsck for the lifetime of
This sentence is missing some verb.
> + <filename>systemd-fsckd</filename>.</para>
> + </refsect1>
> +
> + <refsect1>
> + <title>Protocol with plymouth</title>
> +
> + <para><filename>systemd-fsckd</filename> passes the following
> + following messages to the theme via libplymouth:</para>
dup
> + <para>Progress update, sent as a plymouth update message:
> + <literal>fsckd:<num_devices>:<progress>:<string></literal>
> + <variablelist>
> + <varlistentry>
> + <term><literal><num_devices></literal></term>
> + <listitem><para>the current number of devices
> + being checked (int)</para></listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal><progress></literal></term>
> + <listitem><para>the current minimum percentage of
> + all devices being checking (float, from 0 to 100)</para></listitem>
> + </varlistentry>
> + <varlistentry>
> + <term><literal><string></literal></term>
> + <listitem><para>a translated message ready to be displayed
> + by the plymouth theme displaying the data above. It can be overriden
> + by themes supporting i18n.</para></listitem>
> + </varlistentry>
> + </variablelist>
> + </para>
> +
> + <para>Cancel message, sent as a traditional plymouth message:
> + <literal>fsckd-cancel-msg:<string></literal>
> + <variablelist>
> + <varlistentry>
> + <term><literal><strings></literal></term>
> + <listitem><para>a translated string ready to be displayed
> + by the plymouth theme indicating that c or C can be used to cancel
> + current checks. It can be overriden (matching only
> + <literal>fsckd-cancel-msg</literal> prefix)
> + by themes supporting i18n.</para></listitem>
> + </varlistentry>
> + </variablelist>
> + </para>
This is very detailed too, but it is OK, we don't really have a good place for this
kind of documentation.
> + </refsect1>
> +
> + <refsect1>
> + <title>Options</title>
> +
> + <para>The following options are understood:</para>
> +
> + <variablelist>
> + <xi:include href="standard-options.xml" xpointer="help" />
> + <xi:include href="standard-options.xml" xpointer="version" />
> + </variablelist>
> +
> + </refsect1>
> +
> + <refsect1>
> + <title>Exit status</title>
> +
> + <para>On success, 0 is returned, a non-zero failure
> + code otherwise. Note that the daemon stays idle for
> + a while to accept new <filename>systemd-fsck</filename>
> + connections before exiting.</para>
> + </refsect1>
> +
> + <refsect1>
> + <title>See Also</title>
> + <para>
> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>systemd-fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
> + <citerefentry><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
> + </para>
> + </refsect1>
> +
> +</refentry>
> diff --git a/units/systemd-fsckd.service.in b/units/systemd-fsckd.service.in
> index 27c325f..9c7ed51 100644
> --- a/units/systemd-fsckd.service.in
> +++ b/units/systemd-fsckd.service.in
> @@ -7,6 +7,7 @@
>
> [Unit]
> Description=File System Check Daemon to report status
> +Documentation=man:systemd-fsckd.service(8)
> DefaultDependencies=no
> Requires=systemd-fsckd.socket
> Before=shutdown.target
> diff --git a/units/systemd-fsckd.socket b/units/systemd-fsckd.socket
> index 96a034a..6f4badb 100644
> --- a/units/systemd-fsckd.socket
> +++ b/units/systemd-fsckd.socket
> @@ -7,7 +7,7 @@
>
> [Unit]
> Description=fsck to fsckd communication Socket
> -Documentation=man:systemd-fsck at .service(8) man:systemd-fsck-root.service(8)
> +Documentation=man:systemd-fsckd.service(8) man:systemd-fsck at .service(8) man:systemd-fsck-root.service(8)
> DefaultDependencies=no
> Before=sockets.target
Zbyszek
More information about the systemd-devel
mailing list