man: add various filenames to the index

Everything which is an absolute filename marked with <filename></filename>
lands in the index, unless noindex= attribute is present. Should make
it easier for people to find stuff when they are looking at a file on
disk.

Various formatting errors in manpages are fixed, kernel-install(1) is
restored to formatting sanity.
parent 202288be
......@@ -193,16 +193,25 @@ def _extract_directives(directive_groups, formatting, page):
formatting[text] = name
storfile = directive_groups['filenames']
for xpath in ('.//refsynopsisdiv//filename',
'.//refsynopsisdiv//command'):
for xpath, absolute_only in (('.//refsynopsisdiv//filename', False),
('.//refsynopsisdiv//command', False),
('.//filename', True)):
for name in t.iterfind(xpath):
if absolute_only and not (name.text and name.text.startswith('/')):
continue
if name.attrib.get('noindex'):
continue
name.tail = ''
if name.text:
if name.text.endswith('*'):
name.text = name.text[:-1]
if not name.text.startswith('.'):
text = name.text.partition(' ')[0]
if text != name.text:
name.clear()
name.text = text
if text.endswith('/'):
text = text[:-1]
storfile[text].append((pagename, section))
if text not in formatting:
# use element as formatted display
......
......@@ -652,7 +652,7 @@
<programlisting>journalctl /usr/bin/dbus-daemon</programlisting>
<para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para>
<para>Show all logs of the kernel device node <filename noindex='true'>/dev/sda</filename>:</para>
<programlisting>journalctl /dev/sda</programlisting>
......
......@@ -49,7 +49,10 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<refsynopsisdiv>
<cmdsynopsis>
<command>kernel-install</command> <arg choice="req">COMMAND</arg> <arg choice="req">KERNEL VERSION</arg> <arg choice="req">KERNEL IMAGE</arg>
<command>kernel-install</command>
<arg choice="plain">COMMAND</arg>
<arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
<arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
......@@ -60,9 +63,10 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
initramfs images to and from <filename>/boot</filename>.
</para>
<para>kernel-install will execute the files located in the directory <filename>/usr/lib/kernel/install.d/</filename>
<para><command>kernel-install</command> will execute the files
located in the directory <filename>/usr/lib/kernel/install.d/</filename>
and the local administration directory <filename>/etc/kernel/install.d/</filename>.
All files are collectively sorted and executed in lexical order, regardless of the directories in
All files are collectively sorted and executed in lexical order, regardless of the directory in
which they live. However, files with identical file names replace each other.
Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
......@@ -78,29 +82,44 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term>add &lt;KERNEL VERSION> &lt;KERNEL IMAGE></term>
<term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></command></term>
<listitem>
<para>calls every executable <filename>/usr/lib/kernel/install.d/*.install</filename>
and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
"add &lt;KERNEL VERSION> <filename>/boot/&lt;MACHINE-ID>/&lt;KERNEL VERSION>/</filename>"</para>
<para>kernel-install copies &lt;KERNEL IMAGE> to
<filename>/boot/&lt;MACHINE-ID>/&lt;KERNEL VERSION>/linux</filename>.</para>
<para>kernel-install also creates a boot loader entry according to the boot loader specification
in <filename>/boot/loader/entries/&lt;MACHINE-ID>-&lt;KERNEL VERSION>.conf</filename>.
If the file <filename>initrd</filename> is found next to the <filename>linux</filename> file,
the initrd will be added to the configuration.</para>
<para>calls every executable
<filename>/usr/lib/kernel/install.d/*.install</filename> and
<filename>/etc/kernel/install.d/*.install</filename> with
the arguments
<programlisting>
add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
</programlisting>
</para>
<para><command>kernel-install</command> copies
<replaceable>KERNEL-IMAGE</replaceable> to
<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
</para>
<para><command>kernel-install</command> also creates a boot
loader entry according to the boot loader specification in
<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
If the file <filename>initrd</filename> is found next to the
<filename>linux</filename> file, the initrd will be added to
the configuration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>remove &lt;KERNEL VERSION> &lt;KERNEL IMAGE></term>
<listitem><para>calls every executable <filename>/usr/lib/kernel/install.d/*.install</filename>
and <filename>/etc/kernel/install.d/*.install</filename> with the arguments:
"remove &lt;KERNEL VERSION> <filename>/boot/&lt;MACHINE-ID>/&lt;KERNEL VERSION>/</filename>"
</para>
<para>kernel-install removes the entire directory <filename>/boot/&lt;MACHINE-ID>/&lt;KERNEL VERSION>/</filename>
and the file <filename>/boot/loader/entries/&lt;MACHINE-ID>-&lt;KERNEL VERSION>.conf</filename></para>
<term><command>remove</command> <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></term>
<listitem>
<para>calls every executable <filename>/usr/lib/kernel/install.d/*.install</filename>
and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
<programlisting>
remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
</programlisting>
</para>
<para><command>kernel-install</command> removes the entire directory
<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
and the file
<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename></para>
</listitem>
</varlistentry>
......@@ -140,7 +159,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<filename>/etc/machine-id</filename>
</term>
<listitem>
<para>The content of the file specifies the machine identification &lt;MACHINE-ID>.</para>
<para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
......@@ -148,7 +167,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<filename>/etc/os-release</filename>
</term>
<listitem>
<para>The content of the file specifies the operating system id &lt;OS-ID>.</para>
<para>The content of the file specifies the operating system id <replaceable>OS-ID</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
......
......@@ -129,7 +129,7 @@
<example>
<title>German locale with English messages</title>
<para><filename>/etc/locale.conf:</filename></para>
<para><filename>/etc/locale.conf</filename>:</para>
<programlisting>LANG=de_DE.UTF-8
LC_MESSAGES=C</programlisting>
......
......@@ -168,7 +168,7 @@
<example>
<title>Invoke a program</title>
<para>This calls <filename>/bin/ls</filename>
<para>This calls <filename noindex='true'>/bin/ls</filename>
with STDOUT/STDERR connected to the
journal:</para>
......
......@@ -360,7 +360,7 @@
# systemd-nspawn -bD /srv/mycontainer</programlisting>
<para>This installs a minimal Fedora distribution into
the directory <filename>/srv/mycontainer/</filename> and
the directory <filename noindex='true'>/srv/mycontainer/</filename> and
then boots an OS in a namespace container in
it.</para>
</refsect1>
......
......@@ -70,7 +70,7 @@
<filename>/usr</filename> and the virtual kernel API
file systems such as <filename>/proc</filename>,
<filename>/sys</filename> or
<filename>/dev/</filename>. This service executes no
<filename>/dev</filename>. This service executes no
operation if <filename>/etc/fstab</filename> does not
exist or lists no entries for the mentioned file
systems.</para>
......
......@@ -70,7 +70,7 @@
<para>Automount units must be named after the
automount directories they control. Example: the
automount point <filename>/home/lennart</filename>
automount point <filename noindex='true'>/home/lennart</filename>
must be configured in a unit file
<filename>home-lennart.automount</filename>. For
details about the escaping logic used to convert a
......
......@@ -80,7 +80,7 @@
<para>Device units are named after the
<filename>/sys</filename> and
<filename>/dev</filename> paths they control. Example:
the device <filename>/dev/sda5</filename> is exposed
the device <filename noindex='true'>/dev/sda5</filename> is exposed
in systemd as <filename>dev-sda5.device</filename>. For
details about the escaping logic used to convert a
file system path to a unit name see
......
......@@ -799,10 +799,10 @@
space-separated list of cgroup
identifiers. A cgroup identifier is
formatted like
<filename>cpu:/foo/bar</filename>,
<filename noindex='true'>cpu:/foo/bar</filename>,
where "cpu" indicates the kernel
control group controller used, and
<filename>/foo/bar</filename> is the
<filename noindex='true'>/foo/bar</filename> is the
control group path. The controller
name and ":" may be omitted in which
case the named systemd control group
......
......@@ -86,7 +86,7 @@
<para>Mount units must be named after the mount point
directories they control. Example: the mount point
<filename>/home/lennart</filename> must be configured
<filename noindex='true'>/home/lennart</filename> must be configured
in a unit file
<filename>home-lennart.mount</filename>. For details
about the escaping logic used to convert a file system
......
......@@ -79,7 +79,7 @@
<para>Swap units must be named after the devices
or files they control. Example: the swap device
<filename>/dev/sda5</filename> must be configured in a
<filename noindex='true'>/dev/sda5</filename> must be configured in a
unit file <filename>dev-sda5.swap</filename>. For
details about the escaping logic used to convert a
file system path to a unit name see
......
......@@ -197,7 +197,7 @@
<para>Some unit names reflect paths existing in the
file system name space. Example: a device unit
<filename>dev-sda.device</filename> refers to a device
with the device node <filename>/dev/sda</filename> in
with the device node <filename noindex='true'>/dev/sda</filename> in
the file system namespace. If this applies a special
way to escape the path name is used, so that the
result is usable as part of a file name. Basically,
......
......@@ -124,7 +124,7 @@
<example>
<title>German keyboard and console</title>
<para><filename>/etc/vconsole.conf:</filename></para>
<para><filename>/etc/vconsole.conf</filename>:</para>
<programlisting>KEYMAP=de-latin1
FONT=latarcyrheb-sun16</programlisting>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment