dahdi_span_assignments.8: s/register/assign/

* Use the term "assignment" instead of "registration" (for spans).
* Further fixes.

Signed-off-by: Tzafrir Cohen <tzafrir.cohen@xorcom.com>
Acked-By: Russ Meyerriecks <rmeyerriecks@digium.com>

doc/dahdi_span_assignments.8

@@ -1,55 +1,82 @@
-.TH "SPAN_ASSIGNMENTS" "8" "13 Oct 2013" "" ""
+.TH "DAHDI_SPAN_ASSIGNMENTS" "8" "23 Jan 2014" "" ""
 
 .SH NAME
-dahdi_span_assignments \- handle DAHDI spans registration
+dahdi_span_assignments \- handle DAHDI spans assignments
 .SH SYNOPSIS
 
-.B dahdi_span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] <add|remove> \fIdevpath
+.B dahdi_span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] <add|remove|auto> \fB[\fIdevpath\fB...]
-\fB[\fIdevpath \fB...]
 
-.B dahdi_span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] auto
+.B dahdi_span_assignments [\-v|\-\-verbose] list \fB[\fIdevpath\fB...]
-
-.B dahdi_span_assignments [\-v|\-\-verbose] list
 
 .B dahdi_span_assignments [\-v|\-\-verbose] [\-k|\-\-key \fIkey\fB] dumpconfig
 
 .B dahdi_span_assignments \-h|\-\-help
 
 .SH DESCRIPTION
+Channels in DAHDI devices (such as DAHDI PCI cards) are groups to logical
+units called "spans" (for example: a port in a digital card is a span).
 When the kernel module parameter \fBdahdi.auto_assign_span\fR is unset,
-DAHDI devices (such as DAHDI PCI cards) that register with DAHDI don't
+DAHDI devices that register with DAHDI don't cause their spans to be
-register their spans (e.g.: each digital port is normally a span) with
+automatically assigned.
-DAHDI. This allows user-space to order DAHDI to register them to specific 
+
-span and channel numbers. This allows registering different spans out of
+This allows user-space to order DAHDI to assign them to specific span
-order.
+and channel numbers. That way, specific spans on specific DAHDI devices
+may be assigned with specific span and channel numbers \fBregardless\fR
+of the registration order of the hardware (or if all hardware is present
+at all).
 
 .B dahdi_span_assignments
-is used to register those spans or to help creating the configuration
+is used to assign those spans or to help creating the configuration
-file used in their registration:
+file used in their assignment:
 .B /etc/dahdi/assigned-spans.conf .
 
-.SH OPTIONS
+.SH SUB-COMMANDS
 
-There are several sub-commands:
+There are several sub-commands.
 
-.B add \fIdevpath \fB[\fIdevpath \fB...]
+All sub-commands take an optional list of paths to SysFS nodes of
+devices. If given, the command will only operate on those DAHDI
+devices. The default is to operate on all devices (which would normally
+be the sane case when running from the command-line).
+
+.B add \fB[\fIdevpath \fB...]
 .RS
-Parameters are paths (in SysFS) to DAHDI devices with unregistered
+Applies to all devices or to those listed on the command line.
-spans. The command will register with DAHDI according to according to
+Parameters are paths (in SysFS) to DAHDI devices with unassigned
+spans.
+
+The command will assign spans with DAHDI according to
 configuration in \fBassigned-spans.conf\fR.
+
+If no line matches the span, or if the assignment for it fails (it is
+not available) it will remain unassigned.
+
+If any of the span settings fails (the span number or range of channels
+is already in use), the program will print a message, but continue
+applying the others. In such a case you should fix assigned-spans.conf
+and re-run \fBadd\fR (or run \fBauto\fR to give those channels the
+first available range and regenerate the file with 'dahdi_genconf
+assignedspans').
 .RE
 
-.B remove \fIdevpath \fB[\fIdevpath \fB...]
+.B remove \fB[\fIdevpath \fB...]
 .RS
-Parameters are paths (in SysFS) to DAHDI devices with registered
+Applies to all devices or to those listed on the command line.
-spans. The command will unregister with DAHDI.
+Parameters are paths (in SysFS) to DAHDI devices with assigned
+spans.
+
+The command will un-assign them.
 .RE
 
-.B auto
+.B auto \fB[\fIdevpath \fB...]
 .RS
-Register all non-registered spans. Each span registers to first
+Applies to all devices or to those listed on the command line.
-available span number and channel numbers, as if
+Parameters are paths (in SysFS) to DAHDI devices with unassigned
-\fBdahdi.auto_assign_span\fR was set.
+spans.
+
+Each span is assigned to first available span number and channel
+numbers, as if \fBdahdi.auto_assign_span\fR was set. The configuration
+file doesn't affect these assignments.
 .RE
 
 .B list
@@ -59,14 +86,16 @@ List all spans in the system.
 
 .B dumpconfig
 .RS
-List all registered spans in the system in a format fit to be used in
+List all assigned spans in the system in a format fit to be used in
-\fBassigned-spans.conf\fR. Use this to generate a configuration file after
+\fBassigned\-spans.conf\fR. Use this to generate a configuration file after
-you have (perhaps manually) registered all existing spans.
+you have (automatically or manually) assigned all existing spans.
 
 .B dahdi_genconf assignedspans
 uses this command internally.
 .RE
 
+.SH OPTIONS
+
 .B \-v \-\-verbose
 .RS
 Verbose output.
@@ -74,7 +103,7 @@ Verbose output.
 
 .B \-n \-\-dry\-run
 .RS
-Don't register / unregister spans. Only print commands used to do so.
+Don't assign / un-assign spans. Only print commands used to do so.
 .RE
 
 .B \-k \fIkey
@@ -101,9 +130,9 @@ Path in SysFS to the device node.
 .RE
 .RE
 
-.SH CONFIGURATOIN
+.SH CONFIGURATION
-.B assigned-spans.conf
+.B /etc/dahdi/assigned\-spans.conf
-is a file with lines specifying registration of spans.
+is a file with lines specifying assignment of spans.
 
 Empty lines or lines beginning with '#' are ignored.
 
@@ -112,7 +141,7 @@ Each line is in the format of:
 .I ID		spanspec ...
 
 The \fIID\fR field specifies the DAHDI device and the \fIspanspecs\fR
-define how to register its spans. A line may have multiple
+define how to assign its spans. A line may have multiple
 \fIspanspecs\fR in a single line (though dumpconfig generates a
 configuration with one per line).
 
@@ -137,7 +166,7 @@ first cleaned up: '!' is replaced with '/' and any character beyond
 .SS Span Specification
 
 Each line should have one or more span specifications: this is the value
-used to register a span with DAHDI in the SysFS interface. A
+used to assign a span with DAHDI in the SysFS interface. A
 specification has three colon-separated numbers:
 
 .I rel_span_no:span_no:first_chan
@@ -159,7 +188,7 @@ The desired DAHDI span number. Must be available.
 .B first_chan
 .RS
 The desired DAHDI channel number for the first DAHDI channel in the span.
-All channels of the span will be registered following it and hence that
+All channels of the span will be assigned following it and hence that
 space must be available.
 .RE