[coreutils] [PATCH] doc: split: add examples showing how to use the new option

[Jim Meyering]

Here's a proposed addition to the texinfo manual:

>From a83f05b6e91bb248ed0efc6585854f9785ccbda1 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Fri, 17 Dec 2010 21:58:33 +0100
Subject: [PATCH] doc: split: add examples showing how to use the new option

* doc/coreutils.texi (split invocation): Add examples.
---
 doc/coreutils.texi |   61 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 61 insertions(+), 0 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 76fdce1..00a5575 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -3049,6 +3049,67 @@ split invocation

 @exitstatus

+Here are a few examples to illustrate how the
+@option{--number} (@option{-n}) option works:
+
+Notice how, by default, one line may be split onto two or more:
+
+@example
+$ seq -w 6 10 > k; split -n3 k; head xa?
+==> xaa <==
+06
+07
+==> xab <==
+
+08
+0
+==> xac <==
+9
+10
+@end example
+
+Use the "l/" modifier to suppress that:
+
+@example
+$ seq -w 6 10 > k; split -nl/3 k; head xa?
+==> xaa <==
+06
+07
+
+==> xab <==
+08
+09
+
+==> xac <==
+10
+@end example
+
+Use the "r/" modifier to distribute lines in a round-robin fashion:
+
+@example
+$ seq -w 6 10 > k; split -nr/3 k; head xa?
+==> xaa <==
+06
+09
+
+==> xab <==
+07
+10
+
+==> xac <==
+08
+@end example
+
+You can also extract just the Kth chunk.
+This extracts and prints just the 7th "chunk" of 33:
+
+@example
+$ seq 100 > k; split -nl/7/33 k
+20
+21
+22
+@end example
+

 @node csplit invocation
 @section @command{csplit}: Split a file into context-determined pieces
--
1.7.3.4