fileio: add brief explanations for flags

[thirdparty/systemd.git] / man / halt.xml

diff --git a/man/halt.xml b/man/halt.xml
index f425ebdb8e37577e95543c1501dcff7ac8dc2484..f811b1034848c7c9dcf1c1ee919a55d574561328 100644 (file)
--- a/man/halt.xml
+++ b/man/halt.xml
@@ -1,28 +1,7 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % entities SYSTEM "custom-entities.ent" >
-%entities;
-]>
-
-<!--
-  This file is part of systemd.
-
-  Copyright 2010 Lennart Poettering
-
-  systemd is free software; you can redistribute it and/or modify it
-  under the terms of the GNU Lesser General Public License as published by
-  the Free Software Foundation; either version 2.1 of the License, or
-  (at your option) any later version.
-
-  systemd is distributed in the hope that it will be useful, but
-  WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-  Lesser General Public License for more details.
-
-  You should have received a copy of the GNU Lesser General Public License
-  along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
 <refentry id="halt"
     xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -30,15 +9,6 @@
   <refentryinfo>
     <title>halt</title>
     <productname>systemd</productname>
-
-    <authorgroup>
-      <author>
-        <contrib>Developer</contrib>
-        <firstname>Lennart</firstname>
-        <surname>Poettering</surname>
-        <email>lennart@poettering.net</email>
-      </author>
-    </authorgroup>
   </refentryinfo>
 
   <refmeta>
@@ -71,9 +41,8 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>halt</command>, <command>poweroff</command>,
-    <command>reboot</command> may be used to halt, power-off or reboot
-    the machine.</para>
+    <para><command>halt</command>, <command>poweroff</command>, <command>reboot</command> may be used to
+    halt, power-off, or reboot the machine. All three commands take the same options.</para>
 
   </refsect1>
 
@@ -115,8 +84,13 @@
         <term><option>-f</option></term>
         <term><option>--force</option></term>
 
-        <listitem><para>Force immediate halt, power-off, reboot. Do
-        not contact the init system.</para></listitem>
+        <listitem><para>Force immediate halt, power-off, or reboot. When
+        specified once, this results in an immediate but clean shutdown
+        by the system manager. When specified twice, this results in an
+        immediate shutdown without contacting the system manager. See the
+        description of <option>--force</option> in
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for more details.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -135,6 +109,14 @@
         entry.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>-n</option></term>
+        <term><option>--no-sync</option></term>
+
+        <listitem><para>Don't sync hard disks/storage media before
+        halt, power-off, reboot.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--no-wall</option></term>
 
@@ -154,8 +136,15 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>These are legacy commands available for compatibility
-    only.</para>
+    <para>These commands are implemented in a way that preserves basic compatibility with the original SysV
+    commands.  <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    verbs <command>halt</command>, <command>poweroff</command>, <command>reboot</command> provide the same
+    functionality with some additional features.</para>
+
+    <para>Note that on many SysV systems <command>halt</command> used to be synonymous to
+    <command>poweroff</command>, i.e. both commands would equally result in powering the machine off. systemd
+    is more accurate here, and <command>halt</command> results in halting the machine only (leaving power
+    on), and <command>poweroff</command> is required to actually power it off.</para>
   </refsect1>
 
   <refsect1>