sfdisk: update docs, add examples to the man page

Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/disk-utils/sfdisk.8.adoc b/disk-utils/sfdisk.8.adoc
index 35fac4eb06d824bd973bf35b815484681733f160..0fa1a0228121354caab8dad94e816ed99b3ac9e3 100644 (file)
--- a/disk-utils/sfdisk.8.adoc
+++ b/disk-utils/sfdisk.8.adoc
@@ -252,9 +252,9 @@ ____
 
 where each line fills one partition descriptor.
 
-Fields are separated by whitespace, comma or semicolon possibly followed by whitespace; initial and trailing whitespace is ignored. Numbers can be octal, decimal or hexadecimal; decimal is the default. When a field is absent, empty or specified as '-' a default value is used. But when the *-N* option (change a single partition) is given, the default for each field is its previous value.
+Fields are separated by whitespace, comma (recommended) or semicolon possibly followed by whitespace; initial and trailing whitespace is ignored. Numbers can be octal, decimal or hexadecimal; decimal is the default. When a field is absent, empty or specified as '-' a default value is used. But when the *-N* option (change a single partition) is given, the default for each field is its previous value.
 
-The default value of _start_ is the first non-assigned sector aligned according to device I/O limits. The default start offset for the first partition is 1 MiB. The offset may be followed by the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is interpreted as offset in bytes.
+The default value of _start_ is the first non-assigned sector aligned according to device I/O limits. The default start offset for the first partition is 1 MiB. The offset may be followed by the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is interpreted as offset in bytes. Since v2.38 when the -N option (change a single partition) is given, a '{plus}' can be used to enlarge partition by move start of the partition if there is a free space before the partition.
 
 //TRANSLATORS: Keep {plus} untranslated.
 The default value of _size_ indicates "as much as possible"; i.e., until the next partition or end-of-device. A numerical argument is by default interpreted as a number of sectors, however if the size is followed by one of the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is interpreted as the size of the partition in bytes and it is then aligned according to the device I/O limits. A '{plus}' can be used instead of a number to enlarge the partition as much as possible. Note '{plus}' is equivalent to the default behaviour for a new partition; existing partitions will be resized as required.
@@ -305,7 +305,9 @@ ____
 
 The _device_ field is optional. *sfdisk* extracts the partition number from the device name. It allows specifying the partitions in random order. This functionality is mostly used by *--dump*. Don't use it if you are not sure.
 
-The _value_ can be between quotation marks (e.g., name="This is partition name"). The currently supported fields are:
+The _value_ can be between quotation marks (e.g., name="This is partition name"). The fields *start=* and *size=* support '{plus}' and '-' in the same way as *Unnamed-fields format*.
+
+The currently supported fields are:
 
 **start=**__number__::
 The first non-assigned sector aligned according to device I/O limits. The default start offset for the first partition is 1 MiB. The offset may be followed by the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is interpreted as offset in bytes.
@@ -401,6 +403,29 @@ Since version 2.26 *sfdisk* no longer provides the *-R* or *--re-read* option to
 
 Since version 2.26 *sfdisk* does not provide the *--DOS*, *--IBM*, *--DOS-extended*, *--unhide*, *--show-extended*, *--cylinders*, *--heads*, *--sectors*, *--inside-outer*, *--not-inside-outer* options.
 
+== EXAMPLES
+
+*sfdisk --list --label-nested=mbr /dev/sda*::
+Print protective MBR on device with GPT disk label.
+
+*echo -e ',10M,L\n,10M,L\n,,+\n' | sfdisk /dev/sdc*::
+Create three Linux partitions, with the default start, the size of the first two partitions is 10MiB, and the last partition fills all available space on the device.
+
+*echo -e 'size=10M, type=L\n size=10M, type=L\n size=+\n' | sfdisk /dev/sdc*::
+The same as the previous example, but in named-fields format.
+
+*echo -e 'type=swap' | sfdisk -N 3 /dev/sdc*::
+Set typf of the 3rd partition to 'swap'.
+
+*sfdisk --part-type /dev/sdc 3 swap*::
+The same as the previous example, but without script use.
+
+*sfdisk --delete /dev/sdc 2*::
+Delete 2nd partition.
+
+*echo "+,+" | sfdisk -N 3 --move-data /dev/sdc*::
+Enlarge 3rd partition in both directions, move start to use free space before the partition and enlarge the size to use all free space after to the partition, and move partition data too.
+
 == AUTHORS
 
 mailto:kzak@redhat.com[Karel Zak]