[systemd-devel] Examples in man pages

[Christian Seiler]

Am 24.01.2015 um 15:18 schrieb Zbigniew Jędrzejewski-Szmek:
> On Sat, Jan 24, 2015 at 02:13:00PM +0100, Christian Seiler wrote:
>> +                <example>
>> +                        <title>Making a unit enableable</title>
>> +
>> +                        <para>The following snippet makes a unit
>> +                        (e.g. <filename>foo.service</filename>)
>> +                        enableable via
>> +                        <command>systemctl enable</command>:</para>
>> +
>> +                        <programlisting>[Install]
>> +WantedBy=multi-user.target</programlisting>
>> +
>> +                        <para>After running
>> +                        <command>systemctl enable</command>, a symlink
>> +                        <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename>
>> +                        linking to the actual unit will be created. It
>> +                        tells systemd to pull in the unit when starting
>> +                        <filename>multi-user.target</filename>. The
>> +                        converse <command>systemctl disable</command>
>> +                        will remove that symlink again.</para>
> The description is good. I wonder if it might better to inlcude a complete
> unit here and discuss all lines, instead of just a snippet.

I wanted to keep it as minimal an example as possible, but maybe
something absolutely trivial such as:

[Unit]
Description=Foo

[Service]
ExecStart=/usr/sbin/foo-daemon

[Install]
WantedBy=multi-user.target

with the last section highlighted (<emphasis>)? I don't want to make it
too complicated.

>> [ example about overriding vendor defaults ]
> This part looks nice too.

Thanks!

I'll then go on and write a couple more examples for different typical
use cases. Here's what I'd want to cover:

 - systemd.service(5)
     - Type=simple
          - RemainAfterExit= discussion
     - Type=oneshot
          - RemainAfterExit= discussion
     - Type=forking
          - PIDFile=, GuessMainPID=
     - Type=dbus
     - Type=notify
          - also include snippet for required code in daemon and
            link to sd_notify(3)
     - Type=idle: getty example

 - systemd.target(5)
     - use remote-fs.target to discuss how synchronization points via
       targets work (but also note how DefaultDependencies= makes that
       one special)
     - example of service group with PartOf=

 - systemd.socket(5)
     - inetd style activation Accept=yes
     - systemd style activation Accept=no
          - also include snippet for required code in daemon and
            link to sd_listen_fds()/...

 - systemd.timer(5)
     - just a trivial example w/ a oneshot service

 - systemd.path(5)
     - dynamically activate service based on presence of configuration
       (and explain difference to ConditionPatchExists=)

 - systemd.mount(5), systemd.automount(5) and systemd.swap(5)
     - an example that is equivalent to a given entry in /etc/fstab
       and then explain how additional systemd options such as
       Condition...= can be used to go beyond what is possible in
       /etc/fstab

I'll probably skip systemd.device(5), because I can't think of a good
example for manually using those units.

Did I forget anything?

Christian