Merge f4429e9753 into bf39626d61

Otherwise, `<variable>$BOOT</variable>` is rendered:

```
[2548/2992] Generating man/repart.d.5 with a custom command
Element variable in namespace '' encountered in para, but no template matches.
Element variable in namespace '' encountered in para, but no template matches.
```

.gitattributes

@@ -2,6 +2,7 @@
 *.gpg  binary generated
 *.bmp  binary
 *.base64 generated
+*.rst conflict-marker-size=100
 
 # Mark files as "generated", i.e. no license applies to them.
 # This includes output from programs, directive lists generated by grepping

.gitignore

@@ -39,3 +39,6 @@ mkosi.local.conf
 .dir-locals-2.el
 .vscode/
 /pkg/
+/doc-migration/.venv
+/doc-migration/build
+.venv

doc-migration/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc-migration/README.md

@@ -0,0 +1,172 @@
+# Migration of Documentation from Docbook to Sphinx
+
+- [Migration of Documentation from Docbook to Sphinx](#migration-of-documentation-from-docbook-to-sphinx)
+  - [Prerequisites](#prerequisites)
+  - [Transformation Process](#transformation-process)
+    - [1. Docbook to `rst`](#1-docbook-to-rst)
+    - [2. `rst` to Sphinx](#2-rst-to-sphinx)
+      - [Sphinx Extensions](#sphinx-extensions)
+        - [sphinxcontrib-globalsubs](#sphinxcontrib-globalsubs)
+      - [Custom Sphinx Extensions](#custom-sphinx-extensions)
+        - [directive_roles.py (90% done)](#directive_rolespy-90-done)
+        - [external_man_links.py](#external_man_linkspy)
+      - [Includes](#includes)
+  - [Todo:](#todo)
+
+## Prerequisites
+
+Python dependencies for parsing docbook files and generating `rst`:
+
+- `lxml`
+
+Python dependencies for generating `html` and `man` pages from `rst`:
+
+- `sphinx`
+- `sphinxcontrib-globalsubs`
+- `furo` (The Sphinx theme)
+
+To install these (see [Sphinx Docs](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html#setting-up-your-project-and-development-environment)):
+
+```sh
+# Generate a Python env:
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+# Install deps
+$ python3 -m pip install -U lxml
+$ python3 -m pip install -U sphinx
+$ python3 -m pip install -U sphinxcontrib-globalsubs
+$ python3 -m pip install -U furo
+$ cd doc-migration && ./convert.sh
+```
+
+## Transformation Process
+
+You can run the entire process with `./convert.sh` in the `doc-migration` folder. The individual steps are:
+
+### 1. Docbook to `rst`
+
+Use the `main.py` script to convert a single Docbook file to `rst`:
+
+```sh
+# in the `doc-migration` folder:
+$ python3 main.py --file ../man/busctl.xml --output 'in-progress'
+```
+
+This file calls `db2rst.py` that parses Docbook elements on each file, does some string transformation to the contents of each, and glues them all back together again. It will also output info on unhandled elements, so we know whether our converter is feature complete and can achieve parity with the old docs.
+
+To run the script against all files you can use :
+
+```sh
+# in the `doc-migration` folder:
+$ python3 main.py --dir ../man --output 'in-progress'
+```
+
+> When using the script to convert all files at once in our man folder we recommend using "in-progress" folder name as our output dir so we don't end up replacing some the files that were converted and been marked as finished inside the source folder.
+
+After using the above script at least once you will get two files(`errors.json`,`successes_with_unhandled_tags.json`) in the output dir.
+
+`errors.json` will have all the files that failed to convert to rst with the respective error message for each file.
+running : `python3 main.py --errored` will only process the files that had an error and present in `errors.json`
+
+`successes_with_unhandled_tags.json` will have all the files that were converted but there were still some tags that are not defined in `db2rst.py` yet.
+
+running : `python3 main.py --unhandled-only` will only process the files that are present in `successes_with_unhandled_tags.json`
+
+This is to avoid running all files at once when we only need to work on files that are not completely processed.
+
+### 2. `rst` to Sphinx
+
+```sh
+# in the `/doc-migration` folder
+$ rm -rf build
+# ☝️ if you already have a build
+$ make html man
+```
+
+- The `html` files end up in `/doc-migration/build/html`. Open the `index.html` there to browse the docs.
+- The `man` files end up in `/doc-migration/build/man`. Preview an individual file with `$ mandoc -l build/man/busctl.1`
+
+#### Sphinx Extensions
+
+We use the following Sphinx extensions to achieve parity with the old docs:
+
+##### sphinxcontrib-globalsubs
+
+Allows referencing variables in the `global_substitutions` object in `/doc-migrations/source/conf.py` (the Sphinx config file).
+
+#### Custom Sphinx Extensions
+
+##### directive_roles.py (90% done)
+
+This is used to add custom Sphinx directives and roles to generate systemD directive lists page.
+
+To achieve the functionality exiting in `tools/make-directive-index.py` by building the Directive Index page from custom Sphinx role, here is an example:
+
+The formula for those sphinx roles is like this: `:directive:{directive_id}:{type}`
+
+For example we can use an inline Sphinx role like this:
+
+```
+ :directive:environment-variables:var:`SYSEXT_SCOPE=`
+```
+
+This will be then inserted in the SystemD directive page on build under the group `environment-variables`
+we can use the `{type}` to have more control over how this will be treated inside the Directive Index page.
+
+##### external_man_links.py
+
+This is used to create custom sphinx roles to handle external links for man pages to avoid having full urls in rst for example:
+
+`:die-net:`refentrytitle(manvolnum)` will lead to 'http://linux.die.net/man/{manvolnum}/{refentrytitle}'
+a full list of these roles can be found in [external_man_links](source/_ext/external_man_links.py).
+
+#### Includes
+
+1. Versions
+   In the Docbook files you may find lines like these: `<xi:include href="version-info.xml" xpointer="v205"/>` which would render into `Added in version 205` in the docs. This is now archived with the existing [sphinx directive ".. versionadded::"](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded) and represented as `.. versionadded:: 205` in the rst file
+
+2. Code Snippets
+   These can be included with the [literalinclude directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) when living in their own file.
+
+   Example:
+
+  ```rst
+  .. literalinclude:: ./check-os-release-simple.py
+  :language: python
+  ```
+
+  There is also the option to include a [code block](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) directly in the rst file.
+
+  Example:
+
+  ```rst
+  .. code-block:: sh
+
+  a{sv} 3 One s Eins Two u 2 Yes b true
+
+  ```
+
+3. Text Snippets
+
+  There are a few xml files were sections of these files are reused in multiple other files. While it is no problem to include a whole other rst file the concept of only including a part of that file is a bit more tricky. You can choose to include text partial that starts after a specific text and also to stop before reaching another text. So we decided it would be best to add start and stop markers to define the section in these source files. These markers are: `.. inclusion-marker-do-not-remove` / ``So that a`<xi:include href="standard-options.xml" xpointer="no-pager" />` turns into:
+
+  ```rst
+  .. include:: ./standard-options.rst
+    :start-after: .. inclusion-marker-do-not-remove no-pager
+    :end-before: .. inclusion-end-marker-do-not-remove no-pager
+  ```
+
+## Todo
+
+An incomplete list.
+
+- [ ] Custom Link transformations:
+  - [ ] `custom-man.xsl`
+  - [x] `custom-html.xsl`
+- [ ] See whether `tools/tools/xml_helper.py` does anything we don’t do, this also contains useful code for:
+  - [ ] Build a man index, as in `tools/make-man-index.py`
+  - [x] Build a directives index, as in `tools/make-directive-index.py`
+  - [ ] DBUS doc generation `tools/update-dbus-docs.py`
+- [ ] See whether `tools/update-man-rules.py` does anything we don’t do
+- [ ] Make sure the `man_pages` we generate for Sphinx’s `conf.py` match the Meson rules in `man/rules/meson.build`
+- [ ] Re-implement check-api-docs

doc-migration/convert.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# SPDX-License-Identifier: LGPL-2.1-or-later
+
+# Array of XML filenames
+files=("sd_journal_get_data" "busctl" "systemd" "journalctl" "os-release")
+
+# Directory paths
+input_dir="../man"
+output_dir="source/docs"
+
+echo "---------------------"
+echo "Converting xml to rst"
+echo ""
+# Iterate over the filenames
+for file in "${files[@]}"; do
+    echo "------------------"
+    python3 main.py --dir ${input_dir} --output ${output_dir} --file "${file}.xml"
+done
+
+# Clean and build
+rm -rf build
+
+echo "--------------------"
+echo "Building Sphinx Docs"
+echo "--------------------"
+make html

doc-migration/db2rst.py

@@ -0,0 +1,789 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# SPDX-License-Identifier: LGPL-2.1-or-later
+"""
+    DocBook to ReST converter
+    =========================
+    This script may not work out of the box, but is easy to extend.
+    If you extend it, please send me a patch: wojdyr at gmail.
+
+    Docbook has >400 elements, most of them are not supported (yet).
+    ``pydoc db2rst`` shows the list of supported elements.
+
+    In reST, inline markup can not be nested (major deficiency of reST).
+    Since it is not clear what to do with, say,
+    <subscript><emphasis>x</emphasis></subscript>
+    the script outputs incorrect (nested) reST (:sub:`*x*`)
+    and it is up to user to decide how to change it.
+
+    Usage: db2rst.py file.xml > file.rst
+
+    Ported to Python3 in 2024 by neighbourhood.ie
+
+    :copyright: 2009 by Marcin Wojdyr.
+    :license: BSD.
+"""
+
+# If this option is True, XML comment are discarded. Otherwise, they are
+# converted to ReST comments.
+# Note that ReST doesn't support inline comments. XML comments
+# are converted to ReST comment blocks, what may break paragraphs.
+from source import conf
+import lxml.etree as ET
+import re
+import sys
+import os
+from pathlib import Path
+REMOVE_COMMENTS = False
+
+# id attributes of DocBook elements are translated to ReST labels.
+# If this option is False, only labels that are used in links are generated.
+WRITE_UNUSED_LABELS = False
+
+
+# The Files have sections that are used as includes in other files
+FILES_USED_FOR_INCLUDES = ['sd_journal_get_data.xml', 'standard-options.xml',
+                           'user-system-options.xml', 'common-variables.xml','standard-conf.xml',
+                           'libsystemd-pkgconfig.xml', 'threads-aware.xml']
+
+# to avoid dupliate error reports
+_not_handled_tags = set()
+
+# to remember which id/labels are really needed
+_linked_ids = set()
+
+# buffer that is flushed after the end of paragraph,
+# used for ReST substitutions
+_buffer = ""
+
+_indent_next_listItem_by = 0
+
+
+def _run(input_file, output_dir):
+    sys.stderr.write("Parsing XML file `%s'...\n" % input_file)
+
+    parser = ET.XMLParser(remove_comments=REMOVE_COMMENTS, no_network=False)
+    tree = ET.parse(input_file, parser=parser)
+
+    for elem in tree.iter():
+        if elem.tag in ("xref", "link"):
+            _linked_ids.add(elem.get("linkend"))
+
+    output_file = os.path.join(output_dir, os.path.basename(
+        input_file).replace('.xml', '.rst'))
+
+    with open(output_file, 'w') as file:
+        file.write(TreeRoot(tree.getroot()).encode('utf-8').decode('utf-8'))
+
+
+def _warn(s):
+    sys.stderr.write("WARNING: %s\n" % s)
+
+
+def _supports_only(el, tags):
+    "print warning if there are unexpected children"
+    for i in el:
+        if i.tag not in tags:
+            _warn("%s/%s skipped." % (el.tag, i.tag))
+
+
+def _what(el):
+    "returns string describing the element, such as <para> or Comment"
+    if isinstance(el.tag, str):
+        return "<%s>" % el.tag
+    elif isinstance(el, ET._Comment):
+        return "Comment"
+    else:
+        return str(el)
+
+
+def _has_only_text(el):
+    "print warning if there are any children"
+    if list(el):
+        _warn("children of %s are skipped: %s" % (_get_path(el),
+                                                  ", ".join(_what(i) for i in el)))
+
+
+def _has_no_text(el):
+    "print warning if there is any non-blank text"
+    if el.text is not None and not el.text.isspace():
+        _warn("skipping text of <%s>: %s" % (_get_path(el), el.text))
+    for i in el:
+        if i.tail is not None and not i.tail.isspace():
+            _warn("skipping tail of <%s>: %s" % (_get_path(i), i.tail))
+
+
+def _includes(el):
+    file_path_pathlib = Path(el.get('href'))
+    file_extension = file_path_pathlib.suffix
+    include_files = FILES_USED_FOR_INCLUDES
+    if file_extension == '.xml':
+        if el.get('href') == 'version-info.xml':
+            versionString = conf.global_substitutions.get(
+                el.get("xpointer"))
+            # `\n\n   \n\n   ` forces a newline and subsequent indent.
+            # The empty spaces are stripped later
+            return f".. only:: html\n\n   \n\n   .. versionadded:: {versionString}\n\n   "
+        elif not el.get("xpointer"):
+            return f".. include:: ../includes/{el.get('href').replace('xml', 'rst')}"
+        elif el.get('href') in include_files:
+            return f""".. include:: ../includes/{el.get('href').replace('xml', 'rst')}
+                    :start-after: .. inclusion-marker-do-not-remove {el.get("xpointer")}
+                    :end-before: .. inclusion-end-marker-do-not-remove {el.get("xpointer")}
+                    """
+
+    elif file_extension == '.c':
+        return f""".. literalinclude:: /code-examples/c/{el.get('href')}
+                    :language: c
+                """
+    elif file_extension == '.py':
+        return f""".. literalinclude:: /code-examples/py/{el.get('href')}
+                    :language: python
+                """
+    elif file_extension == '.sh':
+        return f""".. literalinclude:: /code-examples/sh/{el.get('href')}
+                    :language: shell
+                """
+
+
+def _conv(el):
+    "element to string conversion; usually calls element_name() to do the job"
+    if el.tag in globals():
+        s = globals()[el.tag](el)
+        assert s, "Error: %s -> None\n" % _get_path(el)
+        return s
+    elif isinstance(el, ET._Comment):
+        return Comment(el) if (el.text and not el.text.isspace()) else ""
+    else:
+        if el.tag not in _not_handled_tags:
+            # Convert version references to `versionAdded` directives
+            if el.tag == "{http://www.w3.org/2001/XInclude}include":
+                return _includes(el)
+            else:
+                _warn("Don't know how to handle <%s>" % el.tag)
+                _warn(" ... from path: %s" % _get_path(el))
+                _not_handled_tags.add(el.tag)
+        return _concat(el)
+
+
+def _no_special_markup(el):
+    return _concat(el)
+
+
+def _remove_indent_and_escape(s, tag):
+    if tag == "programlisting":
+        return s
+    "remove indentation from the string s, escape some of the special chars"
+    s = "\n".join(i.lstrip().replace("\\", "\\\\") for i in s.splitlines())
+    # escape inline mark-up start-string characters (even if there is no
+    # end-string, docutils show warning if the start-string is not escaped)
+    # TODO: handle also Unicode: ‘ “ ’ « ¡ ¿ as preceding chars
+    s = re.sub(r"([\s'\"([{</:-])"  # start-string is preceded by one of these
+               r"([|*`[])"  # the start-string
+               r"(\S)",    # start-string is followed by non-whitespace
+               r"\1\\\2\3",  # insert backslash
+               s)
+    return s
+
+
+def _concat(el):
+    "concatate .text with children (_conv'ed to text) and their tails"
+    s = ""
+    id = el.get("id")
+    if id is not None and (WRITE_UNUSED_LABELS or id in _linked_ids):
+        s += "\n\n.. _%s:\n\n" % id
+    if el.text is not None:
+        s += _remove_indent_and_escape(el.text, el.tag)
+    for i in el:
+        s += _conv(i)
+        if i.tail is not None:
+            if len(s) > 0 and not s[-1].isspace() and i.tail[0] in " \t":
+                s += i.tail[0]
+            s += _remove_indent_and_escape(i.tail, el.tag)
+    return s.strip()
+
+
+def _original_xml(el):
+    return ET.tostring(el, with_tail=False).decode('utf-8')
+
+
+def _no_markup(el):
+    s = ET.tostring(el, with_tail=False).decode('utf-8')
+    s = re.sub(r"<.+?>", " ", s)  # remove tags
+    s = re.sub(r"\s+", " ", s)  # replace all blanks with single space
+    return s
+
+
+def _get_level(el):
+    "return number of ancestors"
+    return sum(1 for i in el.iterancestors())
+
+
+def _get_path(el):
+    t = [el] + list(el.iterancestors())
+    return "/".join(str(i.tag) for i in reversed(t))
+
+
+def _make_title(t, level, indentLevel=0):
+    t = t.replace('\n', ' ').strip()
+
+    if level == 1:
+        return "\n\n" + "=" * len(t) + "\n" + t + "\n" + "=" * len(t)
+
+    char = ["#", "=", "-", "~", "^", "."]
+    underline = char[level-2] * len(t)
+    indentation = " "*indentLevel
+    return f"\n\n{indentation}{t}\n{indentation}{underline}"
+
+
+def _join_children(el, sep):
+    _has_no_text(el)
+    return sep.join(_conv(i) for i in el)
+
+
+def _block_separated_with_blank_line(el):
+    s = ""
+    id = el.get("id")
+    if id is not None:
+        s += "\n\n.. inclusion-marker-do-not-remove %s\n\n" % id
+    s += "\n\n" + _concat(el)
+    if id is not None:
+        s += "\n\n.. inclusion-end-marker-do-not-remove %s\n\n" % id
+    return s
+
+
+def _indent(el, indent, first_line=None, suppress_blank_line=False):
+    "returns indented block with exactly one blank line at the beginning"
+    start = "\n\n"
+    if suppress_blank_line:
+        start = ""
+
+    # lines = [" "*indent + i for i in _concat(el).splitlines()
+    #         if i and not i.isspace()]
+    # TODO: This variant above strips empty lines within elements. We don’t want that to happen, at least not always
+    lines = [" "*indent + i for i in _concat(el).splitlines()
+             if i]
+    if first_line is not None:
+        # replace indentation of the first line with prefix `first_line'
+        lines[0] = first_line + lines[0][indent:]
+    return start + "\n".join(lines)
+
+
+def _normalize_whitespace(s):
+    return " ".join(s.split())
+
+###################           DocBook elements        #####################
+
+# special "elements"
+
+
+def TreeRoot(el):
+    output = _conv(el)
+    # add .. SPDX-License-Identifier: LGPL-2.1-or-later:
+    output = '\n\n'.join(
+        ['.. SPDX-License-Identifier: LGPL-2.1-or-later:', output])
+    # remove trailing whitespace
+    output = re.sub(r"[ \t]+\n", "\n", output)
+    # leave only one blank line
+    output = re.sub(r"\n{3,}", "\n\n", output)
+    return output
+
+
+def Comment(el):
+    return _indent(el, 12, ".. COMMENT: ")
+
+# Meta refs
+
+
+def refentry(el):
+    return _concat(el)
+
+# FIXME: how to ignore/delete a tag???
+
+
+def refentryinfo(el):
+    # ignore
+    return '  '
+
+
+def refnamediv(el):
+    # return '**Name** \n\n' + _make_title(_join_children(el, ' — '), 2)
+    return '.. only:: html\n\n' + _make_title(_join_children(el, ' — '), 2, 3)
+
+
+def refsynopsisdiv(el):
+    # return '**Synopsis** \n\n' + _make_title(_join_children(el, ' '), 3)
+    s = ""
+    s += _make_title('Synopsis', 2, 3)
+    s += '\n\n'
+    s += _join_children(el, ', ')
+    return s
+
+def refname(el):
+    _has_only_text(el)
+    return "%s" % el.text
+
+
+def refpurpose(el):
+    _has_only_text(el)
+    return "%s" % el.text
+
+
+def cmdsynopsis(el):
+    return _join_children(el, ' ')
+
+
+def arg(el):
+    text = el.text
+    if text is None:
+        text = _join_children(el, '')
+    # choice: req, opt, plain
+    choice = el.get("choice")
+    if choice == 'opt':
+        return f"[%s{'...' if el.get('rep') == 'repeat' else ''}]" % text
+    elif choice == 'req':
+        return "{%s}" % text
+    elif choice == 'plain':
+        return "%s" % text
+    else:
+        "print warning if there another choice"
+        _warn("skipping arg with choice of: %s" % (choice))
+
+
+# general inline elements
+
+def emphasis(el):
+    return "*%s*" % _concat(el).strip()
+
+
+phrase = emphasis
+citetitle = emphasis
+
+
+acronym = _no_special_markup
+
+
+def command(el):
+    # Only enclose in backticks if it’s not part of a term
+    # (which is already enclosed in backticks)
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def literal(el):
+    return "\"%s\"" % _concat(el).strip()
+
+
+def varname(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:var:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def option(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:option:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def constant(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:constant:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+filename = command
+
+def optional(el):
+    return "[%s]" % _concat(el).strip()
+
+
+def replaceable(el):
+    return "<%s>" % _concat(el).strip()
+
+
+def term(el):
+    if el.getparent().index(el) != 0:
+        return ' '
+
+    level = _get_level(el)
+    if level > 5:
+        level = 5
+    # Sometimes, there are multiple terms for one entry. We want those displayed in a single line, so we gather them all up and parse them together
+    hasMultipleTerms = False
+    titleStrings = [_concat(el).strip()]
+    title = ''
+    for term in el.itersiblings(tag='term'):
+        # We only arrive here if there is more than one `<term>` in the `el`
+        hasMultipleTerms = True
+        titleStrings.append(_concat(term).strip())
+
+    if hasMultipleTerms:
+        title = ', '.join(titleStrings)
+        # return _make_title(f"``{titleString}``", 4)
+    else:
+        title = _concat(el).strip()
+
+    if level >= 5:
+        global _indent_next_listItem_by
+        _indent_next_listItem_by += 3
+        return f".. option:: {title}\n\n   \n\n   "
+    return _make_title(f"``{title}``", level) + '\n\n'
+
+# links
+
+
+def ulink(el):
+    url = el.get("url")
+    text = _concat(el).strip()
+    if text.startswith(".. image::"):
+        return "%s\n   :target: %s\n\n" % (text, url)
+    elif url == text:
+        return text
+    elif not text:
+        return "`<%s>`_" % (url)
+    else:
+        return "`%s <%s>`_" % (text, url)
+
+# TODO: other elements are ignored
+
+
+def xref(el):
+    _has_no_text(el)
+    id = el.get("linkend")
+    return ":ref:`%s`" % id if id in _linked_ids else ":ref:`%s <%s>`" % (id, id)
+
+
+def link(el):
+    _has_no_text(el)
+    return "`%s`_" % el.get("linkend")
+
+
+# lists
+
+def itemizedlist(el):
+    return _indent(el, 2, "* ", True)
+
+
+def orderedlist(el):
+    return _indent(el, 2, "1. ", True)
+
+
+def simplelist(el):
+    type = el.get("type")
+    if type == "inline":
+        return _join_children(el, ', ')
+    else:
+        return _concat(el)
+
+
+def member(el):
+    return _concat(el)
+
+# varlists
+
+
+def variablelist(el):
+    return _concat(el)
+
+
+def varlistentry(el):
+    s = ""
+    id = el.get("id")
+    if id is not None:
+        s += "\n\n.. inclusion-marker-do-not-remove %s\n\n" % id
+    for i in el:
+        if i.tag == 'term':
+            s += _conv(i) + '\n\n'
+        else:
+            # Handle nested list items, this is mainly for
+            # options that have options
+            if i.tag == 'listitem':
+                global _indent_next_listItem_by
+                s += _indent(i, _indent_next_listItem_by, None, True)
+                _indent_next_listItem_by = 0
+            else:
+                s += _indent(i, 0, None, True)
+    if id is not None:
+        s += "\n\n.. inclusion-end-marker-do-not-remove %s\n\n" % id
+    return s
+
+
+def listitem(el):
+    _supports_only(
+        el, ["para", "simpara", "{http://www.w3.org/2001/XInclude}include"])
+    return _block_separated_with_blank_line(el)
+
+# sections
+
+
+def example(el):
+    # FIXME: too hacky?
+    elements = [i for i in el]
+    first, rest = elements[0], elements[1:]
+
+    return _make_title(_concat(first), 4) + "\n\n" + "".join(_conv(i) for i in rest)
+
+
+def sect1(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect2(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect3(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect4(el):
+    return _block_separated_with_blank_line(el)
+
+
+def section(el):
+    return _block_separated_with_blank_line(el)
+
+
+def title(el):
+    return _make_title(_concat(el).strip(), _get_level(el) + 1)
+
+# bibliographic elements
+
+
+def author(el):
+    _has_only_text(el)
+    return "\n\n.. _author:\n\n**%s**" % el.text
+
+
+def date(el):
+    _has_only_text(el)
+    return "\n\n.. _date:\n\n%s" % el.text
+
+# references
+
+
+def citerefentry(el):
+    project = el.get("project")
+    refentrytitle = el.xpath("refentrytitle")[0].text
+    manvolnum = el.xpath("manvolnum")[0].text
+
+    extlink_formats = {
+        'man-pages': f':man-pages:`{refentrytitle}({manvolnum})`',
+        'die-net': f':die-net:`{refentrytitle}({manvolnum})`',
+        'mankier': f':mankier:`{refentrytitle}({manvolnum})`',
+        'archlinux': f':archlinux:`{refentrytitle}({manvolnum})`',
+        'debian': f':debian:`{refentrytitle}({manvolnum})`',
+        'freebsd': f':freebsd:`{refentrytitle}({manvolnum})`',
+        'dbus': f':dbus:`{refentrytitle}({manvolnum})`',
+    }
+
+    if project in extlink_formats:
+        return extlink_formats[project]
+
+    if project == 'url':
+        url = el.get("url")
+        return f"`{refentrytitle}({manvolnum}) <{url}>`_"
+
+    return f":ref:`{refentrytitle}({manvolnum})`"
+
+
+def refmeta(el):
+    refentrytitle = el.find('refentrytitle').text
+    manvolnum = el.find('manvolnum').text
+
+    meta_title = f":title: {refentrytitle}"
+
+    meta_manvolnum = f":manvolnum: {manvolnum}"
+
+    doc_title = ".. _%s:" % _join_children(
+        el, '') + '\n\n' + _make_title(_join_children(el, ''), 1)
+
+    return '\n\n'.join([meta_title, meta_manvolnum, doc_title])
+
+
+def refentrytitle(el):
+    if el.get("url"):
+        return ulink(el)
+    else:
+        return _concat(el)
+
+
+def manvolnum(el):
+    return "(%s)" % el.text
+
+# media objects
+
+
+def imageobject(el):
+    return _indent(el, 3, ".. image:: ", True)
+
+
+def imagedata(el):
+    _has_no_text(el)
+    return el.get("fileref")
+
+
+def videoobject(el):
+    return _indent(el, 3, ".. raw:: html\n\n", True)
+
+
+def videodata(el):
+    _has_no_text(el)
+    src = el.get("fileref")
+    return '    <video src="%s" controls>\n' % src + \
+        '      Your browser does not support the <code>video</code> element.\n' + \
+        '    </video>'
+
+
+def programlisting(el):
+    xi_include = el.find('.//{http://www.w3.org/2001/XInclude}include')
+    if xi_include is not None:
+        return _includes(xi_include)
+    else:
+        return f"\n\n.. code-block:: sh\n\n   \n\n{_indent(el, 3)}\n\n"
+
+
+def screen(el):
+    return _indent(el, 3, "::\n\n", False) + "\n\n"
+
+
+def synopsis(el):
+    return _indent(el, 3, "::\n\n", False) + "\n\n"
+
+def funcsynopsis(el):
+    return _concat(el)
+
+def funcsynopsisinfo(el):
+    return "``%s``" % _concat(el)
+
+def funcprototype(el):
+    funcdef = ''.join(el.find('.//funcdef').itertext())
+    params = el.findall('.//paramdef')
+    param_list = [''.join(param.itertext()) for param in params]
+    s = ".. code-block:: \n\n   "
+    s += f"{funcdef}("
+    s += ",\n\t".join(param_list)
+    s += ");"
+    return s
+
+def paramdef(el):
+    return el
+
+def funcdef(el):
+    return el
+
+def function(el):
+    return _concat(el).strip()
+
+def parameter(el):
+    return el
+
+
+def userinput(el):
+    return _indent(el, 3, "\n\n")
+
+
+def computeroutput(el):
+    return _indent(el, 3, "\n\n")
+
+
+# miscellaneous
+def keycombo(el):
+    return _join_children(el, ' + ')
+
+
+def keycap(el):
+    return ":kbd:`%s`" % el.text
+
+
+def warning(el):
+    return ".. warning::`%s`" % el.text
+
+
+def para(el):
+    return _block_separated_with_blank_line(el) + '\n\n \n\n'
+
+
+def simpara(el):
+    return _block_separated_with_blank_line(el)
+
+
+def important(el):
+    return _indent(el, 3, ".. note:: ", True)
+
+
+def itemizedlist(el):
+    return _indent(el, 2, "* ", True)
+
+
+def orderedlist(el):
+    return _indent(el, 2, "1. ", True)
+
+
+def refsect1(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect2(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect3(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect4(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect5(el):
+    return _block_separated_with_blank_line(el)
+
+
+def convert_xml_to_rst(xml_file_path, output_dir):
+    try:
+        _run(xml_file_path, output_dir)
+        return list(_not_handled_tags), ''
+    except Exception as e:
+        _warn('Failed to convert file %s' % xml_file_path)
+        return [], str(e)

doc-migration/main.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+
+import os
+import json
+import argparse
+from typing import List
+from db2rst import convert_xml_to_rst
+
+FILES_USED_FOR_INCLUDES = [
+    'sd_journal_get_data.xml', 'standard-options.xml', 'user-system-options.xml',
+    'common-variables.xml', 'standard-conf.xml', 'libsystemd-pkgconfig.xml', 'threads-aware.xml'
+]
+
+INCLUDES_DIR = "includes"
+
+
+def load_files_from_json(json_path: str) -> List[str]:
+    """
+    Loads a list of filenames from a JSON file.
+
+    Parameters:
+    json_path (str): Path to the JSON file.
+
+    Returns:
+    List[str]: List of filenames.
+    """
+    if not os.path.isfile(json_path):
+        print(f"Error: The file '{json_path}' does not exist.")
+        return []
+
+    with open(json_path, 'r') as json_file:
+        data = json.load(json_file)
+
+    return [entry['file'] for entry in data]
+
+
+def update_json_file(json_path: str, updated_entries: List[dict]) -> None:
+    """
+    Updates a JSON file with new entries.
+
+    Parameters:
+    json_path (str): Path to the JSON file.
+    updated_entries (List[dict]): List of updated entries to write to the JSON file.
+    """
+    with open(json_path, 'w') as json_file:
+        json.dump(updated_entries, json_file, indent=4)
+
+
+def process_xml_files_in_directory(dir: str, output_dir: str, specific_file: str = None, errored: bool = False, unhandled_only: bool = False) -> None:
+    """
+    Processes all XML files in a specified directory, logs results to a JSON file.
+
+    Parameters:
+    dir (str): Path to the directory containing XML files.
+    output_dir (str): Path to the JSON file for logging results.
+    specific_file (str, optional): Specific XML file to process. Defaults to None.
+    errored (bool, optional): Flag to process only files listed in errors.json. Defaults to False.
+    unhandled_only (bool, optional): Flag to process only files listed in successes_with_unhandled_tags.json. Defaults to False.
+    """
+    files_output_dir = os.path.join(output_dir, "files")
+    includes_output_dir = os.path.join(output_dir, INCLUDES_DIR)
+    os.makedirs(files_output_dir, exist_ok=True)
+    os.makedirs(includes_output_dir, exist_ok=True)
+
+    files_to_process = []
+
+    if errored:
+        errors_json_path = os.path.join(output_dir, "errors.json")
+        files_to_process = load_files_from_json(errors_json_path)
+        if not files_to_process:
+            print("No files to process from errors.json. Exiting.")
+            return
+    elif unhandled_only:
+        unhandled_json_path = os.path.join(
+            output_dir, "successes_with_unhandled_tags.json")
+        files_to_process = load_files_from_json(unhandled_json_path)
+        if not files_to_process:
+            print("No files to process from successes_with_unhandled_tags.json. Exiting.")
+            return
+    elif specific_file:
+        specific_file_path = os.path.join(dir, specific_file)
+        if os.path.isfile(specific_file_path):
+            files_to_process = [specific_file]
+        else:
+            print(f"Error: The file '{
+                  specific_file}' does not exist in the directory '{dir}'.")
+            return
+    else:
+        files_to_process = [f for f in os.listdir(dir) if f.endswith(".xml")]
+
+    errors_json_path = os.path.join(output_dir, "errors.json")
+    unhandled_json_path = os.path.join(
+        output_dir, "successes_with_unhandled_tags.json")
+
+    existing_errors = []
+    existing_unhandled = []
+
+    if os.path.exists(errors_json_path):
+        with open(errors_json_path, 'r') as json_file:
+            existing_errors = json.load(json_file)
+
+    if os.path.exists(unhandled_json_path):
+        with open(unhandled_json_path, 'r') as json_file:
+            existing_unhandled = json.load(json_file)
+
+    updated_errors = []
+    updated_successes_with_unhandled_tags = []
+
+    for filename in files_to_process:
+        filepath = os.path.join(dir, filename)
+        output_subdir = includes_output_dir if filename in FILES_USED_FOR_INCLUDES else files_output_dir
+        print('converting file: ', filename)
+        try:
+            unhandled_tags, error = convert_xml_to_rst(filepath, output_subdir)
+            if error:
+                result = {
+                    "file": filename,
+                    "status": "error",
+                    "unhandled_tags": unhandled_tags,
+                    "error": error
+                }
+                updated_errors.append(result)
+            else:
+                result = {
+                    "file": filename,
+                    "status": "success",
+                    "unhandled_tags": unhandled_tags,
+                    "error": error
+                }
+                if len(unhandled_tags) > 0:
+                    updated_successes_with_unhandled_tags.append(result)
+
+            existing_errors = [
+                entry for entry in existing_errors if entry['file'] != filename]
+            existing_unhandled = [
+                entry for entry in existing_unhandled if entry['file'] != filename]
+
+        except Exception as e:
+            result = {
+                "file": filename,
+                "status": "error",
+                "unhandled_tags": [],
+                "error": str(e)
+            }
+            updated_errors.append(result)
+
+    if not errored:
+        updated_errors += existing_errors
+
+    if not unhandled_only:
+        updated_successes_with_unhandled_tags += existing_unhandled
+
+    update_json_file(errors_json_path, updated_errors)
+    update_json_file(unhandled_json_path,
+                     updated_successes_with_unhandled_tags)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Process XML files and save results to a directory.")
+    parser.add_argument(
+        "--dir", type=str, help="Path to the directory containing XML files.", default="../man")
+    parser.add_argument(
+        "--output", type=str, help="Path to the output directory for results and log files.", default="in-progress")
+    parser.add_argument(
+        "--file", type=str, help="If provided, the script will only process the specified file.", default=None)
+    parser.add_argument("--errored", action='store_true',
+                        help="Process only files listed in errors.json.")
+    parser.add_argument("--unhandled-only", action='store_true',
+                        help="Process only files listed in successes_with_unhandled_tags.json.")
+
+    args = parser.parse_args()
+
+    process_xml_files_in_directory(
+        args.dir, args.output, args.file, args.errored, args.unhandled_only)
+
+
+if __name__ == "__main__":
+    main()

doc-migration/source/_ext/autogen_index.py

@@ -0,0 +1,63 @@
+import os
+from sphinx.application import Sphinx
+from sphinx.util.console import bold
+from sphinx.util.typing import ExtensionMetadata
+
+
+def generate_toctree(app: Sphinx):
+    root_dir = app.srcdir
+
+    index_path = os.path.join(root_dir, 'index.rst')
+    if not os.path.exists(index_path):
+        app.logger.warning(
+            f"{index_path} does not exist, skipping generation.")
+        return
+
+    with open(index_path, 'w') as index_file:
+        index_file.write(""".. SPDX-License-Identifier: LGPL-2.1-or-later
+.. systemd documentation master file, created by
+   sphinx-quickstart on Wed Jun 26 16:24:13 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+systemd — System and Service Manager
+===================================
+
+.. manual reference to a doc by its reference label
+   see: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
+.. Manual links
+.. ------------
+.. :ref:`busctl(1)`
+.. :ref:`systemd(1)`
+.. OR using the toctree to pull in files
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+.. This only works if we restructure our headings to match
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+   and then only have single top-level heading with the command name
+
+.. toctree::
+   :maxdepth: 1\n
+""")
+
+        for subdir, _, files in os.walk(root_dir + '/docs'):
+            if subdir == root_dir:
+                continue
+            for file in files:
+                if file.endswith('.rst'):
+                    file_path = os.path.relpath(
+                        os.path.join(subdir, file), root_dir)
+                    # remove the .rst extension
+                    index_file.write(f"   {file_path[:-4]}\n")
+
+        index_file.write("""
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search` """)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.connect('builder-inited', generate_toctree)
+    return {'version': '0.1', 'parallel_read_safe': True, 'parallel_write_safe': True, }

doc-migration/source/_ext/directive_roles.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+from __future__ import annotations
+from typing import List, Dict, Any
+from docutils import nodes
+
+from sphinx.locale import _
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxRole, SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
+
+
+class directive_list(nodes.General, nodes.Element):
+    pass
+
+
+class InlineDirectiveRole(SphinxRole):
+    def run(self) -> tuple[List[nodes.Node], List[nodes.system_message]]:
+        target_id = f'directive-{self.env.new_serialno("directive")}-{
+            self.text}'
+
+        target_node = nodes.target('', self.text, ids=[target_id])
+
+        if not hasattr(self.env, 'directives'):
+            self.env.directives = []
+
+        self.env.directives.append({
+            'name': self.name,
+            'text': self.text,
+            'docname': self.env.docname,
+            'lineno': self.lineno,
+            'target_id': target_id,
+        })
+
+        return [target_node], []
+
+
+class ListDirectiveRoles(SphinxDirective):
+    def run(self) -> List[nodes.Node]:
+        return [directive_list('')]
+
+
+def register_directive_roles(app: Sphinx) -> None:
+    directives_data: List[Dict[str, Any]] = app.config.directives_data
+    role_types: List[str] = app.config.role_types
+
+    for directive in directives_data:
+        dir_id: str = directive['id']
+        for role_type in role_types:
+            role_name = f'directive:{dir_id}:{role_type}'
+            app.add_role(role_name, InlineDirectiveRole())
+
+
+def get_directive_metadata(app: Sphinx) -> Dict[str, Dict[str, Any]]:
+    directives_data: List[Dict[str, Any]] = app.config.directives_data
+    return {directive['id']: directive for directive in directives_data}
+
+
+def group_directives_by_id(env) -> Dict[str, List[Dict[str, Any]]]:
+    grouped_directives: Dict[str, List[Dict[str, Any]]] = {}
+    for dir_info in getattr(env, 'directives', []):
+        dir_id = dir_info['name'].split(':')[1]
+        if dir_id not in grouped_directives:
+            grouped_directives[dir_id] = []
+        grouped_directives[dir_id].append(dir_info)
+    return grouped_directives
+
+
+def create_reference_node(app: Sphinx, dir_info: Dict[str, Any], from_doc_name: str) -> nodes.reference:
+    ref_node = nodes.reference('', '')
+    ref_node['refdocname'] = dir_info['docname']
+    ref_node['refuri'] = app.builder.get_relative_uri(
+        from_doc_name, dir_info['docname']) + '#' + dir_info['target_id']
+
+    metadata: Dict[str, Any] = app.builder.env.metadata.get(
+        dir_info['docname'], {})
+    title: str = metadata.get('title', 'Unknown Title')
+    manvolnum: str = metadata.get('manvolnum', 'Unknown Volume')
+
+    ref_node.append(nodes.Text(f'{title}({manvolnum})'))
+    return ref_node
+
+
+def render_reference_node(references: List[nodes.reference]) -> nodes.paragraph:
+    para = nodes.inline()
+
+    for i, ref_node in enumerate(references):
+        para += ref_node
+        if i < len(references) - 1:
+            para += nodes.Text(", ")
+
+    return para
+
+
+def render_option(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def render_variable(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def render_constant(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def process_items(app: Sphinx, doctree: nodes.document, from_doc_name: str) -> None:
+    env = app.builder.env
+    directive_lookup: Dict[str, Dict[str, Any]] = get_directive_metadata(app)
+    grouped_directives: Dict[str, List[Dict[str, Any]]
+                             ] = group_directives_by_id(env)
+
+    render_map = {
+        'option': render_option,
+        'var': render_variable,
+        'constant': render_constant,
+    }
+
+    for node in doctree.findall(directive_list):
+        content: List[nodes.section] = []
+
+        for dir_id, directives in grouped_directives.items():
+            directive_meta = directive_lookup.get(
+                dir_id, {'title': 'Unknown', 'description': 'No description available.'})
+            section = nodes.section(ids=[dir_id])
+            section += nodes.title(text=directive_meta['title'])
+            section += nodes.paragraph(text=directive_meta['description'])
+
+            directive_references: Dict[str, List[nodes.reference]] = {}
+
+            for dir_info in directives:
+                directive_text: str = dir_info['text']
+                role_type: str = dir_info['name'].split(':')[-1]
+
+                if directive_text not in directive_references:
+                    directive_references[directive_text] = []
+
+                ref_node = create_reference_node(app, dir_info, from_doc_name)
+                directive_references[directive_text].append(ref_node)
+
+            for directive_text, references in directive_references.items():
+                render_fn = render_map.get(role_type, render_option)
+                rendered_section = render_fn(directive_text, references)
+                section += rendered_section
+
+            content.append(section)
+        node.replace_self(content)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('directives_data', [], 'env')
+    app.add_config_value('role_types', [], 'env')
+
+    register_directive_roles(app)
+    app.add_directive('list_directive_roles', ListDirectiveRoles)
+    app.connect('doctree-resolved', process_items)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

doc-migration/source/_ext/external_man_links.py

@@ -0,0 +1,59 @@
+from typing import List, Dict, Tuple, Any
+from docutils import nodes
+from docutils.parsers.rst import roles, states
+import re
+
+# Define the extlink_formats dictionary with type annotations
+extlink_formats: Dict[str, str] = {
+    'man-pages': 'https://man7.org/linux/man-pages/man{manvolnum}/{refentrytitle}.{manvolnum}.html',
+    'die-net': 'http://linux.die.net/man/{manvolnum}/{refentrytitle}',
+    'mankier': 'https://www.mankier.com/{manvolnum}/{refentrytitle}',
+    'archlinux': 'https://man.archlinux.org/man/{refentrytitle}.{manvolnum}.en.html',
+    'debian': 'https://manpages.debian.org/unstable/{refentrytitle}/{refentrytitle}.{manvolnum}.en.html',
+    'freebsd': 'https://www.freebsd.org/cgi/man.cgi?query={refentrytitle}&sektion={manvolnum}',
+    'dbus': 'https://dbus.freedesktop.org/doc/dbus-specification.html#{refentrytitle}',
+}
+
+
+def man_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: states.Inliner,
+    options: Dict[str, Any] = {}
+) -> Tuple[List[nodes.reference], List[nodes.system_message]]:
+    # Regex to match text like 'locale(7)'
+    pattern = re.compile(r'(.+)\((\d+)\)')
+    match = pattern.match(text)
+    if not match:
+        msg = inliner.reporter.error(
+            f'Invalid man page format {text}, expected format "name(section)"',
+            nodes.literal_block(rawtext, rawtext),
+            line=lineno
+        )
+        return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+
+    refentrytitle, manvolnum = match.groups()
+
+    if name not in extlink_formats:
+        msg = inliner.reporter.error(
+            f'Unknown man page role {name}',
+            nodes.literal_block(rawtext, rawtext),
+            line=lineno
+        )
+        return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+
+    url = extlink_formats[name].format(
+        manvolnum=manvolnum, refentrytitle=refentrytitle
+    )
+    node = nodes.reference(
+        rawtext, f'{refentrytitle}({manvolnum})', refuri=url, **options
+    )
+    return [node], []
+
+
+def setup(app: Any) -> Dict[str, bool]:
+    for role in extlink_formats.keys():
+        roles.register_local_role(role, man_role)
+    return {'parallel_read_safe': True, 'parallel_write_safe': True}

doc-migration/source/_static/css/custom.css

@@ -0,0 +1,28 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+.sidebar-logo {
+  margin-inline: 0;
+}
+
+section {
+  margin-block-end: 2em;
+}
+
+/* Make right sidebar wider to accomodate long titles */
+.toc-drawer {
+  width: 100%;
+}
+
+/* Make Toc section headers bold */
+.toc-tree li a:has(+ ul) {
+  font-weight: 600;
+}
+
+.sig-name,
+.sig-prename {
+  color: var(--color-content-foreground);
+}
+
+.std.option {
+  margin-left: 2rem;
+}

doc-migration/source/_static/systemd-logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="202" height="26" viewBox="0 0 202 26" id="systemd-logo">
+    <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+    <path d="M0 0v26h10v-4H4V4h6V0zm76 0v4h6v18h-6v4h10V0z" fill="currentColor"/>
+    <path d="M113.498 14.926q-4.5-.96-4.5-3.878 0-1.079.609-1.981.621-.902 1.781-1.441 1.16-.54 2.707-.54 1.63 0 2.848.528 1.219.516 1.875 1.453.656.926.656 2.121h-3.539q0-.762-.457-1.183-.457-.434-1.394-.434-.774 0-1.243.363-.457.364-.457.938 0 .55.516.89.527.34 1.781.575 1.5.28 2.543.738 1.043.445 1.653 1.242.62.797.62 2.027 0 1.114-.667 2.004-.657.88-1.887 1.383-1.219.504-2.836.504-1.711 0-2.965-.621-1.242-.633-1.898-1.617-.645-.985-.645-2.051h3.34q.036.914.656 1.36.621.433 1.594.433.902 0 1.383-.34.492-.351.492-.937 0-.364-.223-.61-.21-.258-.773-.48-.55-.223-1.57-.446zm19.384-7.606l-5.086 14.58q-.293.831-.726 1.523-.434.703-1.266 1.195-.832.504-2.098.504-.457 0-.75-.048-.281-.046-.785-.176v-2.672q.176.02.527.02.95 0 1.418-.293.47-.293.715-.961l.352-.926-4.43-12.738h3.797l2.262 7.687 2.285-7.687zm5.884 7.606q-4.5-.96-4.5-3.878 0-1.079.61-1.981.62-.902 1.781-1.441 1.16-.54 2.707-.54 1.629 0 2.848.528 1.218.516 1.875 1.453.656.926.656 2.121h-3.539q0-.762-.457-1.183-.457-.434-1.395-.434-.773 0-1.242.363-.457.364-.457.938 0 .55.516.89.527.34 1.781.575 1.5.28 2.543.738 1.043.445 1.652 1.242.621.797.621 2.027 0 1.114-.668 2.004-.656.88-1.886 1.383-1.219.504-2.836.504-1.711 0-2.965-.621-1.242-.633-1.899-1.617-.644-.985-.644-2.051h3.34q.036.914.656 1.36.621.433 1.594.433.902 0 1.383-.34.492-.351.492-.937 0-.364-.223-.61-.21-.258-.773-.48-.551-.223-1.57-.446zm13.983 2.403q.574 0 .984-.082v2.66q-.914.328-2.086.328-3.727 0-3.727-3.797V9.899h-1.793V7.321h1.793v-3.14h3.54v3.14h2.132v2.578h-2.133v6.129q0 .75.293 1.031.293.27.997.27zm14.228-2.519h-8.016q.2 1.183.985 1.886.785.691 2.015.691.914 0 1.688-.34.785-.351 1.336-1.042l1.699 1.957q-.668.96-1.957 1.617-1.278.656-3 .656-1.946 0-3.387-.82-1.43-.82-2.203-2.227-.762-1.406-.762-3.105v-.446q0-1.898.715-3.386.715-1.489 2.063-2.32 1.347-.844 3.187-.844 1.793 0 3.059.761 1.265.762 1.922 2.168.656 1.395.656 3.293zm-3.469-2.65q-.024-1.03-.574-1.628-.54-.598-1.617-.598-1.008 0-1.582.668-.563.668-.739 1.84h4.512zm19.923-5.073q1.934 0 2.989 1.148 1.054 1.148 1.054 3.727v8.039h-3.539V11.95q0-.797-.21-1.23-.212-.446-.61-.61-.387-.164-.984-.164-.715 0-1.219.352-.504.34-.797.972.02.082.02.27V20h-3.54v-8.015q0-.797-.21-1.242-.211-.445-.61-.621-.386-.176-.996-.176-.68 0-1.183.304-.492.293-.797.844V20h-3.539V7.32h3.316l.118 1.419q.633-.797 1.547-1.22.926-.433 2.086-.433 1.172 0 2.016.48.855.47 1.312 1.442.633-.926 1.582-1.418.961-.504 2.203-.504zM201.398 2v18h-3.187l-.176-1.359q-1.243 1.594-3.212 1.594-1.535 0-2.66-.82-1.113-.832-1.699-2.285-.574-1.454-.574-3.317v-.246q0-1.934.574-3.398.586-1.465 1.7-2.274 1.124-.808 2.683-.808 1.805 0 3.012 1.37V2.001zm-5.672 15.376q1.488 0 2.133-1.266v-4.898q-.61-1.266-2.11-1.266-1.207 0-1.77.984-.55.985-.55 2.637v.246q0 1.629.54 2.602.55.96 1.757.96z" fill="currentColor"/>
+    <path d="M45 13L63 3v20z" fill="#30d475"/>
+    <circle cx="30" cy="13" r="9" fill="#30d475"/>
+</svg>

doc-migration/source/code-examples/c/event-quick-child.c

@@ -0,0 +1,43 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <assert.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <systemd/sd-event.h>
+
+int main(int argc, char **argv) {
+  pid_t pid = fork();
+  assert(pid >= 0);
+
+  /* SIGCHLD signal must be blocked for sd_event_add_child to work */
+  sigset_t ss;
+  sigemptyset(&ss);
+  sigaddset(&ss, SIGCHLD);
+  sigprocmask(SIG_BLOCK, &ss, NULL);
+
+  if (pid == 0)  /* child */
+    sleep(1);
+
+  else {         /* parent */
+    sd_event *e = NULL;
+    int r;
+
+    /* Create the default event loop */
+    sd_event_default(&e);
+    assert(e);
+
+    /* We create a floating child event source (attached to 'e').
+     * The default handler will be called with 666 as userdata, which
+     * will become the exit value of the loop. */
+    r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);
+    assert(r >= 0);
+
+    r = sd_event_loop(e);
+    assert(r == 666);
+
+    sd_event_unref(e);
+  }
+
+  return 0;
+}

doc-migration/source/code-examples/c/glib-event-glue.c

@@ -0,0 +1,48 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdlib.h>
+#include <glib.h>
+#include <systemd/sd-event.h>
+
+typedef struct SDEventSource {
+  GSource source;
+  GPollFD pollfd;
+  sd_event *event;
+} SDEventSource;
+
+static gboolean event_prepare(GSource *source, gint *timeout_) {
+  return sd_event_prepare(((SDEventSource *)source)->event) > 0;
+}
+
+static gboolean event_check(GSource *source) {
+  return sd_event_wait(((SDEventSource *)source)->event, 0) > 0;
+}
+
+static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) {
+  return sd_event_dispatch(((SDEventSource *)source)->event) > 0;
+}
+
+static void event_finalize(GSource *source) {
+  sd_event_unref(((SDEventSource *)source)->event);
+}
+
+static GSourceFuncs event_funcs = {
+  .prepare = event_prepare,
+  .check = event_check,
+  .dispatch = event_dispatch,
+  .finalize = event_finalize,
+};
+
+GSource *g_sd_event_create_source(sd_event *event) {
+  SDEventSource *source;
+
+  source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource));
+
+  source->event = sd_event_ref(event);
+  source->pollfd.fd = sd_event_get_fd(event);
+  source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR;
+
+  g_source_add_poll((GSource *)source, &source->pollfd);
+
+  return (GSource *)source;
+}

doc-migration/source/code-examples/c/hwdb-usb-device.c

@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <stdio.h>
+#include <stdint.h>
+#include <systemd/sd-hwdb.h>
+
+int print_usb_properties(uint16_t vid, uint16_t pid) {
+  char match[128];
+  sd_hwdb *hwdb;
+  const char *key, *value;
+  int r;
+
+  /* Match this USB vendor and product ID combination */
+  snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
+
+  r = sd_hwdb_new(&hwdb);
+  if (r < 0)
+    return r;
+
+  SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
+    printf("%s: \"%s\" → \"%s\"\n", match, key, value);
+
+  sd_hwdb_unref(hwdb);
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  print_usb_properties(0x046D, 0xC534);
+  return 0;
+}

doc-migration/source/code-examples/c/id128-app-specific.c

@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <systemd/sd-id128.h>
+
+#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
+
+int main(int argc, char *argv[]) {
+  sd_id128_t id;
+  sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
+  printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id));
+  return 0;
+}

doc-migration/source/code-examples/c/inotify-watch-tmp.c

@@ -0,0 +1,58 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <string.h>
+#include <sys/inotify.h>
+
+#include <systemd/sd-event.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static int inotify_handler(sd_event_source *source,
+                           const struct inotify_event *event,
+                           void *userdata) {
+
+  const char *desc = NULL;
+
+  sd_event_source_get_description(source, &desc);
+
+  if (event->mask & IN_Q_OVERFLOW)
+    printf("inotify-handler <%s>: overflow\n", desc);
+  else if (event->mask & IN_CREATE)
+    printf("inotify-handler <%s>: create on %s\n", desc, event->name);
+  else if (event->mask & IN_DELETE)
+    printf("inotify-handler <%s>: delete on %s\n", desc, event->name);
+  else if (event->mask & IN_MOVED_TO)
+    printf("inotify-handler <%s>: moved-to on %s\n", desc, event->name);
+
+  /* Terminate the program if an "exit" file appears */
+  if ((event->mask & (IN_CREATE|IN_MOVED_TO)) &&
+      strcmp(event->name, "exit") == 0)
+    sd_event_exit(sd_event_source_get_event(source), 0);
+
+  return 1;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_event_unrefp) sd_event *event = NULL;
+  _cleanup_(sd_event_source_unrefp) sd_event_source *source1 = NULL, *source2 = NULL;
+
+  const char *path1 = argc > 1 ? argv[1] : "/tmp";
+  const char *path2 = argc > 2 ? argv[2] : NULL;
+
+  /* Note: failure handling is omitted for brevity */
+
+  sd_event_default(&event);
+
+  sd_event_add_inotify(event, &source1, path1,
+                       IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
+                       inotify_handler, NULL);
+  if (path2)
+    sd_event_add_inotify(event, &source2, path2,
+                         IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
+                         inotify_handler, NULL);
+
+  sd_event_loop(event);
+
+  return 0;
+}

doc-migration/source/code-examples/c/journal-enumerate-fields.c

@@ -0,0 +1,21 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  sd_journal *j;
+  const char *field;
+  int r;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH_FIELD(j, field)
+    printf("%s\n", field);
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-foreach.c

@@ -0,0 +1,30 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  int r;
+  sd_journal *j;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH(j) {
+    const char *d;
+    size_t l;
+
+    r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l);
+    if (r < 0) {
+      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
+      continue;
+    }
+
+    printf("%.*s\n", (int) l, d);
+  }
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-poll.c

@@ -0,0 +1,28 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <poll.h>
+#include <time.h>
+#include <systemd/sd-journal.h>
+
+int wait_for_changes(sd_journal *j) {
+  uint64_t t;
+  int msec;
+  struct pollfd pollfd;
+
+  sd_journal_get_timeout(j, &t);
+  if (t == (uint64_t) -1)
+    msec = -1;
+  else {
+    struct timespec ts;
+    uint64_t n;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
+    msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
+  }
+
+  pollfd.fd = sd_journal_get_fd(j);
+  pollfd.events = sd_journal_get_events(j);
+  poll(&pollfd, 1, msec);
+  return sd_journal_process(j);
+}

doc-migration/source/code-examples/c/journal-iterate-unique.c

@@ -0,0 +1,27 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  sd_journal *j;
+  const void *d;
+  size_t l;
+  int r;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
+  if (r < 0) {
+    fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
+    printf("%.*s\n", (int) l, (const char*) d);
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-wait.c

@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  int r;
+  sd_journal *j;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+
+  for (;;)  {
+    const void *d;
+    size_t l;
+    r = sd_journal_next(j);
+    if (r < 0) {
+      fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
+      break;
+    }
+    if (r == 0) {
+      /* Reached the end, let's wait for changes, and try again */
+      r = sd_journal_wait(j, (uint64_t) -1);
+      if (r < 0) {
+        fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
+        break;
+      }
+      continue;
+    }
+    r = sd_journal_get_data(j, "MESSAGE", &d, &l);
+    if (r < 0) {
+      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
+      continue;
+    }
+    printf("%.*s\n", (int) l, (const char*) d);
+  }
+
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-stream-fd.c

@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <syslog.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <systemd/sd-journal.h>
+#include <systemd/sd-daemon.h>
+
+int main(int argc, char *argv[]) {
+  int fd;
+  FILE *log;
+
+  fd = sd_journal_stream_fd("test", LOG_INFO, 1);
+  if (fd < 0) {
+    fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd));
+    return 1;
+  }
+
+  log = fdopen(fd, "w");
+  if (!log) {
+    fprintf(stderr, "Failed to create file object: %s\n", strerror(errno));
+    close(fd);
+    return 1;
+  }
+  fprintf(log, "Hello World!\n");
+  fprintf(log, SD_WARNING "This is a warning!\n");
+  fclose(log);
+  return 0;
+}

doc-migration/source/code-examples/c/logcontrol-example.c

@@ -0,0 +1,251 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* Implements the LogControl1 interface as per specification:
+ * https://www.freedesktop.org/software/systemd/man/org.freedesktop.LogControl1.html
+ *
+ * Compile with 'cc logcontrol-example.c $(pkg-config --libs --cflags libsystemd)'
+ *
+ * To get and set properties via busctl:
+ *
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              SyslogIdentifier
+ *   s "example"
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogTarget
+ *   s "journal"
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel
+ *   s "info"
+ * $ busctl --user set-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel \
+ *                              "s" debug
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel
+ *   s "debug"
+ */
+
+#include <errno.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <syslog.h>
+#include <systemd/sd-bus.h>
+#include <systemd/sd-journal.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static int log_error(int log_level, int error, const char *str) {
+  sd_journal_print(log_level, "%s failed: %s", str, strerror(-error));
+  return error;
+}
+
+typedef enum LogTarget {
+  LOG_TARGET_JOURNAL,
+  LOG_TARGET_KMSG,
+  LOG_TARGET_SYSLOG,
+  LOG_TARGET_CONSOLE,
+  _LOG_TARGET_MAX,
+} LogTarget;
+
+static const char* const log_target_table[_LOG_TARGET_MAX] = {
+  [LOG_TARGET_JOURNAL] = "journal",
+  [LOG_TARGET_KMSG]    = "kmsg",
+  [LOG_TARGET_SYSLOG]  = "syslog",
+  [LOG_TARGET_CONSOLE] = "console",
+};
+
+static const char* const log_level_table[LOG_DEBUG + 1] = {
+  [LOG_EMERG]   = "emerg",
+  [LOG_ALERT]   = "alert",
+  [LOG_CRIT]    = "crit",
+  [LOG_ERR]     = "err",
+  [LOG_WARNING] = "warning",
+  [LOG_NOTICE]  = "notice",
+  [LOG_INFO]    = "info",
+  [LOG_DEBUG]   = "debug",
+};
+
+typedef struct object {
+  const char *syslog_identifier;
+  LogTarget log_target;
+  int log_level;
+} object;
+
+static int property_get(
+                sd_bus *bus,
+                const char *path,
+                const char *interface,
+                const char *property,
+                sd_bus_message *reply,
+                void *userdata,
+                sd_bus_error *error) {
+
+  object *o = userdata;
+
+  if (strcmp(property, "LogLevel") == 0)
+    return sd_bus_message_append(reply, "s", log_level_table[o->log_level]);
+
+  if (strcmp(property, "LogTarget") == 0)
+    return sd_bus_message_append(reply, "s", log_target_table[o->log_target]);
+
+  if (strcmp(property, "SyslogIdentifier") == 0)
+    return sd_bus_message_append(reply, "s", o->syslog_identifier);
+
+  return sd_bus_error_setf(error,
+                           SD_BUS_ERROR_UNKNOWN_PROPERTY,
+                           "Unknown property '%s'",
+                           property);
+}
+
+static int property_set(
+                sd_bus *bus,
+                const char *path,
+                const char *interface,
+                const char *property,
+                sd_bus_message *message,
+                void *userdata,
+                sd_bus_error *error) {
+
+  object *o = userdata;
+  const char *value;
+  int r;
+
+  r = sd_bus_message_read(message, "s", &value);
+  if (r < 0)
+    return r;
+
+  if (strcmp(property, "LogLevel") == 0) {
+    int i;
+    for (i = 0; i < LOG_DEBUG + 1; i++)
+      if (strcmp(value, log_level_table[i]) == 0) {
+        o->log_level = i;
+        setlogmask(LOG_UPTO(i));
+        return 0;
+      }
+
+    return sd_bus_error_setf(error,
+                             SD_BUS_ERROR_INVALID_ARGS,
+                             "Invalid value for LogLevel: '%s'",
+                             value);
+  }
+
+  if (strcmp(property, "LogTarget") == 0) {
+    LogTarget i;
+    for (i = 0; i < _LOG_TARGET_MAX; i++)
+      if (strcmp(value, log_target_table[i]) == 0) {
+        o->log_target = i;
+        return 0;
+      }
+
+    return sd_bus_error_setf(error,
+                             SD_BUS_ERROR_INVALID_ARGS,
+                             "Invalid value for LogTarget: '%s'",
+                             value);
+  }
+
+  return sd_bus_error_setf(error,
+                           SD_BUS_ERROR_UNKNOWN_PROPERTY,
+                           "Unknown property '%s'",
+                           property);
+}
+
+/* https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html
+ */
+static const sd_bus_vtable vtable[] = {
+  SD_BUS_VTABLE_START(0),
+  SD_BUS_WRITABLE_PROPERTY(
+    "LogLevel", "s",
+    property_get, property_set,
+    0,
+    0),
+  SD_BUS_WRITABLE_PROPERTY(
+    "LogTarget", "s",
+    property_get, property_set,
+    0,
+    0),
+  SD_BUS_PROPERTY(
+    "SyslogIdentifier", "s",
+    property_get,
+    0,
+    SD_BUS_VTABLE_PROPERTY_CONST),
+  SD_BUS_VTABLE_END
+};
+
+int main(int argc, char **argv) {
+  /* The bus should be relinquished before the program terminates. The cleanup
+   * attribute allows us to do it nicely and cleanly whenever we exit the
+   * block.
+   */
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+
+  object o = {
+    .log_level = LOG_INFO,
+    .log_target = LOG_TARGET_JOURNAL,
+    .syslog_identifier = "example",
+  };
+  int r;
+
+  /* https://man7.org/linux/man-pages/man3/setlogmask.3.html
+   * Programs using syslog() instead of sd_journal can use this API to cut logs
+   * emission at the source.
+   */
+  setlogmask(LOG_UPTO(o.log_level));
+
+  /* Acquire a connection to the bus, letting the library work out the details.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_default.html
+   */
+  r = sd_bus_default(&bus);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_default()");
+
+  /* Publish an interface on the bus, specifying our well-known object access
+   * path and public interface name.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html
+   * https://dbus.freedesktop.org/doc/dbus-tutorial.html
+   */
+  r = sd_bus_add_object_vtable(bus, NULL,
+                               "/org/freedesktop/LogControl1",
+                               "org.freedesktop.LogControl1",
+                               vtable,
+                               &o);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_add_object_vtable()");
+
+  /* By default the service is assigned an ephemeral name. Also add a fixed
+   * one, so that clients know whom to call.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html
+   */
+  r = sd_bus_request_name(bus, "org.freedesktop.Example", 0);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_request_name()");
+
+  for (;;) {
+    /* https://www.freedesktop.org/software/systemd/man/sd_bus_wait.html
+     */
+    r = sd_bus_wait(bus, UINT64_MAX);
+    if (r < 0)
+      return log_error(o.log_level, r, "sd_bus_wait()");
+    /* https://www.freedesktop.org/software/systemd/man/sd_bus_process.html
+     */
+    r = sd_bus_process(bus, NULL);
+    if (r < 0)
+      return log_error(o.log_level, r, "sd_bus_process()");
+  }
+
+  /* https://www.freedesktop.org/software/systemd/man/sd_bus_release_name.html
+   */
+  r = sd_bus_release_name(bus, "org.freedesktop.Example");
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_release_name()");
+
+  return 0;
+}

doc-migration/source/code-examples/c/notify-selfcontained-example.c

@@ -0,0 +1,188 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* Implement the systemd notify protocol without external dependencies.
+ * Supports both readiness notification on startup and on reloading,
+ * according to the protocol defined at:
+ * https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+ * This protocol is guaranteed to be stable as per:
+ * https://systemd.io/PORTABILITY_AND_STABILITY/ */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <inttypes.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <time.h>
+#include <unistd.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static void closep(int *fd) {
+  if (!fd || *fd < 0)
+    return;
+
+  close(*fd);
+  *fd = -1;
+}
+
+static int notify(const char *message) {
+  union sockaddr_union {
+    struct sockaddr sa;
+    struct sockaddr_un sun;
+  } socket_addr = {
+    .sun.sun_family = AF_UNIX,
+  };
+  size_t path_length, message_length;
+  _cleanup_(closep) int fd = -1;
+  const char *socket_path;
+
+  /* Verify the argument first */
+  if (!message)
+    return -EINVAL;
+
+  message_length = strlen(message);
+  if (message_length == 0)
+    return -EINVAL;
+
+  /* If the variable is not set, the protocol is a noop */
+  socket_path = getenv("NOTIFY_SOCKET");
+  if (!socket_path)
+    return 0; /* Not set? Nothing to do */
+
+  /* Only AF_UNIX is supported, with path or abstract sockets */
+  if (socket_path[0] != '/' && socket_path[0] != '@')
+    return -EAFNOSUPPORT;
+
+  path_length = strlen(socket_path);
+  /* Ensure there is room for NUL byte */
+  if (path_length >= sizeof(socket_addr.sun.sun_path))
+    return -E2BIG;
+
+  memcpy(socket_addr.sun.sun_path, socket_path, path_length);
+
+  /* Support for abstract socket */
+  if (socket_addr.sun.sun_path[0] == '@')
+    socket_addr.sun.sun_path[0] = 0;
+
+  fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0);
+  if (fd < 0)
+    return -errno;
+
+  if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0)
+    return -errno;
+
+  ssize_t written = write(fd, message, message_length);
+  if (written != (ssize_t) message_length)
+    return written < 0 ? -errno : -EPROTO;
+
+  return 1; /* Notified! */
+}
+
+static int notify_ready(void) {
+  return notify("READY=1");
+}
+
+static int notify_reloading(void) {
+  /* A buffer with length sufficient to format the maximum UINT64 value. */
+  char reload_message[sizeof("RELOADING=1\nMONOTONIC_USEC=18446744073709551615")];
+  struct timespec ts;
+  uint64_t now;
+
+  /* Notify systemd that we are reloading, including a CLOCK_MONOTONIC timestamp in usec
+   * so that the program is compatible with a Type=notify-reload service. */
+
+  if (clock_gettime(CLOCK_MONOTONIC, &ts) < 0)
+    return -errno;
+
+  if (ts.tv_sec < 0 || ts.tv_nsec < 0 ||
+      (uint64_t) ts.tv_sec > (UINT64_MAX - (ts.tv_nsec / 1000ULL)) / 1000000ULL)
+    return -EINVAL;
+
+  now = (uint64_t) ts.tv_sec * 1000000ULL + (uint64_t) ts.tv_nsec / 1000ULL;
+
+  if (snprintf(reload_message, sizeof(reload_message), "RELOADING=1\nMONOTONIC_USEC=%" PRIu64, now) < 0)
+    return -EINVAL;
+
+  return notify(reload_message);
+}
+
+static int notify_stopping(void) {
+  return notify("STOPPING=1");
+}
+
+static volatile sig_atomic_t reloading = 0;
+static volatile sig_atomic_t terminating = 0;
+
+static void signal_handler(int sig) {
+  if (sig == SIGHUP)
+    reloading = 1;
+  else if (sig == SIGINT || sig == SIGTERM)
+    terminating = 1;
+}
+
+int main(int argc, char **argv) {
+  struct sigaction sa = {
+    .sa_handler = signal_handler,
+    .sa_flags = SA_RESTART,
+  };
+  int r;
+
+  /* Setup signal handlers */
+  sigemptyset(&sa.sa_mask);
+  sigaction(SIGHUP, &sa, NULL);
+  sigaction(SIGINT, &sa, NULL);
+  sigaction(SIGTERM, &sa, NULL);
+
+  /* Do more service initialization work here … */
+
+  /* Now that all the preparations steps are done, signal readiness */
+
+  r = notify_ready();
+  if (r < 0) {
+    fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  while (!terminating) {
+    if (reloading) {
+      reloading = false;
+
+      /* As a separate but related feature, we can also notify the manager
+       * when reloading configuration. This allows accurate state-tracking,
+       * and also automated hook-in of 'systemctl reload' without having to
+       * specify manually an ExecReload= line in the unit file. */
+
+      r = notify_reloading();
+      if (r < 0) {
+        fprintf(stderr, "Failed to notify reloading to $NOTIFY_SOCKET: %s\n", strerror(-r));
+        return EXIT_FAILURE;
+      }
+
+      /* Do some reconfiguration work here … */
+
+      r = notify_ready();
+      if (r < 0) {
+        fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r));
+        return EXIT_FAILURE;
+      }
+    }
+
+    /* Do some daemon work here … */
+    sleep(5);
+  }
+
+  r = notify_stopping();
+  if (r < 0) {
+    fprintf(stderr, "Failed to report termination to $NOTIFY_SOCKET: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  /* Do some shutdown work here … */
+
+  return EXIT_SUCCESS;
+}

doc-migration/source/code-examples/c/path-documents.c

@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <systemd/sd-path.h>
+
+int main(void) {
+  int r;
+  char *t;
+
+  r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
+  if (r < 0)
+    return EXIT_FAILURE;
+
+  printf("~/Documents: %s\n", t);
+  free(t);
+
+  return EXIT_SUCCESS;
+}

doc-migration/source/code-examples/c/print-unit-path-call-method.c

@@ -0,0 +1,50 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* This is equivalent to:
+ * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
+ *       org.freedesktop.systemd1.Manager GetUnitByPID $$
+ *
+ * Compile with 'cc print-unit-path-call-method.c -lsystemd'
+ */
+
+#include <errno.h>
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+#define DESTINATION "org.freedesktop.systemd1"
+#define PATH        "/org/freedesktop/systemd1"
+#define INTERFACE   "org.freedesktop.systemd1.Manager"
+#define MEMBER      "GetUnitByPID"
+
+static int log_error(int error, const char *message) {
+  fprintf(stderr, "%s: %s\n", message, strerror(-error));
+  return error;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
+  _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL;
+  int r;
+
+  r = sd_bus_open_system(&bus);
+  if (r < 0)
+    return log_error(r, "Failed to acquire bus");
+
+  r = sd_bus_call_method(bus, DESTINATION, PATH, INTERFACE, MEMBER, &error, &reply, "u", (unsigned) getpid());
+  if (r < 0)
+    return log_error(r, MEMBER " call failed");
+
+  const char *ans;
+  r = sd_bus_message_read(reply, "o", &ans);
+  if (r < 0)
+    return log_error(r, "Failed to read reply");
+
+  printf("Unit path is \"%s\".\n", ans);
+
+  return 0;
+}

doc-migration/source/code-examples/c/print-unit-path.c

@@ -0,0 +1,59 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* This is equivalent to:
+ * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
+ *       org.freedesktop.systemd1.Manager GetUnitByPID $$
+ *
+ * Compile with 'cc print-unit-path.c -lsystemd'
+ */
+
+#include <errno.h>
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+#define DESTINATION "org.freedesktop.systemd1"
+#define PATH        "/org/freedesktop/systemd1"
+#define INTERFACE   "org.freedesktop.systemd1.Manager"
+#define MEMBER      "GetUnitByPID"
+
+static int log_error(int error, const char *message) {
+  fprintf(stderr, "%s: %s\n", message, strerror(-error));
+  return error;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
+  _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL, *m = NULL;
+  int r;
+
+  r = sd_bus_open_system(&bus);
+  if (r < 0)
+    return log_error(r, "Failed to acquire bus");
+
+  r = sd_bus_message_new_method_call(bus, &m,
+                                     DESTINATION, PATH, INTERFACE, MEMBER);
+  if (r < 0)
+    return log_error(r, "Failed to create bus message");
+
+  r = sd_bus_message_append(m, "u", (unsigned) getpid());
+  if (r < 0)
+    return log_error(r, "Failed to append to bus message");
+
+  r = sd_bus_call(bus, m, -1, &error, &reply);
+  if (r < 0)
+    return log_error(r, MEMBER " call failed");
+
+  const char *ans;
+  r = sd_bus_message_read(reply, "o", &ans);
+  if (r < 0)
+    return log_error(r, "Failed to read reply");
+
+  printf("Unit path is \"%s\".\n", ans);
+
+  return 0;
+}

doc-migration/source/code-examples/c/sd-bus-container-append.c

@@ -0,0 +1,20 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <systemd/sd-bus.h>
+
+int append_strings_to_message(sd_bus_message *m, const char *const *arr) {
+  const char *s;
+  int r;
+
+  r = sd_bus_message_open_container(m, 'a', "s");
+  if (r < 0)
+    return r;
+
+  for (s = *arr; *s; s++) {
+    r = sd_bus_message_append(m, "s", s);
+    if (r < 0)
+      return r;
+  }
+
+  return sd_bus_message_close_container(m);
+}

doc-migration/source/code-examples/c/sd-bus-container-read.c

@@ -0,0 +1,27 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+
+#include <systemd/sd-bus.h>
+
+int read_strings_from_message(sd_bus_message *m) {
+  int r;
+
+  r = sd_bus_message_enter_container(m, 'a', "s");
+  if (r < 0)
+    return r;
+
+  for (;;) {
+    const char *s;
+
+    r = sd_bus_message_read(m, "s", &s);
+    if (r < 0)
+      return r;
+    if (r == 0)
+      break;
+
+    printf("%s\n", s);
+  }
+
+  return sd_bus_message_exit_container(m);
+}

doc-migration/source/code-examples/c/sd_bus_error-example.c

@@ -0,0 +1,18 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <string.h>
+#include <unistd.h>
+#include <systemd/sd-bus.h>
+
+int writer_with_negative_errno_return(int fd, sd_bus_error *error) {
+  const char *message = "Hello, World!\n";
+
+  ssize_t n = write(fd, message, strlen(message));
+  if (n >= 0)
+    return n; /* On success, return the number of bytes written, possibly 0. */
+
+  /* On error, initialize the error structure, and also propagate the errno
+   * value that write(2) set for us. */
+  return sd_bus_error_set_errnof(error, errno, "Failed to write to fd %i: %s", fd, strerror(errno));
+}

doc-migration/source/code-examples/c/vtable-example.c

@@ -0,0 +1,143 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+typedef struct object {
+  char *name;
+  uint32_t number;
+} object;
+
+static int method(sd_bus_message *m, void *userdata, sd_bus_error *error) {
+  int r;
+
+  printf("Got called with userdata=%p\n", userdata);
+
+  if (sd_bus_message_is_method_call(m,
+                                    "org.freedesktop.systemd.VtableExample",
+                                    "Method4"))
+    return 1;
+
+  const char *string;
+  r = sd_bus_message_read(m, "s", &string);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_message_read() failed: %s\n", strerror(-r));
+    return 0;
+  }
+
+  r = sd_bus_reply_method_return(m, "s", string);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_reply_method_return() failed: %s\n", strerror(-r));
+    return 0;
+  }
+
+  return 1;
+}
+
+static const sd_bus_vtable vtable[] = {
+        SD_BUS_VTABLE_START(0),
+        SD_BUS_METHOD(
+            "Method1", "s", "s", method, 0),
+        SD_BUS_METHOD_WITH_NAMES_OFFSET(
+            "Method2",
+            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
+            "s", SD_BUS_PARAM(returnstring),
+            method, offsetof(object, number),
+            SD_BUS_VTABLE_DEPRECATED),
+        SD_BUS_METHOD_WITH_ARGS_OFFSET(
+            "Method3",
+            SD_BUS_ARGS("s", string, "o", path),
+            SD_BUS_RESULT("s", returnstring),
+            method, offsetof(object, number),
+            SD_BUS_VTABLE_UNPRIVILEGED),
+        SD_BUS_METHOD_WITH_ARGS(
+            "Method4",
+            SD_BUS_NO_ARGS,
+            SD_BUS_NO_RESULT,
+            method,
+            SD_BUS_VTABLE_UNPRIVILEGED),
+        SD_BUS_SIGNAL(
+            "Signal1",
+            "so",
+            0),
+        SD_BUS_SIGNAL_WITH_NAMES(
+            "Signal2",
+            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
+            0),
+        SD_BUS_SIGNAL_WITH_ARGS(
+            "Signal3",
+            SD_BUS_ARGS("s", string, "o", path),
+            0),
+        SD_BUS_WRITABLE_PROPERTY(
+            "AutomaticStringProperty", "s", NULL, NULL,
+            offsetof(object, name),
+            SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE),
+        SD_BUS_WRITABLE_PROPERTY(
+            "AutomaticIntegerProperty", "u", NULL, NULL,
+            offsetof(object, number),
+            SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION),
+        SD_BUS_VTABLE_END
+};
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  int r;
+
+  sd_bus_default(&bus);
+
+  object object = { .number = 666 };
+  object.name = strdup("name");
+  if (!object.name) {
+    fprintf(stderr, "OOM\n");
+    return EXIT_FAILURE;
+  }
+
+  r = sd_bus_add_object_vtable(bus, NULL,
+                               "/org/freedesktop/systemd/VtableExample",
+                               "org.freedesktop.systemd.VtableExample",
+                               vtable,
+                               &object);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_add_object_vtable() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  r = sd_bus_request_name(bus,
+                          "org.freedesktop.systemd.VtableExample",
+                          0);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_request_name() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  for (;;) {
+    r = sd_bus_wait(bus, UINT64_MAX);
+    if (r < 0) {
+      fprintf(stderr, "sd_bus_wait() failed: %s\n", strerror(-r));
+      return EXIT_FAILURE;
+    }
+
+    r = sd_bus_process(bus, NULL);
+    if (r < 0) {
+      fprintf(stderr, "sd_bus_process() failed: %s\n", strerror(-r));
+      return EXIT_FAILURE;
+    }
+  }
+
+  r = sd_bus_release_name(bus, "org.freedesktop.systemd.VtableExample");
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_release_name() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  free(object.name);
+
+  return 0;
+}

doc-migration/source/code-examples/py/90-rearrange-path.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT-0
+
+"""
+
+Proof-of-concept systemd environment generator that makes sure that bin dirs
+are always after matching sbin dirs in the path.
+(Changes /sbin:/bin:/foo/bar to /bin:/sbin:/foo/bar.)
+
+This generator shows how to override the configuration possibly created by
+earlier generators. It would be easier to write in bash, but let's have it
+in Python just to prove that we can, and to serve as a template for more
+interesting generators.
+
+"""
+
+import os
+import pathlib
+
+def rearrange_bin_sbin(path):
+    """Make sure any pair of …/bin, …/sbin directories is in this order
+
+    >>> rearrange_bin_sbin('/bin:/sbin:/usr/sbin:/usr/bin')
+    '/bin:/sbin:/usr/bin:/usr/sbin'
+    """
+    items = [pathlib.Path(p) for p in path.split(':')]
+    for i in range(len(items)):
+        if 'sbin' in items[i].parts:
+            ind = items[i].parts.index('sbin')
+            bin = pathlib.Path(*items[i].parts[:ind], 'bin', *items[i].parts[ind+1:])
+            if bin in items[i+1:]:
+                j = i + 1 + items[i+1:].index(bin)
+                items[i], items[j] = items[j], items[i]
+    return ':'.join(p.as_posix() for p in items)
+
+if __name__ == '__main__':
+    path = os.environ['PATH'] # This should be always set.
+                              # If it's not, we'll just crash, which is OK too.
+    new = rearrange_bin_sbin(path)
+    if new != path:
+        print('PATH={}'.format(new))

doc-migration/source/code-examples/py/check-os-release-simple.py

@@ -0,0 +1,12 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: MIT-0
+
+import platform
+os_release = platform.freedesktop_os_release()
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'fedora' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Fedora!')

doc-migration/source/code-examples/py/check-os-release.py

@@ -0,0 +1,37 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: MIT-0
+
+import ast
+import re
+import sys
+
+def read_os_release():
+    try:
+        filename = '/etc/os-release'
+        f = open(filename)
+    except FileNotFoundError:
+        filename = '/usr/lib/os-release'
+        f = open(filename)
+
+    for line_number, line in enumerate(f, start=1):
+        line = line.rstrip()
+        if not line or line.startswith('#'):
+            continue
+        m = re.match(r'([A-Z][A-Z_0-9]+)=(.*)', line)
+        if m:
+            name, val = m.groups()
+            if val and val[0] in '"\'':
+                val = ast.literal_eval(val)
+            yield name, val
+        else:
+            print(f'{filename}:{line_number}: bad line {line!r}',
+                  file=sys.stderr)
+
+os_release = dict(read_os_release())
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'debian' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Debian!')

doc-migration/source/code-examples/py/notify-selfcontained-example.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT-0
+#
+# Implement the systemd notify protocol without external dependencies.
+# Supports both readiness notification on startup and on reloading,
+# according to the protocol defined at:
+# https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+# This protocol is guaranteed to be stable as per:
+# https://systemd.io/PORTABILITY_AND_STABILITY/
+
+import errno
+import os
+import signal
+import socket
+import sys
+import time
+
+reloading = False
+terminating = False
+
+def notify(message):
+    if not message:
+        raise ValueError("notify() requires a message")
+
+    socket_path = os.environ.get("NOTIFY_SOCKET")
+    if not socket_path:
+        return
+
+    if socket_path[0] not in ("/", "@"):
+        raise OSError(errno.EAFNOSUPPORT, "Unsupported socket type")
+
+    # Handle abstract socket.
+    if socket_path[0] == "@":
+        socket_path = "\0" + socket_path[1:]
+
+    with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_CLOEXEC) as sock:
+        sock.connect(socket_path)
+        sock.sendall(message)
+
+def notify_ready():
+    notify(b"READY=1")
+
+def notify_reloading():
+    microsecs = time.clock_gettime_ns(time.CLOCK_MONOTONIC) // 1000
+    notify(f"RELOADING=1\nMONOTONIC_USEC={microsecs}".encode())
+
+def notify_stopping():
+    notify(b"STOPPING=1")
+
+def reload(signum, frame):
+    global reloading
+    reloading = True
+
+def terminate(signum, frame):
+    global terminating
+    terminating = True
+
+def main():
+    print("Doing initial setup")
+    global reloading, terminating
+
+    # Set up signal handlers.
+    print("Setting up signal handlers")
+    signal.signal(signal.SIGHUP, reload)
+    signal.signal(signal.SIGINT, terminate)
+    signal.signal(signal.SIGTERM, terminate)
+
+    # Do any other setup work here.
+
+    # Once all setup is done, signal readiness.
+    print("Done setting up")
+    notify_ready()
+
+    print("Starting loop")
+    while not terminating:
+        if reloading:
+            print("Reloading")
+            reloading = False
+
+            # Support notifying the manager when reloading configuration.
+            # This allows accurate state tracking as well as automatically
+            # enabling 'systemctl reload' without needing to manually
+            # specify an ExecReload= line in the unit file.
+
+            notify_reloading()
+
+            # Do some reconfiguration work here.
+
+            print("Done reloading")
+            notify_ready()
+
+        # Do the real work here ...
+
+        print("Sleeping for five seconds")
+        time.sleep(5)
+
+    print("Terminating")
+    notify_stopping()
+
+if __name__ == "__main__":
+    sys.stdout.reconfigure(line_buffering=True)
+    print("Starting app")
+    main()
+    print("Stopped app")

doc-migration/source/code-examples/sh/check-os-release.sh

@@ -0,0 +1,11 @@
+#!/bin/sh -eu
+# SPDX-License-Identifier: MIT-0
+
+test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
+. "${os_release}"
+
+echo "Running on ${PRETTY_NAME:-Linux}"
+
+if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then
+    echo "Looks like Debian!"
+fi

doc-migration/source/conf.py

@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+import os
+project = 'systemd'
+copyright = '2024, systemd'
+author = 'systemd'
+
+
+sys.path.append(os.path.abspath("./_ext"))
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinxcontrib.globalsubs',
+              'directive_roles', 'external_man_links', 'autogen_index']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+html_title = ''
+html_css_files = [
+    'css/custom.css',
+]
+html_theme_options = {
+    # TODO: update these `source`-options with the proper values
+    "source_repository": "https://github.com/neighbourhoodie/nh-systemd",
+    "source_branch": "man_pages_in_sphinx",
+    "source_directory": "doc-migration/source/",
+    "light_logo": "systemd-logo.svg",
+    "dark_logo": "systemd-logo.svg",
+    "light_css_variables": {
+        "color-brand-primary": "#35a764",
+        "color-brand-content": "#35a764",
+    },
+}
+
+
+man_pages = [
+    ('busctl', 'busctl', 'Introspect the bus', None, '1'),
+    ('journalctl', 'journalctl', 'Print log entries from the systemd journal', None, '1'),
+    ('os-release', 'os-release', 'Operating system identification', None, '5'),
+    ('systemd', 'systemd, init', 'systemd system and service manager', None, '1'),
+]
+
+global_substitutions = {f'v{n}': f'{n}' for n in range(183, 300)} | {
+    # Custom Entities
+    'MOUNT_PATH': '{{MOUNT_PATH}}',
+    'UMOUNT_PATH': '{{UMOUNT_PATH}}',
+    'SYSTEM_GENERATOR_DIR': '{{SYSTEM_GENERATOR_DIR}}',
+    'USER_GENERATOR_DIR': '{{USER_GENERATOR_DIR}}',
+    'SYSTEM_ENV_GENERATOR_DIR': '{{SYSTEM_ENV_GENERATOR_DIR}}',
+    'USER_ENV_GENERATOR_DIR': '{{USER_ENV_GENERATOR_DIR}}',
+    'CERTIFICATE_ROOT': '{{CERTIFICATE_ROOT}}',
+    'FALLBACK_HOSTNAME': '{{FALLBACK_HOSTNAME}}',
+    'MEMORY_ACCOUNTING_DEFAULT': "{{ 'yes' if MEMORY_ACCOUNTING_DEFAULT else 'no' }}",
+    'KILL_USER_PROCESSES': "{{ 'yes' if KILL_USER_PROCESSES else 'no' }}",
+    'DEBUGTTY': '{{DEBUGTTY}}',
+    'RC_LOCAL_PATH': '{{RC_LOCAL_PATH}}',
+    'HIGH_RLIMIT_NOFILE': '{{HIGH_RLIMIT_NOFILE}}',
+    'DEFAULT_DNSSEC_MODE': '{{DEFAULT_DNSSEC_MODE_STR}}',
+    'DEFAULT_DNS_OVER_TLS_MODE': '{{DEFAULT_DNS_OVER_TLS_MODE_STR}}',
+    'DEFAULT_TIMEOUT': '{{DEFAULT_TIMEOUT_SEC}} s',
+    'DEFAULT_USER_TIMEOUT': '{{DEFAULT_USER_TIMEOUT_SEC}} s',
+    'DEFAULT_KEYMAP': '{{SYSTEMD_DEFAULT_KEYMAP}}',
+    'fedora_latest_version': '40',
+    'fedora_cloud_release': '1.10',
+}
+
+# Existing lists of directive groups
+directives_data = [
+    {
+        "id": "unit-directives",
+        "title": "Unit directives",
+        "description": "Directives for configuring units, used in unit files."
+    },
+    {
+        "id": "kernel-commandline-options",
+        "title": "Options on the kernel command line",
+        "description": "Kernel boot options for configuring the behaviour of the systemd process."
+    },
+    {
+        "id": "smbios-type-11-options",
+        "title": "SMBIOS Type 11 Variables",
+        "description": "Data passed from VMM to system via SMBIOS Type 11."
+    },
+    {
+        "id": "environment-variables",
+        "title": "Environment variables",
+        "description": "Environment variables understood by the systemd manager and other programs and environment variable-compatible settings."
+    },
+    {
+        "id": "system-credentials",
+        "title": "System Credentials",
+        "description": "System credentials understood by the system and service manager and various other components:"
+    },
+    {
+        "id": "efi-variables",
+        "title": "EFI variables",
+        "description": "EFI variables understood by\n    "
+    },
+    {
+        "id": "home-directives",
+        "title": "Home Area/User Account directives",
+        "description": "Directives for configuring home areas and user accounts via\n    "
+    },
+    {
+        "id": "udev-directives",
+        "title": "UDEV directives",
+        "description": "Directives for configuring systemd units through the udev database."
+    },
+    {
+        "id": "network-directives",
+        "title": "Network directives",
+        "description": "Directives for configuring network links through the net-setup-link udev builtin and networks\n    through systemd-networkd."
+    },
+    {
+        "id": "journal-directives",
+        "title": "Journal fields",
+        "description": "Fields in the journal events with a well known meaning."
+    },
+    {
+        "id": "pam-directives",
+        "title": "PAM configuration directives",
+        "description": "Directives for configuring PAM behaviour."
+    },
+    {
+        "id": "fstab-options",
+        "title": 'fstab-options',
+        "description": "Options which influence mounted filesystems and encrypted volumes."
+    },
+    {
+        "id": "nspawn-directives",
+        "title": 'nspawn-directives',
+        "description": "Directives for configuring systemd-nspawn containers."
+    },
+    {
+        "id": "config-directives",
+        "title": "Program configuration options",
+        "description": "Directives for configuring the behaviour of the systemd process and other tools through\n    configuration files."
+    },
+    {
+        "id": "options",
+        "title": "Command line options",
+        "description": "Command-line options accepted by programs in the systemd suite."
+    },
+    {
+        "id": "constants",
+        "title": "Constants",
+        "description": "Various constants used and/or defined by systemd."
+    },
+    {
+        "id": "dns",
+        "title": "DNS resource record types",
+        "description": "No description available"
+    },
+    {
+        "id": "miscellaneous",
+        "title": "Miscellaneous options and directives",
+        "description": "Other configuration elements which don't fit in any of the above groups."
+    },
+    {
+        "id": "specifiers",
+        "title": "Specifiers",
+        "description": "Short strings which are substituted in configuration directives."
+    },
+    {
+        "id": "filenames",
+        "title": "Files and directories",
+        "description": "Paths and file names referred to in the documentation."
+    },
+    {
+        "id": "dbus-interface",
+        "title": "D-Bus interfaces",
+        "description": "Interfaces exposed over D-Bus."
+    },
+    {
+        "id": "dbus-method",
+        "title": "D-Bus methods",
+        "description": "Methods exposed in the D-Bus interface."
+    },
+    {
+        "id": "dbus-property",
+        "title": "D-Bus properties",
+        "description": "Properties exposed in the D-Bus interface."
+    },
+    {
+        "id": "dbus-signal",
+        "title": "D-Bus signals",
+        "description": "Signals emitted in the D-Bus interface."
+    }
+]
+
+role_types = [
+    'constant',
+    'var',
+    'option'
+]

doc-migration/source/docs/busctl.rst

@@ -0,0 +1,593 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: busctl
+
+:manvolnum: 1
+
+.. _busctl(1):
+
+=========
+busctl(1)
+=========
+
+.. only:: html
+
+   busctl — Introspect the bus
+   ###########################
+
+   Synopsis
+   ########
+
+``busctl`` [OPTIONS...] [COMMAND] [<NAME>...]
+
+Description
+===========
+
+``busctl`` may be used to
+introspect and monitor the D-Bus bus.
+
+Commands
+========
+
+The following commands are understood:
+
+``list``
+--------
+
+Show all peers on the bus, by their service
+names. By default, shows both unique and well-known names, but
+this may be changed with the ``--unique`` and
+``--acquired`` switches. This is the default
+operation if no command is specified.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``status [<SERVICE>]``
+----------------------
+
+Show process information and credentials of a
+bus service (if one is specified by its unique or well-known
+name), a process (if one is specified by its numeric PID), or
+the owner of the bus (if no parameter is
+specified).
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``monitor [<SERVICE>...]``
+--------------------------
+
+Dump messages being exchanged. If
+<SERVICE> is specified, show messages
+to or from this peer, identified by its well-known or unique
+name. Otherwise, show all messages on the bus. Use
+:kbd:`Ctrl` + :kbd:`C`
+to terminate the dump.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``capture [<SERVICE>...]``
+--------------------------
+
+Similar to ``monitor`` but
+writes the output in pcapng format (for details, see
+`PCAP Next Generation (pcapng) Capture File Format <https://github.com/pcapng/pcapng/>`_).
+Make sure to redirect standard output to a file or pipe. Tools like
+:die-net:`wireshark(1)`
+may be used to dissect and view the resulting
+files.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``tree [<SERVICE>...]``
+-----------------------
+
+Shows an object tree of one or more
+services. If <SERVICE> is specified,
+show object tree of the specified services only. Otherwise,
+show all object trees of all services on the bus that acquired
+at least one well-known name.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``introspect <SERVICE> <OBJECT> [<INTERFACE>]``
+-----------------------------------------------
+
+Show interfaces, methods, properties and
+signals of the specified object (identified by its path) on
+the specified service. If the interface argument is passed, the
+output is limited to members of the specified
+interface.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``call <SERVICE> <OBJECT> <INTERFACE> <METHOD> [<SIGNATURE>[<ARGUMENT>...]]``
+-----------------------------------------------------------------------------
+
+Invoke a method and show the response. Takes a
+service name, object path, interface name and method name. If
+parameters shall be passed to the method call, a signature
+string is required, followed by the arguments, individually
+formatted as strings. For details on the formatting used, see
+below. To suppress output of the returned data, use the
+``--quiet`` option.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``emit <OBJECT> <INTERFACE> <SIGNAL> [<SIGNATURE>[<ARGUMENT>...]]``
+-------------------------------------------------------------------
+
+Emit a signal. Takes an object path, interface name and method name. If parameters
+shall be passed, a signature string is required, followed by the arguments, individually formatted as
+strings. For details on the formatting used, see below. To specify the destination of the signal,
+use the ``--destination=`` option.
+
+.. only:: html
+
+   .. versionadded:: 242
+
+``get-property <SERVICE> <OBJECT> <INTERFACE> <PROPERTY>``
+----------------------------------------------------------
+
+Retrieve the current value of one or more
+object properties. Takes a service name, object path,
+interface name and property name. Multiple properties may be
+specified at once, in which case their values will be shown one
+after the other, separated by newlines. The output is, by
+default, in terse format. Use ``--verbose`` for a
+more elaborate output format.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``set-property <SERVICE> <OBJECT> <INTERFACE> <PROPERTY> <SIGNATURE> <ARGUMENT>``
+---------------------------------------------------------------------------------
+
+Set the current value of an object
+property. Takes a service name, object path, interface name,
+property name, property signature, followed by a list of
+parameters formatted as strings.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``help``
+--------
+
+Show command syntax help.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+Options
+=======
+
+The following options are understood:
+
+``--address=<ADDRESS>``
+-----------------------
+
+Connect to the bus specified by
+<ADDRESS> instead of using suitable
+defaults for either the system or user bus (see
+``--system`` and ``--user``
+options).
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--show-machine``
+------------------
+
+When showing the list of peers, show a
+column containing the names of containers they belong to.
+See
+:ref:`systemd-machined.service(8)`.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--unique``
+------------
+
+When showing the list of peers, show only
+"unique" names (of the form
+":<number>.<number>").
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--acquired``
+--------------
+
+The opposite of ``--unique`` —
+only "well-known" names will be shown.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--activatable``
+-----------------
+
+When showing the list of peers, show only
+peers which have actually not been activated yet, but may be
+started automatically if accessed.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--match=<MATCH>``
+-------------------
+
+When showing messages being exchanged, show only the
+subset matching <MATCH>.
+See
+:ref:`sd_bus_add_match(3)`.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--size=``
+-----------
+
+When used with the ``capture`` command,
+specifies the maximum bus message size to capture
+("snaplen"). Defaults to 4096 bytes.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--list``
+----------
+
+When used with the ``tree`` command, shows a
+flat list of object paths instead of a tree.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``-q, --quiet``
+---------------
+
+When used with the ``call`` command,
+suppresses display of the response message payload. Note that even
+if this option is specified, errors returned will still be
+printed and the tool will indicate success or failure with
+the process exit code.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--verbose``
+-------------
+
+When used with the ``call`` or
+``get-property`` command, shows output in a
+more verbose format.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--xml-interface``
+-------------------
+
+When used with the ``introspect`` call, dump the XML description received from
+the D-Bus ``org.freedesktop.DBus.Introspectable.Introspect`` call instead of the
+normal output.
+
+.. only:: html
+
+   .. versionadded:: 243
+
+``--json=<MODE>``
+-----------------
+
+When used with the ``call`` or ``get-property`` command, shows output
+formatted as JSON. Expects one of "short" (for the shortest possible output without any
+redundant whitespace or line breaks) or "pretty" (for a pretty version of the same, with
+indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
+way, which means type information is embedded into the JSON object tree.
+
+.. only:: html
+
+   .. versionadded:: 240
+
+``-j``
+------
+
+Equivalent to ``--json=pretty`` when invoked interactively from a terminal. Otherwise
+equivalent to ``--json=short``, in particular when the output is piped to some other
+program.
+
+.. only:: html
+
+   .. versionadded:: 240
+
+``--expect-reply=<BOOL>``
+-------------------------
+
+When used with the ``call`` command,
+specifies whether ``busctl`` shall wait for
+completion of the method call, output the returned method
+response data, and return success or failure via the process
+exit code. If this is set to "no", the
+method call will be issued but no response is expected, the
+tool terminates immediately, and thus no response can be
+shown, and no success or failure is returned via the exit
+code. To only suppress output of the reply message payload,
+use ``--quiet`` above. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--auto-start=<BOOL>``
+-----------------------
+
+When used with the ``call`` or ``emit`` command, specifies
+whether the method call should implicitly activate the
+called service, should it not be running yet but is
+configured to be auto-started. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--allow-interactive-authorization=<BOOL>``
+--------------------------------------------
+
+When used with the ``call`` command,
+specifies whether the services may enforce interactive
+authorization while executing the operation, if the security
+policy is configured for this. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--timeout=<SECS>``
+--------------------
+
+When used with the ``call`` command,
+specifies the maximum time to wait for method call
+completion. If no time unit is specified, assumes
+seconds. The usual other units are understood, too (ms, us,
+s, min, h, d, w, month, y). Note that this timeout does not
+apply if ``--expect-reply=no`` is used, as the
+tool does not wait for any reply message then. When not
+specified or when set to 0, the default of
+"25s" is assumed.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--augment-creds=<BOOL>``
+--------------------------
+
+Controls whether credential data reported by
+``list`` or ``status`` shall
+be augmented with data from
+``/proc/``. When this is turned on, the data
+shown is possibly inconsistent, as the data read from
+``/proc/`` might be more recent than the rest of
+the credential information. Defaults to "yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--watch-bind=<BOOL>``
+-----------------------
+
+Controls whether to wait for the specified ``AF_UNIX`` bus socket to appear in the
+file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
+the socket is created and then connect to it.
+
+.. only:: html
+
+   .. versionadded:: 237
+
+``--destination=<SERVICE>``
+---------------------------
+
+Takes a service name. When used with the ``emit`` command, a signal is
+emitted to the specified service.
+
+.. only:: html
+
+   .. versionadded:: 242
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove user
+                    :end-before: .. inclusion-end-marker-do-not-remove user
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove system
+                    :end-before: .. inclusion-end-marker-do-not-remove system
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove host
+                    :end-before: .. inclusion-end-marker-do-not-remove host
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove machine
+                    :end-before: .. inclusion-end-marker-do-not-remove machine
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove capsule
+                    :end-before: .. inclusion-end-marker-do-not-remove capsule
+
+``-l, --full``
+--------------
+
+Do not ellipsize the output in ``list`` command.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove no-pager
+                    :end-before: .. inclusion-end-marker-do-not-remove no-pager
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove no-legend
+                    :end-before: .. inclusion-end-marker-do-not-remove no-legend
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove help
+                    :end-before: .. inclusion-end-marker-do-not-remove help
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove version
+                    :end-before: .. inclusion-end-marker-do-not-remove version
+
+Parameter Formatting
+====================
+
+The ``call`` and
+``set-property`` commands take a signature string
+followed by a list of parameters formatted as string (for details
+on D-Bus signature strings, see the `Type
+system chapter of the D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#type-system>`_). For simple
+types, each parameter following the signature should simply be the
+parameter's value formatted as string. Positive boolean values may
+be formatted as "true", "yes",
+"on", or "1"; negative boolean
+values may be specified as "false",
+"no", "off", or
+"0". For arrays, a numeric argument for the
+number of entries followed by the entries shall be specified. For
+variants, the signature of the contents shall be specified,
+followed by the contents. For dictionaries and structs, the
+contents of them shall be directly specified.
+
+For example,
+
+.. code-block:: sh
+
+   s jawoll
+
+is the formatting
+of a single string "jawoll".
+
+.. code-block:: sh
+
+   as 3 hello world foobar
+
+is the formatting of a string array with three entries,
+"hello", "world" and
+"foobar".
+
+.. code-block:: sh
+
+   a{sv} 3 One s Eins Two u 2 Yes b true
+
+is the formatting of a dictionary
+array that maps strings to variants, consisting of three
+entries. The string "One" is assigned the
+string "Eins". The string
+"Two" is assigned the 32-bit unsigned
+integer 2. The string "Yes" is assigned a
+positive boolean.
+
+Note that the ``call``,
+``get-property``, ``introspect``
+commands will also generate output in this format for the returned
+data. Since this format is sometimes too terse to be easily
+understood, the ``call`` and
+``get-property`` commands may generate a more
+verbose, multi-line output when passed the
+``--verbose`` option.
+
+Examples
+========
+
+Write and Read a Property
+-------------------------
+
+The following two commands first write a property and then
+read it back. The property is found on the
+"/org/freedesktop/systemd1" object of the
+"org.freedesktop.systemd1" service. The name of
+the property is "LogLevel" on the
+"org.freedesktop.systemd1.Manager"
+interface. The property contains a single string:
+
+.. code-block:: sh
+
+   # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
+   # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
+   s "debug"
+
+Terse and Verbose Output
+------------------------
+
+The following two commands read a property that contains
+an array of strings, and first show it in terse format, followed
+by verbose format:
+
+.. code-block:: sh
+
+   $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
+   as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
+   $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
+   ARRAY "s" {
+           STRING "LANG=en_US.UTF-8";
+           STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
+   };
+
+Invoking a Method
+-----------------
+
+The following command invokes the
+"StartUnit" method on the
+"org.freedesktop.systemd1.Manager"
+interface of the
+"/org/freedesktop/systemd1" object
+of the "org.freedesktop.systemd1"
+service, and passes it two strings
+"cups.service" and
+"replace". As a result of the method
+call, a single object path parameter is received and
+shown:
+
+.. code-block:: sh
+
+   # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
+   o "/org/freedesktop/systemd1/job/42684"
+
+See Also
+========
+
+:dbus:`dbus-daemon(1)`, `D-Bus <https://www.freedesktop.org/wiki/Software/dbus>`_, :ref:`sd-bus(3)`, :ref:`varlinkctl(1)`, :ref:`systemd(1)`, :ref:`machinectl(1)`, :die-net:`wireshark(1)`

doc-migration/source/docs/includes/sd_journal_get_data.rst

@@ -0,0 +1,315 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: sd_journal_get_data
+
+:manvolnum: 3
+
+.. _sd_journal_get_data(3):
+
+======================
+sd_journal_get_data(3)
+======================
+
+.. only:: html
+
+   sd_journal_get_data — sd_journal_enumerate_data — sd_journal_enumerate_available_data — sd_journal_restart_data — SD_JOURNAL_FOREACH_DATA — sd_journal_set_data_threshold — sd_journal_get_data_threshold — Read data fields from the current journal entry
+   ###########################################################################################################################################################################################################################################################
+
+   Synopsis
+   ########
+
+``#include <systemd/sd-journal.h>``
+
+.. code-block::
+
+   int sd_journal_get_data(sd_journal *j,
+	const char *field,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   int sd_journal_enumerate_data(sd_journal *j,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   int sd_journal_enumerate_available_data(sd_journal *j,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   void sd_journal_restart_data(sd_journal *j);
+
+.. code-block::
+
+   SD_JOURNAL_FOREACH_DATA(sd_journal *j,
+	const void *data,
+	size_t length);
+
+.. code-block::
+
+   int sd_journal_set_data_threshold(sd_journal *j,
+	size_t sz);
+
+.. code-block::
+
+   int sd_journal_get_data_threshold(sd_journal *j,
+	size_t *sz);
+
+Description
+===========
+
+sd_journal_get_data() gets the data object associated with a specific field
+from the current journal entry. It takes four arguments: the journal context object, a string with the
+field name to request, plus a pair of pointers to pointer/size variables where the data object and its
+size shall be stored in. The field name should be an entry field name. Well-known field names are listed in
+:ref:`systemd.journal-fields(7)`,
+but any field can be specified. The returned data is in a read-only memory map and is only valid until
+the next invocation of sd_journal_get_data(),
+sd_journal_enumerate_data(),
+sd_journal_enumerate_available_data(), or when the read pointer is altered. Note
+that the data returned will be prefixed with the field name and "=". Also note that, by
+default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned
+off with sd_journal_set_data_threshold() (see below).
+
+sd_journal_enumerate_data() may be used
+to iterate through all fields of the current entry. On each
+invocation the data for the next field is returned. The order of
+these fields is not defined. The data returned is in the same
+format as with sd_journal_get_data() and also
+follows the same life-time semantics.
+
+sd_journal_enumerate_available_data() is similar to
+sd_journal_enumerate_data(), but silently skips any fields which may be valid, but
+are too large or not supported by current implementation.
+
+sd_journal_restart_data() resets the
+data enumeration index to the beginning of the entry. The next
+invocation of sd_journal_enumerate_data()
+will return the first field of the entry again.
+
+Note that the SD_JOURNAL_FOREACH_DATA() macro may be used as a handy wrapper
+around sd_journal_restart_data() and
+sd_journal_enumerate_available_data().
+
+Note that these functions will not work before
+:ref:`sd_journal_next(3)`
+(or related call) has been called at least once, in order to
+position the read pointer at a valid entry.
+
+sd_journal_set_data_threshold() may be
+used to change the data field size threshold for data returned by
+sd_journal_get_data(),
+sd_journal_enumerate_data() and
+sd_journal_enumerate_unique(). This threshold
+is a hint only: it indicates that the client program is interested
+only in the initial parts of the data fields, up to the threshold
+in size — but the library might still return larger data objects.
+That means applications should not rely exclusively on this
+setting to limit the size of the data fields returned, but need to
+apply an explicit size limit on the returned data as well. This
+threshold defaults to 64K by default. To retrieve the complete
+data fields this threshold should be turned off by setting it to
+0, so that the library always returns the complete data objects.
+It is recommended to set this threshold as low as possible since
+this relieves the library from having to decompress large
+compressed data objects in full.
+
+sd_journal_get_data_threshold() returns
+the currently configured data field size threshold.
+
+Return Value
+============
+
+sd_journal_get_data() returns 0 on success or a negative errno-style error
+code. sd_journal_enumerate_data() and
+sd_journal_enumerate_available_data() return a positive integer if the next field
+has been read, 0 when no more fields remain, or a negative errno-style error code.
+sd_journal_restart_data() doesn't return anything.
+sd_journal_set_data_threshold() and sd_journal_get_threshold()
+return 0 on success or a negative errno-style error code.
+
+Errors
+------
+
+Returned errors may indicate the following problems:
+
+.. inclusion-marker-do-not-remove EINVAL
+
+.. option:: -EINVAL
+
+   One of the required parameters is ``NULL`` or invalid.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EINVAL
+
+.. inclusion-marker-do-not-remove ECHILD
+
+.. option:: -ECHILD
+
+   The journal object was created in a different process, library or module instance.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ECHILD
+
+.. inclusion-marker-do-not-remove EADDRNOTAVAIL
+
+.. option:: -EADDRNOTAVAIL
+
+   The read pointer is not positioned at a valid entry;
+   :ref:`sd_journal_next(3)`
+   or a related call has not been called at least once.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EADDRNOTAVAIL
+
+.. inclusion-marker-do-not-remove ENOENT
+
+.. option:: -ENOENT
+
+   The current entry does not include the specified field.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOENT
+
+.. inclusion-marker-do-not-remove ENOMEM
+
+.. option:: -ENOMEM
+
+   Memory allocation failed.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOMEM
+
+.. inclusion-marker-do-not-remove ENOBUFS
+
+.. option:: -ENOBUFS
+
+   A compressed entry is too large.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOBUFS
+
+.. inclusion-marker-do-not-remove E2BIG
+
+.. option:: -E2BIG
+
+   The data field is too large for this computer architecture (e.g. above 4 GB on a
+   32-bit architecture).
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove E2BIG
+
+.. inclusion-marker-do-not-remove EPROTONOSUPPORT
+
+.. option:: -EPROTONOSUPPORT
+
+   The journal is compressed with an unsupported method or the journal uses an
+   unsupported feature.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EPROTONOSUPPORT
+
+.. inclusion-marker-do-not-remove EBADMSG
+
+.. option:: -EBADMSG
+
+   The journal is corrupted (possibly just the entry being iterated over).
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EBADMSG
+
+.. inclusion-marker-do-not-remove EIO
+
+.. option:: -EIO
+
+   An I/O error was reported by the kernel.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EIO
+
+Notes
+=====
+
+.. include:: ../includes/threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove strict
+                    :end-before: .. inclusion-end-marker-do-not-remove strict
+
+.. include:: ../includes/libsystemd-pkgconfig.rst
+                    :start-after: .. inclusion-marker-do-not-remove pkgconfig-text
+                    :end-before: .. inclusion-end-marker-do-not-remove pkgconfig-text
+
+Examples
+========
+
+See
+:ref:`sd_journal_next(3)`
+for a complete example how to use
+sd_journal_get_data().
+
+Use the
+SD_JOURNAL_FOREACH_DATA() macro to
+iterate through all fields of the current journal
+entry:
+
+.. code-block:: sh
+
+   …
+   int print_fields(sd_journal *j) {
+     const void *data;
+     size_t length;
+     SD_JOURNAL_FOREACH_DATA(j, data, length)
+       printf("%.*s\n", (int) length, data);
+   }
+   …
+
+History
+=======
+
+sd_journal_get_data(),
+sd_journal_enumerate_data(),
+sd_journal_restart_data(), and
+SD_JOURNAL_FOREACH_DATA() were added in version 187.
+
+sd_journal_set_data_threshold() and
+sd_journal_get_data_threshold() were added in version 196.
+
+sd_journal_enumerate_available_data() was added in version 246.
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd.journal-fields(7)`, :ref:`sd-journal(3)`, :ref:`sd_journal_open(3)`, :ref:`sd_journal_next(3)`, :ref:`sd_journal_get_realtime_usec(3)`, :ref:`sd_journal_query_unique(3)`

doc-migration/source/docs/os-release.rst

@@ -0,0 +1,576 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: os-release
+
+:manvolnum: 5
+
+.. _os-release(5):
+
+=============
+os-release(5)
+=============
+
+.. only:: html
+
+   os-release — initrd-release — extension-release — Operating system identification
+   #################################################################################
+
+   Synopsis
+   ########
+
+``/etc/os-release``
+``/usr/lib/os-release``
+``/etc/initrd-release``
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+
+Description
+===========
+
+The ``/etc/os-release`` and
+``/usr/lib/os-release`` files contain operating
+system identification data.
+
+The format of ``os-release`` is a newline-separated list of
+environment-like shell-compatible variable assignments. It is possible to source the configuration from
+Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this
+means variable expansion is explicitly not supported), allowing applications to read the file without
+implementing a shell compatible execution engine. Variable assignment values must be enclosed in double
+or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z,
+0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is
+optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes,
+following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not
+be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#"
+are treated as comments. Blank lines are permitted and ignored.
+
+The file ``/etc/os-release`` takes
+precedence over ``/usr/lib/os-release``.
+Applications should check for the former, and exclusively use its
+data if it exists, and only fall back to
+``/usr/lib/os-release`` if it is missing.
+Applications should not read data from both files at the same
+time. ``/usr/lib/os-release`` is the recommended
+place to store OS release information as part of vendor trees.
+``/etc/os-release`` should be a relative symlink
+to ``/usr/lib/os-release``, to provide
+compatibility with applications only looking at
+``/etc/``. A relative symlink instead of an
+absolute symlink is necessary to avoid breaking the link in a
+chroot or initrd environment.
+
+``os-release`` contains data that is
+defined by the operating system vendor and should generally not be
+changed by the administrator.
+
+As this file only encodes names and identifiers it should
+not be localized.
+
+The ``/etc/os-release`` and
+``/usr/lib/os-release`` files might be symlinks
+to other files, but it is important that the file is available
+from earliest boot on, and hence must be located on the root file
+system.
+
+``os-release`` must not contain repeating keys. Nevertheless, readers should pick
+the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A
+reader may warn about repeating entries.
+
+For a longer rationale for ``os-release``
+please refer to the `Announcement of ``/etc/os-release`` <https://0pointer.de/blog/projects/os-release>`_.
+
+``/etc/initrd-release``
+-----------------------
+
+In the `initrd <https://docs.kernel.org/admin-guide/initrd.html>`_,
+``/etc/initrd-release`` plays the same role as ``os-release`` in the
+main system. Additionally, the presence of that file means that the system is in the initrd phase.
+``/etc/os-release`` should be symlinked to ``/etc/initrd-release``
+(or vice versa), so programs that only look for ``/etc/os-release`` (as described
+above) work correctly.
+
+The rest of this document that talks about ``os-release`` should be understood
+to apply to ``initrd-release`` too.
+
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+----------------------------------------------------------
+
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+plays the same role for extension images as ``os-release`` for the main system, and
+follows the syntax and rules as described in the `Portable Services <https://systemd.io/PORTABLE_SERVICES>`_ page. The purpose of this
+file is to identify the extension and to allow the operating system to verify that the extension image
+matches the base OS. This is typically implemented by checking that the ``ID=`` options
+match, and either ``SYSEXT_LEVEL=`` exists and matches too, or if it is not present,
+``VERSION_ID=`` exists and matches. This ensures ABI/API compatibility between the
+layers and prevents merging of an incompatible image in an overlay.
+
+In order to identify the extension image itself, the same fields defined below can be added to the
+``extension-release`` file with a ``SYSEXT_`` prefix (to disambiguate
+from fields used to match on the base image). E.g.: ``SYSEXT_ID=myext``,
+``SYSEXT_VERSION_ID=1.2.3``.
+
+In the ``extension-release.<IMAGE>`` filename, the
+<IMAGE> part must exactly match the file name of the containing image with the
+suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
+change between the build and the deployment phases, it is possible to relax this check: if exactly one
+file whose name matches "``extension-release.*``" is present in this
+directory, and the file is tagged with a ``user.extension-release.strict``
+:man-pages:`xattr(7)` set to the
+string "0", it will be used instead.
+
+The rest of this document that talks about ``os-release`` should be understood
+to apply to ``extension-release`` too.
+
+Options
+=======
+
+The following OS identifications parameters may be set using
+``os-release``:
+
+General information identifying the operating system
+----------------------------------------------------
+
+.. option:: NAME=
+
+   A string identifying the operating system, without a version component, and
+   suitable for presentation to the user. If not set, a default of "NAME=Linux" may
+   be used.
+
+   Examples: "NAME=Fedora", "NAME="Debian GNU/Linux"".
+
+.. option:: ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-") identifying the operating system, excluding any version information and suitable for
+   processing by scripts or usage in generated filenames. If not set, a default of
+   "ID=linux" may be used. Note that even though this string may not include
+   characters that require shell quoting, quoting may nevertheless be used.
+
+   Examples: "ID=fedora", "ID=debian".
+
+.. option:: ID_LIKE=
+
+   A space-separated list of operating system identifiers in the same syntax as the
+   :directive:environment-variables:var:`ID=` setting. It should list identifiers of operating systems that are closely
+   related to the local operating system in regards to packaging and programming interfaces, for
+   example listing one or more OS identifiers the local OS is a derivative from.  An OS should
+   generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
+   derived from it, though symmetric relationships are possible. Build scripts and similar should
+   check this variable if they need to identify the local operating system and the value of
+   :directive:environment-variables:var:`ID=` is not recognized. Operating systems should be listed in order of how
+   closely the local operating system relates to the listed ones, starting with the closest. This
+   field is optional.
+
+   Examples: for an operating system with "ID=centos", an assignment of
+   "ID_LIKE="rhel fedora"" would be appropriate. For an operating system with
+   "ID=ubuntu", an assignment of "ID_LIKE=debian" is appropriate.
+
+.. option:: PRETTY_NAME=
+
+   A pretty operating system name in a format suitable for presentation to the
+   user. May or may not contain a release code name or OS version of some kind, as suitable. If not
+   set, a default of "PRETTY_NAME="Linux"" may be used
+
+   Example: "PRETTY_NAME="Fedora 17 (Beefy Miracle)"".
+
+.. option:: CPE_NAME=
+
+   A CPE name for the operating system, in URI binding syntax, following the `Common Platform Enumeration Specification <http://scap.nist.gov/specifications/cpe/>`_ as
+   proposed by the NIST. This field is optional.
+
+   Example: "CPE_NAME="cpe:/o:fedoraproject:fedora:17""
+
+.. option:: VARIANT=
+
+   A string identifying a specific variant or edition of the operating system suitable
+   for presentation to the user. This field may be used to inform the user that the configuration of
+   this system is subject to a specific divergent set of rules or default configuration settings. This
+   field is optional and may not be implemented on all systems.
+
+   Examples: "VARIANT="Server Edition"", "VARIANT="Smart Refrigerator
+   Edition"".
+
+   Note: this field is for display purposes only. The :directive:environment-variables:var:`VARIANT_ID` field should
+   be used for making programmatic decisions.
+
+   .. only:: html
+
+      .. versionadded:: 220
+
+.. option:: VARIANT_ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
+   "-"), identifying a specific variant or edition of the operating system. This may be interpreted by
+   other packages in order to determine a divergent default configuration. This field is optional and
+   may not be implemented on all systems.
+
+   Examples: "VARIANT_ID=server", "VARIANT_ID=embedded".
+
+   .. only:: html
+
+      .. versionadded:: 220
+
+Information about the version of the operating system
+-----------------------------------------------------
+
+.. option:: VERSION=
+
+   A string identifying the operating system version, excluding any OS name
+   information, possibly including a release code name, and suitable for presentation to the
+   user. This field is optional.
+
+   Examples: "VERSION=17", "VERSION="17 (Beefy Miracle)"".
+
+.. option:: VERSION_ID=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
+   or release code name, and suitable for processing by scripts or usage in generated filenames. This
+   field is optional.
+
+   Examples: "VERSION_ID=17", "VERSION_ID=11.04".
+
+.. option:: VERSION_CODENAME=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-") identifying the operating system release code name, excluding any OS name information or
+   release version, and suitable for processing by scripts or usage in generated filenames. This field
+   is optional and may not be implemented on all systems.
+
+   Examples: "VERSION_CODENAME=buster",
+   "VERSION_CODENAME=xenial".
+
+   .. only:: html
+
+      .. versionadded:: 231
+
+.. option:: BUILD_ID=
+
+   A string uniquely identifying the system image originally used as the installation
+   base. In most cases, :directive:environment-variables:var:`VERSION_ID` or
+   :directive:environment-variables:var:`IMAGE_ID`+:directive:environment-variables:var:`IMAGE_VERSION` are updated when the entire system
+   image is replaced during an update. :directive:environment-variables:var:`BUILD_ID` may be used in distributions where
+   the original installation image version is important: :directive:environment-variables:var:`VERSION_ID` would change
+   during incremental system updates, but :directive:environment-variables:var:`BUILD_ID` would not. This field is
+   optional.
+
+   Examples: "BUILD_ID="2013-03-20.3"", "BUILD_ID=201303203".
+
+   .. only:: html
+
+      .. versionadded:: 200
+
+.. option:: IMAGE_ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-"), identifying a specific image of the operating system. This is supposed to be used for
+   environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
+   OS images. This field is optional and may not be implemented on all systems, in particularly not on
+   those that are not managed via images but put together and updated from individual packages and on
+   the local system.
+
+   Examples: "IMAGE_ID=vendorx-cashier-system",
+   "IMAGE_ID=netbook-image".
+
+   .. only:: html
+
+      .. versionadded:: 249
+
+.. option:: IMAGE_VERSION=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
+   :directive:environment-variables:var:`IMAGE_ID` described above, to discern different versions of the same image.
+
+   Examples: "IMAGE_VERSION=33", "IMAGE_VERSION=47.1rc1".
+
+   .. only:: html
+
+      .. versionadded:: 249
+
+To summarize: if the image updates are built and shipped as comprehensive units,
+``IMAGE_ID``+``IMAGE_VERSION`` is the best fit. Otherwise, if updates
+eventually completely replace previously installed contents, as in a typical binary distribution,
+``VERSION_ID`` should be used to identify major releases of the operating system.
+``BUILD_ID`` may be used instead or in addition to ``VERSION_ID`` when
+the original system image version is important.
+
+Presentation information and links
+----------------------------------
+
+.. option:: HOME_URL=, DOCUMENTATION_URL=, SUPPORT_URL=, BUG_REPORT_URL=, PRIVACY_POLICY_URL=
+
+   Links to resources on the Internet related to the operating system.
+   :directive:environment-variables:var:`HOME_URL=` should refer to the homepage of the operating system, or alternatively
+   some homepage of the specific version of the operating system.
+   :directive:environment-variables:var:`DOCUMENTATION_URL=` should refer to the main documentation page for this
+   operating system.  :directive:environment-variables:var:`SUPPORT_URL=` should refer to the main support page for the
+   operating system, if there is any. This is primarily intended for operating systems which vendors
+   provide support for. :directive:environment-variables:var:`BUG_REPORT_URL=` should refer to the main bug reporting page
+   for the operating system, if there is any. This is primarily intended for operating systems that
+   rely on community QA. :directive:environment-variables:var:`PRIVACY_POLICY_URL=` should refer to the main privacy
+   policy page for the operating system, if there is any. These settings are optional, and providing
+   only some of these settings is common. These URLs are intended to be exposed in "About this system"
+   UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
+   Bug", or "Privacy Policy". The values should be in `RFC3986 format <https://tools.ietf.org/html/rfc3986>`_, and should be
+   "http:" or "https:" URLs, and possibly "mailto:"
+   or "tel:". Only one URL shall be listed in each setting. If multiple resources
+   need to be referenced, it is recommended to provide an online landing page linking all available
+   resources.
+
+   Examples: "HOME_URL="https://fedoraproject.org/"",
+   "BUG_REPORT_URL="https://bugzilla.redhat.com/"".
+
+.. option:: SUPPORT_END=
+
+   The date at which support for this version of the OS ends. (What exactly "lack of
+   support" means varies between vendors, but generally users should assume that updates, including
+   security fixes, will not be provided.) The value is a date in the ISO 8601 format
+   "YYYY-MM-DD", and specifies the first day on which support *is
+   not* provided.
+
+   For example, "SUPPORT_END=2001-01-01" means that the system was supported
+   until the end of the last day of the previous millennium.
+
+   .. only:: html
+
+      .. versionadded:: 252
+
+.. option:: LOGO=
+
+   A string, specifying the name of an icon as defined by `freedesktop.org Icon Theme
+   Specification <https://standards.freedesktop.org/icon-theme-spec/latest>`_. This can be used by graphical applications to display an operating system's
+   or distributor's logo. This field is optional and may not necessarily be implemented on all
+   systems.
+
+   Examples: "LOGO=fedora-logo", "LOGO=distributor-logo-opensuse"
+
+   .. only:: html
+
+      .. versionadded:: 240
+
+.. option:: ANSI_COLOR=
+
+   A suggested presentation color when showing the OS name on the console. This should
+   be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
+   graphical rendition. This field is optional.
+
+   Examples: "ANSI_COLOR="0;31"" for red, "ANSI_COLOR="1;34""
+   for light blue, or "ANSI_COLOR="0;38;2;60;110;180"" for Fedora blue.
+
+.. option:: VENDOR_NAME=
+
+   The name of the OS vendor. This is the name of the organization or company which
+   produces the OS. This field is optional.
+
+   This name is intended to be exposed in "About this system" UIs or software update UIs when
+   needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.
+
+   Examples: "VENDOR_NAME="Fedora Project"" for Fedora Linux,
+   "VENDOR_NAME="Canonical"" for Ubuntu.
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: VENDOR_URL=
+
+   The homepage of the OS vendor. This field is optional. The
+   :directive:environment-variables:var:`VENDOR_NAME=` field should be set if this one is, although clients must be
+   robust against either field not being set.
+
+   The value should be in `RFC3986 format <https://tools.ietf.org/html/rfc3986>`_, and should be
+   "http:" or "https:" URLs. Only one URL shall be listed in the
+   setting.
+
+   Examples: "VENDOR_URL="https://fedoraproject.org/"",
+   "VENDOR_URL="https://canonical.com/"".
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+Distribution-level defaults and metadata
+----------------------------------------
+
+.. option:: DEFAULT_HOSTNAME=
+
+   A string specifying the hostname if
+   :ref:`hostname(5)` is not
+   present and no other configuration source specifies the hostname. Must be either a single DNS label
+   (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
+   format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
+   that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
+   limitation (DNS allows longer names).
+
+   See :ref:`org.freedesktop.hostname1(5)`
+   for a description of how
+   :ref:`systemd-hostnamed.service(8)`
+   determines the fallback hostname.
+
+   .. only:: html
+
+      .. versionadded:: 248
+
+.. option:: ARCHITECTURE=
+
+   A string that specifies which CPU architecture the userspace binaries require.
+   The architecture identifiers are the same as for :directive:environment-variables:var:`ConditionArchitecture=`
+   described in :ref:`systemd.unit(5)`.
+   The field is optional and should only be used when just single architecture is supported.
+   It may provide redundant information when used in a GPT partition with a GUID type that already
+   encodes the architecture. If this is not the case, the architecture should be specified in
+   e.g., an extension image, to prevent an incompatible host from loading it.
+
+   .. only:: html
+
+      .. versionadded:: 252
+
+.. option:: SYSEXT_LEVEL=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
+   extension images are supported. See ``/usr/lib/extension-release.d/extension-release.<IMAGE>``,
+   `initrd <https://docs.kernel.org/admin-guide/initrd.html>`_ and
+   :ref:`systemd-sysext(8)`)
+   for more information.
+
+   Examples: "SYSEXT_LEVEL=2", "SYSEXT_LEVEL=15.14".
+
+   .. only:: html
+
+      .. versionadded:: 248
+
+.. option:: CONFEXT_LEVEL=
+
+   Semantically the same as :directive:environment-variables:var:`SYSEXT_LEVEL=` but for confext images.
+   See ``/etc/extension-release.d/extension-release.<IMAGE>``
+   for more information.
+
+   Examples: "CONFEXT_LEVEL=2", "CONFEXT_LEVEL=15.14".
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: SYSEXT_SCOPE=
+
+   Takes a space-separated list of one or more of the strings
+   "system", "initrd" and "portable". This field is
+   only supported in ``extension-release.d/`` files and indicates what environments
+   the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service
+   images. If unspecified, "SYSEXT_SCOPE=system portable" is implied, i.e. any system
+   extension without this field is applicable to regular systems and to portable service environments,
+   but not to initrd environments.
+
+   .. only:: html
+
+      .. versionadded:: 250
+
+.. option:: CONFEXT_SCOPE=
+
+   Semantically the same as :directive:environment-variables:var:`SYSEXT_SCOPE=` but for confext images.
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: PORTABLE_PREFIXES=
+
+   Takes a space-separated list of one or more valid prefix match strings for the
+   `Portable Services <https://systemd.io/PORTABLE_SERVICES>`_ logic.
+   This field serves two purposes: it is informational, identifying portable service images as such
+   (and thus allowing them to be distinguished from other OS images, such as bootable system images).
+   It is also used when a portable service image is attached: the specified or implied portable
+   service prefix is checked against the list specified here, to enforce restrictions how images may
+   be attached to a system.
+
+   .. only:: html
+
+      .. versionadded:: 250
+
+Notes
+-----
+
+If you are using this file to determine the OS or a specific version of it, use the
+``ID`` and ``VERSION_ID`` fields, possibly with
+``ID_LIKE`` as fallback for ``ID``. When looking for an OS identification
+string for presentation to the user use the ``PRETTY_NAME`` field.
+
+Note that operating system vendors may choose not to provide version information, for example to
+accommodate for rolling releases. In this case, ``VERSION`` and
+``VERSION_ID`` may be unset. Applications should not rely on these fields to be
+set.
+
+Operating system vendors may extend the file format and introduce new fields. It is highly
+recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
+reading this file must ignore unknown fields.
+
+Example: "DEBIAN_BTS="debbugs://bugs.debian.org/"".
+
+Container and sandbox runtime managers may make the host's identification data available to
+applications by providing the host's ``/etc/os-release`` (if available, otherwise
+``/usr/lib/os-release`` as a fallback) as
+``/run/host/os-release``.
+
+Examples
+========
+
+``os-release`` file for Fedora Workstation
+------------------------------------------
+
+.. code-block:: sh
+
+   NAME=Fedora
+   VERSION="32 (Workstation Edition)"
+   ID=fedora
+   VERSION_ID=32
+   PRETTY_NAME="Fedora 32 (Workstation Edition)"
+   ANSI_COLOR="0;38;2;60;110;180"
+   LOGO=fedora-logo-icon
+   CPE_NAME="cpe:/o:fedoraproject:fedora:32"
+   HOME_URL="https://fedoraproject.org/"
+   DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
+   SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
+   BUG_REPORT_URL="https://bugzilla.redhat.com/"
+   REDHAT_BUGZILLA_PRODUCT="Fedora"
+   REDHAT_BUGZILLA_PRODUCT_VERSION=32
+   REDHAT_SUPPORT_PRODUCT="Fedora"
+   REDHAT_SUPPORT_PRODUCT_VERSION=32
+   PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
+   VARIANT="Workstation Edition"
+   VARIANT_ID=workstation
+
+``extension-release`` file for an extension for Fedora Workstation 32
+---------------------------------------------------------------------
+
+.. code-block:: sh
+
+   ID=fedora
+   VERSION_ID=32
+
+Reading ``os-release`` in :man-pages:`sh(1)`
+--------------------------------------------
+
+.. literalinclude:: /code-examples/sh/check-os-release.sh
+                    :language: shell
+
+Reading ``os-release`` in :die-net:`python(1)` (versions >= 3.10)
+-----------------------------------------------------------------
+
+.. literalinclude:: /code-examples/py/check-os-release-simple.py
+                    :language: python
+
+See docs for `platform.freedesktop_os_release <https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release>`_ for more details.
+
+Reading ``os-release`` in :die-net:`python(1)` (any version)
+------------------------------------------------------------
+
+.. literalinclude:: /code-examples/py/check-os-release.py
+                    :language: python
+
+Note that the above version that uses the built-in implementation is preferred
+in most cases, and the open-coded version here is provided for reference.
+
+See Also
+========
+
+:ref:`systemd(1)`, :die-net:`lsb_release(1)`, :ref:`hostname(5)`, :ref:`machine-id(5)`, :ref:`machine-info(5)`

doc-migration/source/docs/systemD-directives.rst

@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:title: systemd.directives
+
+:manvolnum: 7
+
+
+.. _systemD-directives(7):
+
+=========
+systemd.directives(7)
+=========
+
+Index of configuration directives
+
+
+.. list_directive_roles::

doc-migration/source/includes/common-variables.rst

@@ -0,0 +1,266 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+Environment
+###########
+
+.. inclusion-marker-do-not-remove log-level
+
+``$SYSTEMD_LOG_LEVEL``
+----------------------
+.. inclusion-marker-do-not-remove log-level-body
+
+   The maximum log level of emitted messages (messages with a higher
+   log level, i.e. less important ones, will be suppressed). Takes a comma-separated list of values. A
+   value may be either one of (in order of decreasing importance) ``emerg``,
+   ``alert``, ``crit``, ``err``,
+   ``warning``, ``notice``, ``info``,
+   ``debug``, or an integer in the range 0…7. See
+   `syslog(3) <https://man7.org/linux/man-pages/man3/syslog.3.html>`_
+   for more information. Each value may optionally be prefixed with one of ``console``,
+   ``syslog``, ``kmsg`` or ``journal`` followed by a
+   colon to set the maximum log level for that specific log target (e.g.
+   ``SYSTEMD_LOG_LEVEL=debug,console:info`` specifies to log at debug level except when
+   logging to the console which should be at info level). Note that the global maximum log level takes
+   priority over any per target maximum log levels.
+
+.. inclusion-end-marker-do-not-remove log-level-body
+
+.. inclusion-end-marker-do-not-remove log-level
+
+.. inclusion-marker-do-not-remove log-color
+
+``$SYSTEMD_LOG_COLOR``
+----------------------
+.. inclusion-marker-do-not-remove log-color-body
+
+   A boolean. If true, messages written to the tty will be colored
+   according to priority.
+
+   This setting is only useful when messages are written directly to the terminal, because
+   :ref:`journalctl(1)` and
+   other tools that display logs will color messages based on the log level on their own.
+
+.. inclusion-end-marker-do-not-remove log-color-body
+
+.. inclusion-end-marker-do-not-remove log-color
+
+.. inclusion-marker-do-not-remove log-time
+
+``$SYSTEMD_LOG_TIME``
+---------------------
+.. inclusion-marker-do-not-remove log-time-body
+
+   A boolean. If true, console log messages will be prefixed with a
+   timestamp.
+
+   This setting is only useful when messages are written directly to the terminal or a file, because
+   :ref:`journalctl(1)` and
+   other tools that display logs will attach timestamps based on the entry metadata on their own.
+
+.. inclusion-end-marker-do-not-remove log-time-body
+
+.. inclusion-end-marker-do-not-remove log-time
+
+.. inclusion-marker-do-not-remove log-location
+
+``$SYSTEMD_LOG_LOCATION``
+-------------------------
+
+.. inclusion-marker-do-not-remove log-location-body
+
+   A boolean. If true, messages will be prefixed with a filename
+   and line number in the source code where the message originates.
+
+   Note that the log location is often attached as metadata to journal entries anyway. Including it
+   directly in the message text can nevertheless be convenient when debugging programs.
+
+.. inclusion-end-marker-do-not-remove log-location-body
+
+.. inclusion-end-marker-do-not-remove log-location
+
+.. inclusion-marker-do-not-remove log-tid
+
+``$SYSTEMD_LOG_TID``
+--------------------
+.. inclusion-marker-do-not-remove log-tid-body
+
+   A boolean. If true, messages will be prefixed with the current
+   numerical thread ID (TID).
+
+   Note that the this :directive:options:const:`information` is attached as metadata to journal entries anyway. Including it
+   directly in the message text can nevertheless be convenient when debugging programs.
+
+.. inclusion-end-marker-do-not-remove log-tid-body
+
+.. inclusion-end-marker-do-not-remove log-tid
+
+.. inclusion-marker-do-not-remove log-target
+
+``$SYSTEMD_LOG_TARGET``
+-----------------------
+.. inclusion-marker-do-not-remove log-target-body
+
+   The destination for log messages. One of
+   ``console`` (log to the attached tty), ``console-prefixed`` (log to
+   the attached tty but with prefixes encoding the log level and "facility", see `syslog(3) <https://man7.org/linux/man-pages/man3/syslog.3.html>`_,
+   ``kmsg`` (log to the kernel circular log buffer), ``journal`` (log to
+   the journal), ``journal-or-kmsg`` (log to the journal if available, and to kmsg
+   otherwise), ``auto`` (determine the appropriate log target automatically, the default),
+   ``null`` (disable log output).
+
+   .. COMMENT: <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated
+
+.. inclusion-end-marker-do-not-remove log-target-body
+
+.. inclusion-end-marker-do-not-remove log-target
+
+.. inclusion-marker-do-not-remove log-ratelimit-kmsg
+
+``$SYSTEMD_LOG_RATELIMIT_KMSG``
+-------------------------------
+.. inclusion-marker-do-not-remove log-ratelimit-kmsg-body
+
+   Whether to ratelimit kmsg or not. Takes a boolean.
+   Defaults to ``true``. If disabled, systemd will not ratelimit messages written to kmsg.
+
+.. inclusion-end-marker-do-not-remove log-ratelimit-kmsg-body
+
+.. inclusion-end-marker-do-not-remove log-ratelimit-kmsg
+
+.. inclusion-marker-do-not-remove pager
+
+``$SYSTEMD_PAGER``
+------------------
+.. inclusion-marker-do-not-remove pager-body
+
+   Pager to use when ``--no-pager`` is not given; overrides
+   ``$PAGER``. If neither ``$SYSTEMD_PAGER`` nor ``$PAGER`` are set, a
+   set of well-known pager implementations are tried in turn, including
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_ and
+   `more(1) <https://man7.org/linux/man-pages/man1/more.1.html>`_, until one is found. If
+   no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
+   or the value ``cat`` is equivalent to passing ``--no-pager``.
+
+   Note: if ``$SYSTEMD_PAGERSECURE`` is not set, ``$SYSTEMD_PAGER``
+   (as well as ``$PAGER``) will be silently ignored.
+
+.. inclusion-end-marker-do-not-remove pager-body
+
+.. inclusion-end-marker-do-not-remove pager
+
+.. inclusion-marker-do-not-remove less
+
+``$SYSTEMD_LESS``
+-----------------
+.. inclusion-marker-do-not-remove less-body
+
+   Override the options passed to ``less`` (by default
+   ``FRSXMK``).
+
+   Users might want to change two options in particular:
+
+   ``K``
+   -----
+      This option instructs the pager to exit immediately when
+      :kbd:`Ctrl` + :kbd:`C` is pressed. To allow
+      ``less`` to handle :kbd:`Ctrl` + :kbd:`C`
+      itself to switch back to the pager command prompt, unset this option.
+
+      If the value of ``$SYSTEMD_LESS`` does not include ``K``,
+      and the pager that is invoked is ``less``,
+      :kbd:`Ctrl` + :kbd:`C` will be ignored by the
+      executable, and needs to be handled by the pager.
+
+   ``X``
+   -----
+      This option instructs the pager to not send termcap initialization and deinitialization
+      strings to the terminal. It is set by default to allow command output to remain visible in the
+      terminal even after the pager exits. Nevertheless, this prevents some pager functionality from
+      working, in particular paged output cannot be scrolled with the mouse.
+
+   Note that setting the regular ``$LESS`` environment variable has no effect
+   for ``less`` invocations by systemd tools.
+
+   See
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_
+   for more discussion.
+
+.. inclusion-end-marker-do-not-remove less-body
+
+.. inclusion-end-marker-do-not-remove less
+
+.. inclusion-marker-do-not-remove lesscharset
+
+``$SYSTEMD_LESSCHARSET``
+------------------------
+
+   Override the charset passed to ``less`` (by default ``utf-8``, if
+   the invoking terminal is determined to be UTF-8 compatible).
+
+   Note that setting the regular ``$LESSCHARSET`` environment variable has no effect
+   for ``less`` invocations by systemd tools.
+
+.. inclusion-end-marker-do-not-remove lesscharset
+
+.. inclusion-marker-do-not-remove lesssecure
+
+``$SYSTEMD_PAGERSECURE``
+------------------------
+
+   Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
+   false, disabled. If ``$SYSTEMD_PAGERSECURE`` is not set at all, secure mode is enabled
+   if the effective UID is not the same as the owner of the login session, see
+   `geteuid(2) <https://man7.org/linux/man-pages/man2/geteuid.2.html>`_
+   and :ref:`sd_pid_get_owner_uid(3)`.
+   In secure mode, ``LESSSECURE=1`` will be set when invoking the pager, and the pager shall
+   disable commands that open or create new files or start new subprocesses. When
+   ``$SYSTEMD_PAGERSECURE`` is not set at all, pagers which are not known to implement
+   secure mode will not be used. (Currently only
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_
+   implements secure mode.)
+
+   Note: when commands are invoked with elevated privileges, for example under `sudo(8) <https://man7.org/linux/man-pages/man8/sudo.8.html>`_ or
+   `pkexec(1) <http://linux.die.net/man/ 1/pkexec>`_, care
+   must be taken to ensure that unintended interactive features are not enabled. "Secure" mode for the
+   pager may be enabled automatically as describe above. Setting ``SYSTEMD_PAGERSECURE=0``
+   or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
+   that if the ``$SYSTEMD_PAGER`` or ``$PAGER`` variables are to be
+   honoured, ``$SYSTEMD_PAGERSECURE`` must be set too. It might be reasonable to completely
+   disable the pager using ``--no-pager`` instead.
+
+.. inclusion-end-marker-do-not-remove lesssecure
+
+.. inclusion-marker-do-not-remove colors
+
+``$SYSTEMD_COLORS``
+-------------------
+
+   Takes a boolean argument. When true, ``systemd`` and related utilities
+   will use colors in their output, otherwise the output will be monochrome. Additionally, the variable can
+   take one of the following special values: ``16``, ``256`` to restrict the use
+   of colors to the base 16 or 256 ANSI colors, respectively. This can be specified to override the automatic
+   decision based on ``$TERM`` and what the console is connected to.
+
+.. COMMENT: This is not documented on purpose, because it is not clear if $NO_COLOR will become supported
+            widely enough. So let's provide support, but without advertising this.
+            <varlistentry id='no-color'>
+            <term><varname>$NO_COLOR</varname></term>
+            <listitem><para>If set (to any value), and <varname>$SYSTEMD_COLORS</varname> is not set, equivalent to
+            <option>SYSTEMD_COLORS=0</option>. See <ulink url="https://no-color.org/">no-color.org</ulink>.</para>
+            </listitem>
+            </varlistentry>
+
+.. inclusion-end-marker-do-not-remove colors
+
+.. inclusion-marker-do-not-remove urlify
+
+``$SYSTEMD_URLIFY``
+-------------------
+
+   The value must be a boolean. Controls whether clickable links should be generated in
+   the output for terminal emulators supporting this. This can be specified to override the decision that
+   ``systemd`` makes based on ``$TERM`` and other conditions.
+
+.. inclusion-end-marker-do-not-remove urlify

doc-migration/source/includes/libsystemd-pkgconfig.rst

@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+Notes
+#####
+
+Functions described here are available as a shared
+library, which can be compiled against and linked to with the
+``libsystemd```pkg-config(1) <http://linux.die.net/man/ 1/pkg-config>`_
+file.
+
+.. include:: ./includes/threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove getenv
+                    :end-before: .. inclusion-end-marker-do-not-remove getenv

doc-migration/source/includes/sd_journal_get_data.rst

@@ -0,0 +1,296 @@
+:title: sd_journal_get_data
+:manvolnum: 3
+
+.. _sd_journal_get_data(3):
+
+======================
+sd_journal_get_data(3)
+======================
+
+**Name**
+
+sd_journal_get_data — sd_journal_enumerate_data — sd_journal_enumerate_available_data — sd_journal_restart_data — SD_JOURNAL_FOREACH_DATA — sd_journal_set_data_threshold — sd_journal_get_data_threshold — Read data fields from the current journal entry
+###########################################################################################################################################################################################################################################################
+
+**Synopsis**
+
+#include <systemd/sd-journal.h>
+
+.. code-block::sh
+
+   int ``sd_journal_get_data``
+   sd_journal *j
+   const char *field
+   const void \**data
+   size_t *length
+
+   int ``sd_journal_enumerate_data``
+   sd_journal *j
+   const void \**data
+   size_t *length
+
+   int ``sd_journal_enumerate_available_data``
+   sd_journal *j
+   const void \**data
+   size_t *length
+
+   void ``sd_journal_restart_data``
+   sd_journal *j
+
+   ``SD_JOURNAL_FOREACH_DATA``
+   sd_journal *j
+   const void *data
+   size_t length
+
+   int ``sd_journal_set_data_threshold``
+   sd_journal *j
+   size_t sz
+
+   int ``sd_journal_get_data_threshold``
+   sd_journal *j
+   size_t *sz
+
+Description
+===========
+
+``sd_journal_get_data()`` gets the data object associated with a specific field
+from the current journal entry. It takes four arguments: the journal context object, a string with the
+field name to request, plus a pair of pointers to pointer/size variables where the data object and its
+size shall be stored in. The field name should be an entry field name. Well-known field names are listed in
+:ref:`systemd.journal-fields(7)`,
+but any field can be specified. The returned data is in a read-only memory map and is only valid until
+the next invocation of ``sd_journal_get_data()``,
+``sd_journal_enumerate_data()``,
+``sd_journal_enumerate_available_data()``, or when the read pointer is altered. Note
+that the data returned will be prefixed with the field name and ``=``. Also note that, by
+default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned
+off with ``sd_journal_set_data_threshold()`` (see below).
+
+``sd_journal_enumerate_data()`` may be used
+to iterate through all fields of the current entry. On each
+invocation the data for the next field is returned. The order of
+these fields is not defined. The data returned is in the same
+format as with ``sd_journal_get_data()`` and also
+follows the same life-time semantics.
+
+``sd_journal_enumerate_available_data()`` is similar to
+``sd_journal_enumerate_data()``, but silently skips any fields which may be valid, but
+are too large or not supported by current implementation.
+
+``sd_journal_restart_data()`` resets the
+data enumeration index to the beginning of the entry. The next
+invocation of ``sd_journal_enumerate_data()``
+will return the first field of the entry again.
+
+Note that the ``SD_JOURNAL_FOREACH_DATA()`` macro may be used as a handy wrapper
+around ``sd_journal_restart_data()`` and
+``sd_journal_enumerate_available_data()``.
+
+Note that these functions will not work before
+:ref:`sd_journal_next(3)`
+(or related call) has been called at least once, in order to
+position the read pointer at a valid entry.
+
+``sd_journal_set_data_threshold()`` may be
+used to change the data field size threshold for data returned by
+``sd_journal_get_data()``,
+``sd_journal_enumerate_data()`` and
+``sd_journal_enumerate_unique()``. This threshold
+is a hint only: it indicates that the client program is interested
+only in the initial parts of the data fields, up to the threshold
+in size — but the library might still return larger data objects.
+That means applications should not rely exclusively on this
+setting to limit the size of the data fields returned, but need to
+apply an explicit size limit on the returned data as well. This
+threshold defaults to 64K by default. To retrieve the complete
+data fields this threshold should be turned off by setting it to
+0, so that the library always returns the complete data objects.
+It is recommended to set this threshold as low as possible since
+this relieves the library from having to decompress large
+compressed data objects in full.
+
+``sd_journal_get_data_threshold()`` returns
+the currently configured data field size threshold.
+
+Return Value
+============
+
+``sd_journal_get_data()`` returns 0 on success or a negative errno-style error
+code. ``sd_journal_enumerate_data()`` and
+``sd_journal_enumerate_available_data()`` return a positive integer if the next field
+has been read, 0 when no more fields remain, or a negative errno-style error code.
+``sd_journal_restart_data()`` doesn't return anything.
+``sd_journal_set_data_threshold()`` and ``sd_journal_get_threshold()``
+return 0 on success or a negative errno-style error code.
+
+Errors
+------
+
+Returned errors may indicate the following problems:
+
+.. inclusion-marker-do-not-remove EINVAL
+
+-EINVAL
+-------
+
+   One of the required parameters is ``NULL`` or invalid.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EINVAL
+
+.. inclusion-marker-do-not-remove ECHILD
+
+-ECHILD
+-------
+
+   The journal object was created in a different process, library or module instance.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ECHILD
+
+.. inclusion-marker-do-not-remove EADDRNOTAVAIL
+
+-EADDRNOTAVAIL
+--------------
+
+   The read pointer is not positioned at a valid entry;
+   :ref:`sd_journal_next(3)`
+   or a related call has not been called at least once.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EADDRNOTAVAIL
+
+.. inclusion-marker-do-not-remove ENOENT
+
+-ENOENT
+-------
+
+   The current entry does not include the specified field.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOENT
+
+.. inclusion-marker-do-not-remove ENOMEM
+
+-ENOMEM
+-------
+
+   Memory allocation failed.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOMEM
+
+.. inclusion-marker-do-not-remove ENOBUFS
+
+-ENOBUFS
+--------
+
+   A compressed entry is too large.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOBUFS
+
+.. inclusion-marker-do-not-remove E2BIG
+
+-E2BIG
+------
+
+   The data field is too large for this computer architecture (e.g. above 4 GB on a
+   32-bit architecture).
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove E2BIG
+
+.. inclusion-marker-do-not-remove EPROTONOSUPPORT
+
+-EPROTONOSUPPORT
+----------------
+
+   The journal is compressed with an unsupported method or the journal uses an
+   unsupported feature.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EPROTONOSUPPORT
+
+.. inclusion-marker-do-not-remove EBADMSG
+
+-EBADMSG
+--------
+
+   The journal is corrupted (possibly just the entry being iterated over).
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EBADMSG
+
+.. inclusion-marker-do-not-remove EIO
+
+-EIO
+----
+
+   An I/O error was reported by the kernel.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EIO
+
+Notes
+=====
+
+.. include:: ./threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove strict
+                    :end-before: .. inclusion-end-marker-do-not-remove strict
+
+.. include:: ./libsystemd-pkgconfig.rst
+                    :start-after: .. inclusion-marker-do-not-remove pkgconfig-text
+                    :end-before: .. inclusion-end-marker-do-not-remove pkgconfig-text
+
+Examples
+========
+
+See
+:ref:`sd_journal_next(3)`
+for a complete example how to use
+``sd_journal_get_data()``.
+
+Use the
+``SD_JOURNAL_FOREACH_DATA()`` macro to
+iterate through all fields of the current journal
+entry:
+
+.. code-block:: sh
+
+   …
+   int print_fields(sd_journal *j) {
+     const void *data;
+     size_t length;
+     SD_JOURNAL_FOREACH_DATA(j, data, length)
+       printf("%.*s\n", (int) length, data);
+   }
+   …
+
+History
+=======
+
+``sd_journal_get_data()``,
+``sd_journal_enumerate_data()``,
+``sd_journal_restart_data()``, and
+``SD_JOURNAL_FOREACH_DATA()`` were added in version 187.
+
+``sd_journal_set_data_threshold()`` and
+``sd_journal_get_data_threshold()`` were added in version 196.
+
+``sd_journal_enumerate_available_data()`` was added in version 246.
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd.journal-fields(7)`, :ref:`sd-journal(3)`, :ref:`sd_journal_open(3)`, :ref:`sd_journal_next(3)`, :ref:`sd_journal_get_realtime_usec(3)`, :ref:`sd_journal_query_unique(3)`

doc-migration/source/includes/standard-options.rst

@@ -0,0 +1,164 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+.. inclusion-marker-do-not-remove help
+
+``-h, --help``
+--------------
+
+   Print a short help text and exit.
+
+.. inclusion-end-marker-do-not-remove help
+
+.. inclusion-marker-do-not-remove version
+
+``--version``
+-------------
+
+   Print a short version string and exit.
+
+.. inclusion-end-marker-do-not-remove version
+
+.. inclusion-marker-do-not-remove no-pager
+
+``--no-pager``
+--------------
+
+   Do not pipe output into a pager.
+
+.. inclusion-end-marker-do-not-remove no-pager
+
+.. inclusion-marker-do-not-remove no-ask-password
+
+``--no-ask-password``
+---------------------
+
+   Do not query the user for authentication for privileged operations.
+
+.. inclusion-end-marker-do-not-remove no-ask-password
+
+.. inclusion-marker-do-not-remove legend
+
+``--legend=<BOOL>``
+-------------------
+
+   Enable or disable printing of the legend, i.e. column headers and the footer with hints. The
+   legend is printed by default, unless disabled with ``--quiet`` or similar.
+
+.. inclusion-end-marker-do-not-remove legend
+
+.. inclusion-marker-do-not-remove no-legend
+
+``--no-legend``
+---------------
+
+   Do not print the legend, i.e. column headers and the
+   footer with hints.
+
+.. inclusion-end-marker-do-not-remove no-legend
+
+.. inclusion-marker-do-not-remove cat-config
+
+``--cat-config``
+----------------
+
+   Copy the contents of config files to standard output.
+   Before each file, the filename is printed as a comment.
+
+.. inclusion-end-marker-do-not-remove cat-config
+
+.. inclusion-marker-do-not-remove tldr
+
+``--tldr``
+----------
+
+   Copy the contents of config files to standard output. Only the "interesting" parts of the
+   configuration files are printed, comments and empty lines are skipped. Before each file, the filename
+   is printed as a comment.
+
+.. inclusion-end-marker-do-not-remove tldr
+
+.. inclusion-marker-do-not-remove json
+
+``--json=<MODE>``
+-----------------
+
+   Shows output formatted as JSON. Expects one of ``short`` (for the
+   shortest possible output without any redundant whitespace or line breaks), ``pretty``
+   (for a pretty version of the same, with indentation and line breaks) or ``off`` (to turn
+   off JSON output, the default).
+
+.. inclusion-end-marker-do-not-remove json
+
+.. inclusion-marker-do-not-remove j
+
+``-j``
+------
+
+   Equivalent to ``--json=pretty`` if running on a terminal, and
+   ``--json=short`` otherwise.
+
+.. inclusion-end-marker-do-not-remove j
+
+.. inclusion-marker-do-not-remove signal
+
+``-s, --signal=``
+-----------------
+
+   When used with ``kill``, choose which signal to send to selected processes. Must
+   be one of the well-known signal specifiers such as ``SIGTERM``,
+   ``SIGINT`` or ``SIGSTOP``. If omitted, defaults to
+   ``SIGTERM``.
+
+   The special value ``help`` will list the known values and the program will exit
+   immediately, and the special value ``list`` will list known values along with the
+   numerical signal numbers and the program will exit immediately.
+
+.. inclusion-end-marker-do-not-remove signal
+
+.. inclusion-marker-do-not-remove image-policy-open
+
+``--image-policy=<policy>``
+---------------------------
+
+   Takes an image policy string as argument, as per
+   :ref:`systemd.image-policy(7)`. The
+   policy is enforced when operating on the disk image specified via ``--image=``, see
+   above. If not specified defaults to the ``*`` policy, i.e. all recognized file systems
+   in the image are used.
+
+.. inclusion-end-marker-do-not-remove image-policy-open
+
+.. inclusion-marker-do-not-remove esp-path
+
+``--esp-path=``
+---------------
+
+   Path to the EFI System Partition (ESP). If not specified, ``/efi/``,
+   ``/boot/``, and ``/boot/efi/`` are checked in turn. It is
+   recommended to mount the ESP to ``/efi/``, if possible.
+
+.. inclusion-end-marker-do-not-remove esp-path
+
+.. inclusion-marker-do-not-remove boot-path
+
+``--boot-path=``
+----------------
+
+   Path to the Extended Boot Loader partition, as defined in the
+   `Boot Loader Specification <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
+   If not specified, ``/boot/`` is checked. It is recommended to mount the Extended Boot
+   Loader partition to ``/boot/``, if possible.
+
+.. inclusion-end-marker-do-not-remove boot-path
+
+.. inclusion-marker-do-not-remove option-P
+
+``-P``
+------
+
+   Equivalent to ``--value`` ``--property=``, i.e. shows the value of the
+   property without the property name or ``=``. Note that using ``-P`` once
+   will also affect all properties listed with ``-p``/``--property=``.
+
+.. inclusion-end-marker-do-not-remove option-P

doc-migration/source/includes/threads-aware.rst

@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+.. inclusion-marker-do-not-remove strict
+
+All functions listed here are thread-agnostic and only a single specific thread may operate on a
+given object during its entire lifetime. It's safe to allocate multiple independent objects and use each from a
+specific thread in parallel. However, it's not safe to allocate such an object in one thread, and operate or free it
+from any other, even if locking is used to ensure these threads don't operate on it at the very same time.
+
+.. inclusion-end-marker-do-not-remove strict
+
+.. inclusion-marker-do-not-remove safe
+
+All functions listed here are thread-safe and may be called in parallel from multiple threads.
+
+.. inclusion-end-marker-do-not-remove safe
+
+.. inclusion-marker-do-not-remove getenv
+
+The code described here uses
+:man-pages:`getenv(3)`,
+which is declared to be not multi-thread-safe. This means that the code calling the functions described
+here must not call
+:man-pages:`setenv(3)`
+from a parallel thread. It is recommended to only do calls to ``setenv()``
+from an early phase of the program when no other threads have been started.
+
+.. inclusion-end-marker-do-not-remove getenv

doc-migration/source/includes/user-system-options.rst

@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+.. inclusion-marker-do-not-remove user
+
+``--user``
+----------
+
+   Talk to the service manager of the calling user,
+   rather than the service manager of the system.
+
+.. inclusion-end-marker-do-not-remove user
+
+.. inclusion-marker-do-not-remove system
+
+``--system``
+------------
+
+   Talk to the service manager of the system. This is the
+   implied default.
+
+.. inclusion-end-marker-do-not-remove system
+
+.. inclusion-marker-do-not-remove host
+
+``-H, --host=``
+---------------
+
+   Execute the operation remotely. Specify a hostname, or a
+   username and hostname separated by ``@``, to
+   connect to. The hostname may optionally be suffixed by a
+   port ssh is listening on, separated by ``:``, and then a
+   container name, separated by ``/``, which
+   connects directly to a specific container on the specified
+   host. This will use SSH to talk to the remote machine manager
+   instance. Container names may be enumerated with
+   ``machinectl -H
+   <HOST>``. Put IPv6 addresses in brackets.
+
+.. inclusion-end-marker-do-not-remove host
+
+.. inclusion-marker-do-not-remove machine
+
+``-M, --machine=``
+------------------
+
+   Execute operation on a local container. Specify a container name to connect to, optionally
+   prefixed by a user name to connect as and a separating ``@`` character. If the special
+   string ``.host`` is used in place of the container name, a connection to the local
+   system is made (which is useful to connect to a specific user's user bus: ``--user
+   --machine=lennart@.host``). If the ``@`` syntax is not used, the connection is
+   made as root user. If the ``@`` syntax is used either the left hand side or the right hand
+   side may be omitted (but not both) in which case the local user name and ``.host`` are
+   implied.
+
+.. inclusion-end-marker-do-not-remove machine
+
+.. inclusion-marker-do-not-remove capsule
+
+``-C, --capsule=``
+------------------
+
+   Execute operation on a capsule. Specify a capsule name to connect to. See
+   :ref:`capsule@.service(5)` for
+   details about capsules.
+
+   .. versionadded:: 256
+
+.. inclusion-end-marker-do-not-remove capsule

doc-migration/source/index.rst

@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+.. systemd documentation master file, created by
+   sphinx-quickstart on Wed Jun 26 16:24:13 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+systemd — System and Service Manager
+===================================
+
+.. manual reference to a doc by its reference label
+   see: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
+.. Manual links
+.. ------------
+.. :ref:`busctl(1)`
+.. :ref:`systemd(1)`
+.. OR using the toctree to pull in files
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+.. This only works if we restructure our headings to match
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+   and then only have single top-level heading with the command name
+
+.. toctree::
+   :maxdepth: 1
+
+   docs/busctl
+   docs/journalctl
+   docs/os-release
+   docs/systemd
+   docs/systemD-directives
+   docs/includes/sd_journal_get_data
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search` 

hwdb.d/60-sensor.hwdb

@@ -760,8 +760,9 @@ sensor:modalias:i2c:bmc150_accel:dmi:*:svnLENOVO:*:pvrLenovoYoga300-11IBR:*
 sensor:modalias:acpi:ACCL0001*:dmi:*:svnLENOVO:pn60072:pvr851*:*
  ACCEL_MOUNT_MATRIX=0, 1, 0; -1, 0, 0; 0, 0, 1
 
-# IdeaPad Duet 3 10IGL5 (82AT)
+# IdeaPad Duet 3 10IGL5 (82AT) and 10IGL5-LTE (82HK)
 sensor:modalias:acpi:SMO8B30*:dmi:*:svnLENOVO*:pn82AT:*
+sensor:modalias:acpi:SMO8B30*:dmi:*:svnLENOVO*:pn82HK:*
  ACCEL_MOUNT_MATRIX=0, 1, 0; -1, 0, 0; 0, 0, 1
 
 #########################################

man/org.freedesktop.systemd1.xml

@@ -593,8 +593,6 @@ node /org/freedesktop/systemd1 {
 
     <!--method GetJobBefore is not documented!-->
 
-    <!--method SetShowStatus is not documented!-->
-
     <!--method ListUnitsFiltered is not documented!-->
 
     <!--method ListUnitsByPatterns is not documented!-->
@@ -673,8 +671,6 @@ node /org/freedesktop/systemd1 {
 
     <!--property ConfirmSpawn is not documented!-->
 
-    <!--property ShowStatus is not documented!-->
-
     <!--property DefaultStandardOutput is not documented!-->
 
     <!--property DefaultStandardError is not documented!-->
@@ -1362,6 +1358,24 @@ node /org/freedesktop/systemd1 {
 
       <para><function>ResetFailedUnit()</function> resets the "failed" state of a specific unit.</para>
 
+      <para><function>SetShowStatus()</function> configures the display of status messages during bootup and
+      shutdown. The <varname>mode</varname> parameter can be set to any value that's valid for the
+      <varname>systemd.show_status</varname> kernel parameter. For more information about
+      <varname>systemd.show_status</varname>, see
+      <citerefentry project="man-pages"><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+      The <varname>mode</varname> parameter can also be set to an empty string. When <varname>mode</varname>
+      is set to an empty string, <function>SetShowStatus()</function> will reset
+      <varname>ShowStatus</varname> back to its original value. You can use
+      <function>SetShowStatus()</function> create a service that does something like this:
+      <orderedlist>
+        <listitem><para>Send a D-Bus message that will turn off status messages.</para></listitem>
+        <listitem><para>Block until a reply to that message is received.</para></listitem>
+        <listitem><para>Print multiples lines without being interrupted by status messages.</para></listitem>
+        <listitem><para>Send a D-Bus message that will reset <varname>ShowStatus</varname> back to its
+        original value.</para></listitem>
+      </orderedlist>
+      </para>
+
       <para><function>ResetFailed()</function> resets the "failed" state of all units.</para>
 
       <para><function>ListUnits()</function> returns an array of all currently loaded units. Note that
@@ -1788,6 +1802,12 @@ node /org/freedesktop/systemd1 {
       <para><varname>Environment</varname> encodes the environment block passed to all executed services. It
       may be altered with bus calls such as <function>SetEnvironment()</function> (see above).</para>
 
+      <para><varname>ShowStatus</varname> encodes systemd's current policy for displaying status messages
+      during bootup and shutdown. Its value can be any valid value for the
+      <varname>systemd.show_status</varname> kernel parameter (see
+      <citerefentry project="man-pages"><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
+      It may be altered using <function>SetShowStatus()</function> (see above).</para>
+
       <para><varname>UnitPath</varname> encodes the currently active unit file search path. It is an array of
       file system paths encoded as strings.</para>
 

man/repart.d.xml

@@ -483,18 +483,18 @@
         <term><varname>ExcludeFiles=</varname></term>
         <term><varname>ExcludeFilesTarget=</varname></term>
 
-        <listitem><para>Takes an absolute file system path referring to a source file or directory on the
-        host. This setting may be used to exclude files or directories from the host from being copied into
-        the file system when <varname>CopyFiles=</varname> is used. This option may be used multiple times to
-        exclude multiple files or directories from host from being copied into the newly formatted file
-        system.</para>
+        <listitem><para>Takes one or more absolute paths, separated by whitespace, each referring to a
+        source file or directory on the host. This setting may be used to exclude files or directories from
+        the host from being copied into the file system when <varname>CopyFiles=</varname> is used. This
+        option may be used multiple times to exclude multiple files or directories from host from being
+        copied into the newly formatted file system.</para>
 
         <para>If the path is a directory and ends with <literal>/</literal>, only the directory's
         contents are excluded but not the directory itself. If the path is a directory and does not end with
         <literal>/</literal>, both the directory and its contents are excluded.</para>
 
         <para><varname>ExcludeFilesTarget=</varname> is like <varname>ExcludeFiles=</varname> except that
-        instead of excluding the path on the host from being copied into the partition, we exclude any files
+        instead of excluding the path on the host from being copied into the partition, it exclude any files
         and directories from being copied into the given path in the partition.</para>
 
         <para>When
@@ -922,9 +922,9 @@
         target for some other supplement definition. A target cannot have more than one supplement partition
         associated with it.</para>
 
-        <para>For example, distributions can use this to implement <variable>$BOOT</variable> as defined in
+        <para>For example, distributions can use this to implement <varname>$BOOT</varname> as defined in
         the <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification/">Boot Loader
-        Specification</ulink>. Distributions may prefer to use the ESP as <variable>$BOOT</variable> whenever
+        Specification</ulink>. Distributions may prefer to use the ESP as <varname>$BOOT</varname> whenever
         possible, but to adhere to the spec XBOOTLDR must sometimes be used instead. So, they should create
         two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for
         the XBOOTLDR that's sufficiently large to hold kernels and configured as a supplement for the ESP.

man/systemd.exec.xml

@@ -3001,7 +3001,12 @@ SystemCallErrorNumber=EPERM</programlisting>
 
         <para><option>tty</option> connects standard output to a tty (as configured via <varname>TTYPath=</varname>,
         see below). If the TTY is used for output only, the executed process will not become the controlling process of
-        the terminal, and will not fail or wait for other processes to release the terminal.</para>
+        the terminal, and will not fail or wait for other processes to release the terminal. Note: if a unit
+        tries to print multiple lines to a TTY during bootup or shutdown, then there's a chance that those
+        lines will be broken up by status messages. <function>SetShowStatus()</function> can be used to
+        prevent this problem. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for details.</para>
 
         <para><option>journal</option> connects standard output with the journal, which is accessible via
         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note

man/systemd.xml

@@ -568,7 +568,11 @@
         <listitem><para>Enables display of status messages on the
         console, as controlled via
         <varname>systemd.show_status=1</varname> on the kernel command
-        line.</para></listitem>
+        line.</para>
+        <para>You may want to use <function>SetShowStatus()</function> instead of
+        <constant>SIGRTMIN+20</constant> in order to prevent race conditions. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -579,7 +583,11 @@
         controlled via
         <varname>systemd.show_status=0</varname>
         on the kernel command
-        line.</para></listitem>
+        line.</para>
+        <para>You may want to use <function>SetShowStatus()</function> instead of
+        <constant>SIGRTMIN+21</constant> in order to prevent race conditions. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>

src/core/service.c

@@ -4169,7 +4169,7 @@ static void service_sigchld_event(Unit *u, pid_t pid, int code, int status) {
          * detect when the cgroup becomes empty. Note that the control process is always
          * our child so it's pointless to watch all other processes. */
         if (!control_pid_good(s))
-                if (!s->main_pid_known || s->main_pid_alien)
+                if (!s->main_pid_known || s->main_pid_alien || unit_cgroup_delegate(u))
                         (void) unit_enqueue_rewatch_pids(u);
 }
 

src/kernel-install/kernel-install.c

@@ -404,15 +404,16 @@ static int context_set_path_strv(Context *c, char* const* strv, const char *sour
 
 static int context_set_plugins(Context *c, const char *s, const char *source) {
         _cleanup_strv_free_ char **v = NULL;
+        int r;
 
         assert(c);
 
         if (c->plugins || !s)
                 return 0;
 
-        v = strv_split(s, NULL);
-        if (!v)
-                return log_oom();
+        r = strv_split_full(&v, s, NULL, EXTRACT_UNQUOTE);
+        if (r < 0)
+                return log_error_errno(r, "Failed to parse plugin paths from %s: %m", source);
 
         return context_set_path_strv(c, v, source, "plugins", &c->plugins);
 }

src/kernel-install/test-kernel-install.sh

@@ -46,7 +46,13 @@ echo 'DTBDTBDTBDTB' >"$D/sources/subdir/whatever.dtb"
 
 export KERNEL_INSTALL_CONF_ROOT="$D/sources"
 # We "install" multiple plugins, but control which ones will be active via install.conf.
-export KERNEL_INSTALL_PLUGINS="${ukify_install} ${loaderentry_install} ${uki_copy_install}"
+KERNEL_INSTALL_PLUGINS="'${loaderentry_install}' '${uki_copy_install}'"
+if [[ -n "$ukify_install" ]]; then
+    # shellcheck disable=SC2089
+    KERNEL_INSTALL_PLUGINS="'${ukify_install}' $KERNEL_INSTALL_PLUGINS"
+fi
+# shellcheck disable=SC2090
+export KERNEL_INSTALL_PLUGINS
 export BOOT_ROOT="$D/boot"
 export BOOT_MNT="$D/boot"
 export MACHINE_ID='3e0484f3634a418b8e6a39e8828b03e3'

src/partition/repart.c

@@ -1742,8 +1742,9 @@ static int config_parse_exclude_files(
                 const char *rvalue,
                 void *data,
                 void *userdata) {
-        _cleanup_free_ char *resolved = NULL;
+
         char ***exclude_files = ASSERT_PTR(data);
+        const char *p = ASSERT_PTR(rvalue);
         int r;
 
         if (isempty(rvalue)) {
@@ -1751,20 +1752,34 @@ static int config_parse_exclude_files(
                 return 0;
         }
 
-        r = specifier_printf(rvalue, PATH_MAX-1, system_and_tmp_specifier_table, arg_root, NULL, &resolved);
-        if (r < 0) {
-                log_syntax(unit, LOG_WARNING, filename, line, r,
-                           "Failed to expand specifiers in ExcludeFiles= path, ignoring: %s", rvalue);
-                return 0;
+        for (;;) {
+                _cleanup_free_ char *word = NULL, *resolved = NULL;
+
+                r = extract_first_word(&p, &word, NULL, EXTRACT_UNQUOTE);
+                if (r == -ENOMEM)
+                        return log_oom();
+                if (r < 0) {
+                        log_syntax(unit, LOG_WARNING, filename, line, r, "Invalid syntax, ignoring: %s", p);
+                        return 0;
+                }
+                if (r == 0)
+                        return 0;
+
+                r = specifier_printf(word, PATH_MAX-1, system_and_tmp_specifier_table, arg_root, NULL, &resolved);
+                if (r < 0) {
+                        log_syntax(unit, LOG_WARNING, filename, line, r,
+                                   "Failed to expand specifiers in %s path, ignoring: %s", lvalue, word);
+                        return 0;
+                }
+
+                r = path_simplify_and_warn(resolved, PATH_CHECK_ABSOLUTE|PATH_KEEP_TRAILING_SLASH, unit, filename, line, lvalue);
+                if (r < 0)
+                        return 0;
+
+                if (strv_consume(exclude_files, TAKE_PTR(resolved)) < 0)
+                        return log_oom();
         }
 
-        r = path_simplify_and_warn(resolved, PATH_CHECK_ABSOLUTE|PATH_KEEP_TRAILING_SLASH, unit, filename, line, lvalue);
-        if (r < 0)
-                return 0;
-
-        if (strv_consume(exclude_files, TAKE_PTR(resolved)) < 0)
-                return log_oom();
-
         return 0;
 }
 

src/test/test-compress.c

@@ -197,7 +197,7 @@ _unused_ static void test_compress_stream(const char *compression,
         ASSERT_OK(compress(src, dst, -1, &uncompressed_size));
 
         if (cat) {
-                assert_se(asprintf(&cmd, "%s %s | diff %s -", cat, pattern, srcfile) > 0);
+                assert_se(asprintf(&cmd, "%s %s | diff '%s' -", cat, pattern, srcfile) > 0);
                 assert_se(system(cmd) == 0);
         }
 
@@ -212,7 +212,7 @@ _unused_ static void test_compress_stream(const char *compression,
         r = decompress(dst, dst2, st.st_size);
         assert_se(r == 0);
 
-        assert_se(asprintf(&cmd2, "diff %s %s", srcfile, pattern2) > 0);
+        assert_se(asprintf(&cmd2, "diff '%s' %s", srcfile, pattern2) > 0);
         assert_se(system(cmd2) == 0);
 
         log_debug("/* test faulty decompression */");

src/udev/test-udev-spawn.c

@@ -52,7 +52,8 @@ static void test_event_spawn_self(const char *self, const char *arg, bool with_p
 
         log_debug("/* %s(%s, %s) */", __func__, arg, yes_no(with_pidfd));
 
-        assert_se(cmd = strjoin(self, " ", arg));
+        /* 'self' may contain spaces, hence needs to be quoted. */
+        assert_se(cmd = strjoin("'", self, "' ", arg));
 
         test_event_spawn_core(with_pidfd, cmd, result_buf, BUF_SIZE);
 

test/test-compare-versions.sh

@@ -4,32 +4,32 @@ set -e
 
 ANALYZE="${1:-systemd-analyze}"
 
-$ANALYZE compare-versions 1 lt 2
-$ANALYZE compare-versions 1 '<' 2
-$ANALYZE compare-versions 1 le 2
-$ANALYZE compare-versions 1 '<=' 2
-$ANALYZE compare-versions 1 ne 2
-$ANALYZE compare-versions 1 '!=' 2
-( ! $ANALYZE compare-versions 1 ge 2 )
-( ! $ANALYZE compare-versions 1 '>=' 2 )
-( ! $ANALYZE compare-versions 1 eq 2 )
-( ! $ANALYZE compare-versions 1 '==' 2 )
-( ! $ANALYZE compare-versions 1 gt 2 )
-( ! $ANALYZE compare-versions 1 '>' 2 )
+"$ANALYZE" compare-versions 1 lt 2
+"$ANALYZE" compare-versions 1 '<' 2
+"$ANALYZE" compare-versions 1 le 2
+"$ANALYZE" compare-versions 1 '<=' 2
+"$ANALYZE" compare-versions 1 ne 2
+"$ANALYZE" compare-versions 1 '!=' 2
+( ! "$ANALYZE" compare-versions 1 ge 2 )
+( ! "$ANALYZE" compare-versions 1 '>=' 2 )
+( ! "$ANALYZE" compare-versions 1 eq 2 )
+( ! "$ANALYZE" compare-versions 1 '==' 2 )
+( ! "$ANALYZE" compare-versions 1 gt 2 )
+( ! "$ANALYZE" compare-versions 1 '>' 2 )
 
-test "$($ANALYZE compare-versions 1 2)" = '1 < 2'
-test "$($ANALYZE compare-versions 2 2)" = '2 == 2'
-test "$($ANALYZE compare-versions 2 1)" = '2 > 1'
-test "$($ANALYZE compare-versions '' '')" = "'' == ''"
+test "$("$ANALYZE" compare-versions 1 2)" = '1 < 2'
+test "$("$ANALYZE" compare-versions 2 2)" = '2 == 2'
+test "$("$ANALYZE" compare-versions 2 1)" = '2 > 1'
+test "$("$ANALYZE" compare-versions '' '')" = "'' == ''"
 
 set +e
 
-$ANALYZE compare-versions 1 2; ret1=$?
-$ANALYZE compare-versions 2 2; ret2=$?
-$ANALYZE compare-versions 2 1; ret3=$?
+"$ANALYZE" compare-versions 1 2; ret1=$?
+"$ANALYZE" compare-versions 2 2; ret2=$?
+"$ANALYZE" compare-versions 2 1; ret3=$?
 
 set -e
 
-test $ret1 == 12
-test $ret2 == 0
-test $ret3 == 11
+test "$ret1" == 12
+test "$ret2" == 0
+test "$ret3" == 11

test/test-fstab-generator.sh

@@ -44,9 +44,9 @@ test_one() (
     fi
 
     if [[ "${input##*/}" =~ \.fstab\.input ]]; then
-        SYSTEMD_LOG_LEVEL=debug SYSTEMD_IN_INITRD="$initrd" SYSTEMD_SYSFS_CHECK=no SYSTEMD_PROC_CMDLINE="fstab=yes root=fstab" SYSTEMD_FSTAB="$input" SYSTEMD_SYSROOT_FSTAB="/dev/null" $generator "$out" "$out" "$out"
+        SYSTEMD_LOG_LEVEL=debug SYSTEMD_IN_INITRD="$initrd" SYSTEMD_SYSFS_CHECK=no SYSTEMD_PROC_CMDLINE="fstab=yes root=fstab" SYSTEMD_FSTAB="$input" SYSTEMD_SYSROOT_FSTAB="/dev/null" "$generator" "$out" "$out" "$out"
     else
-        SYSTEMD_LOG_LEVEL=debug SYSTEMD_IN_INITRD="$initrd" SYSTEMD_SYSFS_CHECK=no SYSTEMD_PROC_CMDLINE="fstab=no $(cat "$input")" $generator "$out" "$out" "$out"
+        SYSTEMD_LOG_LEVEL=debug SYSTEMD_IN_INITRD="$initrd" SYSTEMD_SYSFS_CHECK=no SYSTEMD_PROC_CMDLINE="fstab=no $(cat "$input")" "$generator" "$out" "$out" "$out"
     fi
 
     # The option x-systemd.growfs creates symlink to system's systemd-growfs@.service in .mount.wants directory.

test/test-sysusers.sh.in

@@ -53,7 +53,7 @@ for f in $(find "$SOURCE"/test-*.input | sort -V); do
     echo "*** Running $f"
     prepare_testdir "${f%.input}"
     cp "$f" "$TESTDIR/usr/lib/sysusers.d/test.conf"
-    $SYSUSERS --root="$TESTDIR"
+    "$SYSUSERS" --root="$TESTDIR"
 
     compare "${f%.*}" ""
 done
@@ -62,7 +62,7 @@ for f in $(find "$SOURCE"/test-*.input | sort -V); do
     echo "*** Running $f on stdin"
     prepare_testdir "${f%.input}"
     touch "$TESTDIR/etc/sysusers.d/test.conf"
-    $SYSUSERS --root="$TESTDIR" - <"$f"
+    "$SYSUSERS" --root="$TESTDIR" - <"$f"
 
     compare "${f%.*}" "on stdin"
 done
@@ -72,9 +72,9 @@ for f in $(find "$SOURCE"/test-*.input | sort -V); do
     prepare_testdir "${f%.input}"
     touch "$TESTDIR/etc/sysusers.d/test.conf"
     # this overrides test.conf which is masked on disk
-    $SYSUSERS --root="$TESTDIR" --replace=/etc/sysusers.d/test.conf - <"$f"
+    "$SYSUSERS" --root="$TESTDIR" --replace=/etc/sysusers.d/test.conf - <"$f"
     # this should be ignored
-    $SYSUSERS --root="$TESTDIR" --replace=/usr/lib/sysusers.d/test.conf - <"$SOURCE/test-1.input"
+    "$SYSUSERS" --root="$TESTDIR" --replace=/usr/lib/sysusers.d/test.conf - <"$SOURCE/test-1.input"
 
     compare "${f%.*}" "on stdin with --replace"
 done
@@ -84,9 +84,9 @@ echo "*** Testing --inline"
 prepare_testdir "$SOURCE/inline"
 # copy a random file to make sure it is ignored
 cp "$f" "$TESTDIR/etc/sysusers.d/confuse.conf"
-$SYSUSERS --root="$TESTDIR" --inline \
-          "u     u1   222 -     - /bin/zsh" \
-          "g     g1   111"
+"$SYSUSERS" --root="$TESTDIR" --inline \
+            "u     u1   222 -     - /bin/zsh" \
+            "g     g1   111"
 
 compare "$SOURCE/inline" "(--inline)"
 
@@ -95,19 +95,19 @@ echo "*** Testing --inline with --replace"
 prepare_testdir "$SOURCE/inline"
 # copy a random file to make sure it is ignored
 cp "$f" "$TESTDIR/etc/sysusers.d/confuse.conf"
-$SYSUSERS --root="$TESTDIR" \
-          --inline \
-          --replace=/etc/sysusers.d/confuse.conf \
-          "u     u1   222 -     - /bin/zsh" \
-          "g     g1   111"
+"$SYSUSERS" --root="$TESTDIR" \
+            --inline \
+            --replace=/etc/sysusers.d/confuse.conf \
+            "u     u1   222 -     - /bin/zsh" \
+            "g     g1   111"
 
 compare "$SOURCE/inline" "(--inline --replace=…)"
 
 echo "*** Testing --inline with no /etc"
 rm -rf "${TESTDIR:?}/etc"
-$SYSUSERS --root="$TESTDIR" --inline \
-          "u     u1   222 -     - /bin/zsh" \
-          "g     g1   111"
+"$SYSUSERS" --root="$TESTDIR" --inline \
+            "u     u1   222 -     - /bin/zsh" \
+            "g     g1   111"
 
 compare "$SOURCE/inline" "(--inline)"
 
@@ -136,7 +136,7 @@ for f in $(find "$SOURCE"/test-*.input | sort -V); do
     echo "*** Running $f (with login.defs)"
     prepare_testdir "${f%.input}"
     cp "$f" "$TESTDIR/usr/lib/sysusers.d/test.conf"
-    $SYSUSERS --root="$TESTDIR"
+    "$SYSUSERS" --root="$TESTDIR"
 
     # shellcheck disable=SC2050
     [ @ENABLE_COMPAT_MUTABLE_UID_BOUNDARIES@ = 1 ] && bound=555 || bound=$system_guid_max
@@ -152,7 +152,7 @@ for f in $(find "$SOURCE"/test-*.input | sort -V); do
     echo "*** Running $f (with login.defs symlinked)"
     prepare_testdir "${f%.input}"
     cp "$f" "$TESTDIR/usr/lib/sysusers.d/test.conf"
-    $SYSUSERS --root="$TESTDIR"
+    "$SYSUSERS" --root="$TESTDIR"
 
     # shellcheck disable=SC2050
     [ @ENABLE_COMPAT_MUTABLE_UID_BOUNDARIES@ = 1 ] && bound=555 || bound=$system_guid_max
@@ -166,7 +166,7 @@ for f in $(find "$SOURCE"/unhappy-*.input | sort -V); do
     echo "*** Running test $f"
     prepare_testdir "${f%.input}"
     cp "$f" "$TESTDIR/usr/lib/sysusers.d/test.conf"
-    SYSTEMD_LOG_LEVEL=info $SYSUSERS --root="$TESTDIR" 2>&1 | tail -n1 | sed -r 's/^[^:]+:[^:]+://' >"$TESTDIR/err"
+    SYSTEMD_LOG_LEVEL=info "$SYSUSERS" --root="$TESTDIR" 2>&1 | tail -n1 | sed -r 's/^[^:]+:[^:]+://' >"$TESTDIR/err"
     if ! diff -u "$TESTDIR/err"  "${f%.*}.expected-err"; then
         echo >&2 "**** Unexpected error output for $f"
         cat >&2 "$TESTDIR/err"