Re: [PATCH]: Basic info documentation for SELinux context related commands runcon and chcon

[Jim Meyering]

Ondřej Vašík <address@hidden> wrote:
> as those commands were not documented in info documentation, I wrote
> basic info documentation for runcon and chcon command (and related
> SELinux context menu section). It is completely based on man
> documentation, I would say just the first step to have them documented.
> Patch is in attachement.

Thanks for doing that!

I've added to your patch with the following.
Please fold this into yours and add similar mark-up for runcon.
Also, it'd be good to document the exit status values that runcon uses,
as is done for at least nohup and timeout.

>From 246ef8da7b03037e1666c9a1ff479ab3fdec14e2 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Tue, 7 Oct 2008 00:03:35 +0200
Subject: [PATCH] tweak wording, add formatting like @var, @option

---
 doc/coreutils.texi |   81 ++++++++++++++++++++++++---------------------------
 1 files changed, 38 insertions(+), 43 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 5bb1f73..440e519 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -95,7 +95,7 @@
 * readlink: (coreutils)readlink invocation.     Print referent of a symlink.
 * rm: (coreutils)rm invocation.                 Remove files.
 * rmdir: (coreutils)rmdir invocation.           Remove empty directories.
-* runcon: (coreutils)runcon invocation.         Run file in specif. SELinux 
CTX.
+* runcon: (coreutils)runcon invocation.         Run in specified SELinux CTX.
 * seq: (coreutils)seq invocation.               Print numeric sequences
 * sha1sum: (coreutils)sha1sum invocation.       Print or check SHA-1 digests.
 * sha2: (coreutils)sha2 utilities.              Print or check SHA-2 digests.
@@ -425,7 +425,7 @@ Top

 SELinux context
 * chcon invocation::             Change SELinux context of file
-* runcon invocation::            Run file in specified SELinux context
+* runcon invocation::            Run a command in specified SELinux context

 Modified command invocation

@@ -12900,7 +12900,7 @@ SELinux context

 @menu
 * chcon invocation::            Change SELinux context of file
-* runcon invocation::           Run file in specified SELinux context
+* runcon invocation::           Run a command in specified SELinux context
 @end menu

 @node chcon invocation
@@ -12910,18 +12910,18 @@ chcon invocation
 @cindex changing security context
 @cindex change SELinux context

-
address@hidden changes SELinux security context of the file.
address@hidden changes the SELinux security context of the selected files.
 Synopses:

 @smallexample
-chcon address@hidden@dots{} CONTEXT @address@hidden
-chcon address@hidden@dots{} [-u USER] [-r ROLE] [-l RANGE] [-t TYPE] 
@address@hidden
-chcon address@hidden@dots{} --reference=RFILE @address@hidden
+chcon address@hidden@dots{} @var{context} @address@hidden
+chcon address@hidden@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}] 
[-t @var{type}] @address@hidden
+chcon address@hidden@dots{} address@hidden @address@hidden
 @end smallexample

-Change  the  SELinux  security  context  of each FILE to CONTEXT.  With
---reference, change the security context of each FILE to that of RFILE.
+Change the SELinux security context of each @var{file} to @var{context}.
+With @option{--reference}, change the security context of each @var{file}
+to that of @var{rfile}.

 The program accepts the following options.  Also see @ref{Common options}.

@@ -12932,13 +12932,12 @@ chcon invocation
 @opindex -h
 @opindex --no-dereference
 @cindex no dereference
-Affect symbolic links instead of any referenced file
+Affect symbolic links instead of any referenced file.

address@hidden --reference=RFILE
address@hidden address@hidden
 @opindex --reference
 @cindex reference file
-Use  RFILE’s  security  context rather than specifying a CONTEXT
-value
+Use @var{rfile}'s security context rather than specifying a @var{context} 
value.

 @item -R
 @itemx --recursive
@@ -12946,56 +12945,52 @@ chcon invocation
 @opindex --recursive
 Operate on files and directories recursively.

-Following options to modify how a hierarchy is traversed could also
-be specified. If more than one is specified, only the final one takes
-effect.
address@hidden @samp
address@hidden -H
-if a command line argument is a symbolic link  to  a  directory,
-traverse it
address@hidden -L
-traverse every symbolic link to a directory encountered
address@hidden -P
-do not traverse any symbolic links (default)
address@hidden table
address@hidden
address@hidden symlinks}.
+
address@hidden
address@hidden symlinks}.
+
address@hidden
address@hidden symlinks}.

 @item -v
 @itemx --verbose
 @opindex -v
 @opindex --verbose
 @cindex diagnostic
-Output a diagnostic for every file processed
+Output a diagnostic for every file processed.

address@hidden -u USER
address@hidden --user=USER
address@hidden -u @var{user}
address@hidden address@hidden
 @opindex -u
 @opindex --user
-Set user USER in the target security context
+Set user @var{user} in the target security context.

address@hidden -r ROLE
address@hidden --role=ROLE
address@hidden -r @var{role}
address@hidden address@hidden
 @opindex -r
 @opindex --role
-Set role ROLE in the target security context
+Set role @var{role} in the target security context.

address@hidden -t TYPE
address@hidden --type=type
address@hidden -t @var{type}
address@hidden address@hidden
 @opindex -t
 @opindex --type
-Set type TYPE in the target security context
+Set type @var{type} in the target security context.

address@hidden -l RANGE
address@hidden --range=RANGE
address@hidden -l @var{range}
address@hidden address@hidden
 @opindex -l
 @opindex --range
-Set range RANGE in the target security context
+Set range @var{range} in the target security context.

 @end table

 @exitstatus

 @node runcon invocation
address@hidden @command{runcon}: Run file in specified SELinux context
address@hidden @command{runcon}: Run a command in specified SELinux context

 @pindex runcon
 @cindex run with security context
@@ -13013,11 +13008,11 @@ runcon invocation
 current or transitioned security context modified by one or more of LEVEL,
 ROLE, TYPE and USER.

-If  none  of -c, -t, -u, -r, or -l, is specified, the first argument is
-used as the complete context.  Any additional arguments  after  COMMAND
+If none of -c, -t, -u, -r, or -l, is specified, the first argument is
+used as the complete context.  Any additional arguments after COMMAND
 are interpreted as arguments to the command.

-With neither  CONTEXT nor COMMAND, print the current security context.
+With neither CONTEXT nor COMMAND, print the current security context.

 The program accepts the following options.  Also see @ref{Common options}.

--
1.6.0.2.307.gc427