[systemd-devel] documentation and required version

[Zbigniew Jędrzejewski-Szmek]

On Wed, Jul 30, 2014 at 08:32:44AM -0400, Mauricio Tavares wrote:
> 's
> 
> On Wed, Jul 30, 2014 at 8:08 AM, Reindl Harald <h.reindl at thelounge.net> wrote:
> >
> >
> > Am 30.07.2014 13:58, schrieb Tom Gundersen:
> >> On Wed, Jul 30, 2014 at 1:21 PM, Reindl Harald <h.reindl at thelounge.net> wrote:
> >>> http://www.freedesktop.org/software/systemd/man/systemd.exec.html
> >>>
> >>> such error messages caused by list all sort of options
> >>> without any information when they where introduced are
> >>> really annoying - the docs should clearly say the minimum
> >>> required systemd version and the more options are added
> >>> the more important is that
> >>>
> >>> Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
> >>> section 'Service'
> >>> Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
> >>> section 'Service
> >>
> >> Won't this be solved by using the man pages shipped with the version
> >> of systemd you are using?
> >
> > no - for several reasons
> >
> > * it's more comfortable to use a website with working links like
> >   http://www.freedesktop.org/software/systemd/man/systemd.kill.html
> >   mentioned as example in ExecStop=
> >
> > * it's more comfortable to have STRG+F in a webbrowsers
> >
> > * i currently maintain machines with 204, 208 and 215
> >   having *one* manual open which lists all available options
> >   and mention the minimum version of them gives a better picture
> >
>       Tom, I see no reason why having the man page indicate when a
> given option was introduced be any worse than your suggestion. Since
> the online man page better be the latest one, if it stated when each
> option was introduced Reindl can use the online page as he wants and
> those who want to use the man page in their computers can do the same.
> Everyone wins.
Some of our man pages in section 3 partially have history, see e.g. [1].
I think having such information is very useful, but keeping it accurate
is harder then it might seem at first. For example look at
SocketUser/SocketGroup settings. They were added in systemd-214, but
then were backported to 208-stable and 204-stable, and appeared in
Fedora in a 204 update has Fedora 19 has been out for more than an a
year [2]. It turns out that in this case man pages distributed with
the system are a more accurate source of information then anything
that could be included by upstream. So I'd be happy to merge patches
which judiciously add history for manpages which describe API changes
(i.e. section 3), but in general I don't think we have the man power
to fully describe full history of all settings in systemd.

Zbyszek

[1] http://www.freedesktop.org/software/systemd/man/sd_journal_open.html#History
[2] https://admin.fedoraproject.org/updates/FEDORA-2014-8761/systemd-204-20.fc19