man: use paragraphs in descriptions of /tmp and /var/tmp

We have three somewhat separate ideas: what the directory is for, what $TMPDIR is for, and security considerations.
Let's use paragraphs.

Also, conjunctions in titles aren't capitalized usually.

diff --git a/docs/TEMPORARY_DIRECTORIES.md b/docs/TEMPORARY_DIRECTORIES.md
index 5bb24fa3eecd33aa40d2253cb05f94f1ad0ab4fc..c0f945c8851cf57f0a66783a191297e21524c6dc 100644 (file)
--- a/docs/TEMPORARY_DIRECTORIES.md
+++ b/docs/TEMPORARY_DIRECTORIES.md
@@ -1,10 +1,10 @@
 ---
-title: Using /tmp/ And /var/tmp/ Safely
+title: Using /tmp/ and /var/tmp/ Safely
 category: Interfaces
 layout: default
 ---
 
-# Using `/tmp/` And `/var/tmp/` Safely
+# Using `/tmp/` and `/var/tmp/` Safely
 
 `/tmp/` and `/var/tmp/` are two world-writable directories Linux systems
 provide for temporary files. The former is typically on `tmpfs` and thus

diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
index 48114394c44e3b1615a5842c751726faf65b7f2b..2c80c2c1a9d1c777d92456fe96ec6e0231b6a947 100644 (file)
--- a/man/file-hierarchy.xml
+++ b/man/file-hierarchy.xml
@@ -127,20 +127,23 @@
         <term><filename>/tmp/</filename></term>
         <listitem><para>The place for small temporary files. This directory is usually mounted as a
         <literal>tmpfs</literal> instance, and should hence not be used for larger files. (Use
-        <filename>/var/tmp/</filename> for larger files.) Since the directory is accessible to other users of
-        the system, it is essential that this directory is only written to with the <citerefentry
-        project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-        <citerefentry
-        project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
-        related calls. This directory is usually flushed at boot-up. Also, files that are not accessed within
-        a certain time are usually automatically deleted. If applications find the environment variable
-        <varname>$TMPDIR</varname> set, they should prefer using the directory specified in it over directly
-        referencing <filename>/tmp/</filename> (see <citerefentry
+        <filename>/var/tmp/</filename> for larger files.) This directory is usually flushed at boot-up. Also,
+        files that are not accessed within a certain time may be automatically deleted.</para>
+
+        <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
+        the directory specified in it instead of <filename>/tmp/</filename> (see <citerefentry
         project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
         <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE
-        Std 1003.1</ulink> for details). For further details about this directory, see <ulink
-        url="https://systemd.io/TEMPORARY_DIRECTORIES">Using /tmp/ And /var/tmp/
-        Safely</ulink>.</para></listitem>
+        Std 1003.1</ulink> for details).</para>
+
+        <para>Since <filename>/tmp/</filename> is accessible to other users of the system, it is essential
+        that files and subdirectories under this directory are only created with <citerefentry
+        project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+        <citerefentry
+        project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+        and similar calls. For more details, see <ulink url="https://systemd.io/TEMPORARY_DIRECTORIES">Using
+        /tmp/ and /var/tmp/ Safely</ulink>.</para>
+        </listitem>
       </varlistentry>
 
     </variablelist>
@@ -334,20 +337,22 @@
         <term><filename>/var/tmp/</filename></term>
         <listitem><para>The place for larger and persistent temporary files. In contrast to
         <filename>/tmp/</filename>, this directory is usually mounted from a persistent physical file system
-        and can thus accept larger files. (Use <filename>/tmp/</filename> for smaller files.) This directory
-        is generally not flushed at boot-up, but time-based cleanup of files that have not been accessed for
-        a certain time is applied. The same security restrictions as with <filename>/tmp/</filename> apply,
-        and hence only <citerefentry
+        and can thus accept larger files. (Use <filename>/tmp/</filename> for small ephemeral files.) This
+        directory is generally not flushed at boot-up, but time-based cleanup of files that have not been
+        accessed for a certain time is applied.</para>
+
+        <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
+        the directory specified in it instead of <filename>/var/tmp/</filename> (see <citerefentry
+        project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details).</para>
+
+        <para>The same security restrictions as with <filename>/tmp/</filename> apply: <citerefentry
         project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
         <citerefentry
-        project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
-        similar calls should be used to make use of this directory.  If applications find the environment
-        variable <varname>$TMPDIR</varname> set, they should prefer using the directory specified in it over
-        directly referencing <filename>/var/tmp/</filename> (see <citerefentry
-        project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
-        details). For further details about this directory, see <ulink
-        url="https://systemd.io/TEMPORARY_DIRECTORIES">Using /tmp/ And /var/tmp/
-        Safely</ulink>.</para></listitem>
+        project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+        and similar calls should be used. For further details about this directory, see <ulink
+        url="https://systemd.io/TEMPORARY_DIRECTORIES">Using /tmp/ and /var/tmp/ Safely</ulink>.</para>
+        </listitem>
       </varlistentry>
 
     </variablelist>