kickstart: document which options accept units
PATCH 1/1 kickstart: document which options accept units
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
--- documentation/ref-manual/kickstart.rst | 31 +++++++++++++++++--------- 1 file changed, 21 insertions(+), 10 deletions(-)
documentation/ref-manual/kickstart.rst +21 -10
@@ -65,13 +65,18 @@ Here is an example that uses "/" as the mountpoint. The command uses Here is a list that describes other supported options you can use with the ``part`` and ``partition`` commands: -- ``--size``: The minimum partition size in MBytes. Specify an - integer value such as 500. Do not append the number with "MB". You do - not need this option if you use ``--source``. - -- ``--fixed-size``: The exact partition size in MBytes. You cannot - specify with ``--size``. An error occurs when assembling the disk - image if the partition data is larger than ``--fixed-size``. +- ``--size (in MBytes)``: The minimum partition size. Specify as an + integer value optionally followed by one of the units "k" / "K" for + kibibyte, "M" for mebibyte and "G" for gibibyte. The default unit + if none is given is "M". You do not need this option if you use + ``--source``. + +- ``--fixed-size (in MBytes)``: The exact partition size. Specify as an + integer value optionally followed by one of the units "k" / "K" for + kibibyte, "M" for mebibyte and "G" for gibibyte. The default unit + if none is given is "M". Cannot be specify together with ``--size``. + An error occurs when assembling the disk image if the partition data + is larger than ``--fixed-size``. - ``--source``: This option is a Wic-specific option that names the source of the data that populates the partition. The most common
@@ -137,7 +142,10 @@ the ``part`` and ``partition`` commands: - ``--offset (in KBytes)``: This option is a Wic-specific option that says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image build - will fail. + will fail. Specify as an integer value optionally followed by one of + the units "s" / "S" for 512Byte sector, "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "k". - ``--no-table``: This option is a Wic-specific option. Using the option reserves space for the partition and causes it to become
@@ -148,10 +156,13 @@ the ``part`` and ``partition`` commands: excludes the given relative path from the resulting image. This option is only effective with the rootfs source plugin. -- ``--extra-space``: This option is a Wic-specific option that adds +- ``--extra-space (in MBytes)``: This option is a Wic-specific option that adds extra space after the space filled by the content of the partition. The final size can exceed the size specified by the ``--size`` - option. The default value is 10 Mbytes. + option. The default value is 10 Mbytes. Specify as an integer value + optionally followed by one of the units "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "M". - ``--overhead-factor``: This option is a Wic-specific option that multiplies the size of the partition by the option's value. You must
Signature · 1 line
2.20.1
Hi Olaf,
Thanks for the patch!
Quoted 15 lines · On Thu, Aug 12, 2021 at 04:01:33PM +0000, [email protected] wrote:
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
Signed-off-by Olaf Mandel <[email protected]>--- documentation/ref-manual/kickstart.rst | 31 +++++++++++++++++--------- 1 file changed, 21 insertions(+), 10 deletions(-)documentation/ref-manual/kickstart.rst +0
-0@@ -65,13 +65,18 @@ Here is an example that uses "/" as the mountpoint. The command uses Here is a list that describes other supported options you can use with
documentation/ref-manual/kickstart.rst Here is an example that uses "/" as the mountpoint. The command uses · line 68
Quoted 10 lines
documentation/ref-manual/kickstart.rst +1
-7the ``part`` and ``partition`` commands: -- ``--size``: The minimum partition size in MBytes. Specify an - integer value such as 500. Do not append the number with "MB". You do - not need this option if you use ``--source``. - -- ``--fixed-size``: The exact partition size in MBytes. You cannot - specify with ``--size``. An error occurs when assembling the disk - image if the partition data is larger than ``--fixed-size``. +- ``--size (in MBytes)``: The minimum partition size. Specify as an
I'm not really fond of saying it's in MBytes here just to say a sentence later that it can be something else. Especially since I would understand 35K to be 35000 MBytes and not 35 KiB.
The explanation is sufficient to me, it's less confusing IMO.
In any case, if we keep it, it should say MiBytes and not MBytes since in the description you say it's mebibytes and not megabytes.
documentation/ref-manual/kickstart.rst Here is an example that uses "/" as the mountpoint. The command uses · line 74
Quoted 6 lines
documentation/ref-manual/kickstart.rst +6
-0+ integer value optionally followed by one of the units "k" / "K" for + kibibyte, "M" for mebibyte and "G" for gibibyte. The default unit + if none is given is "M". You do not need this option if you use + ``--source``. + +- ``--fixed-size (in MBytes)``: The exact partition size. Specify as an
Same remark.
Quoted 9 lines
documentation/ref-manual/kickstart.rst +5
-0+ integer value optionally followed by one of the units "k" / "K" for + kibibyte, "M" for mebibyte and "G" for gibibyte. The default unit + if none is given is "M". Cannot be specify together with ``--size``. + An error occurs when assembling the disk image if the partition data + is larger than ``--fixed-size``. - ``--source``: This option is a Wic-specific option that names the source of the data that populates the partition. The most common
documentation/ref-manual/kickstart.rst the ``part`` and ``partition`` commands: · line 149
Quoted 9 lines
documentation/ref-manual/kickstart.rst +4
-1@@ -137,7 +142,10 @@ the ``part`` and ``partition`` commands: - ``--offset (in KBytes)``: This option is a Wic-specific option that says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image build - will fail. + will fail. Specify as an integer value optionally followed by one of + the units "s" / "S" for 512Byte sector, "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "k".
Same remark.
documentation/ref-manual/kickstart.rst the ``part`` and ``partition`` commands: · line 159
Quoted 8 lines
documentation/ref-manual/kickstart.rst +1
-1- ``--no-table``: This option is a Wic-specific option. Using the option reserves space for the partition and causes it to become@@ -148,10 +156,13 @@ the ``part`` and ``partition`` commands: excludes the given relative path from the resulting image. This option is only effective with the rootfs source plugin. -- ``--extra-space``: This option is a Wic-specific option that adds +- ``--extra-space (in MBytes)``: This option is a Wic-specific option that adds
Same remark.
documentation/ref-manual/kickstart.rst the ``part`` and ``partition`` commands: · line 162
Quoted 4 lines
documentation/ref-manual/kickstart.rst +1
-1extra space after the space filled by the content of the partition. The final size can exceed the size specified by the ``--size`` - option. The default value is 10 Mbytes. + option. The default value is 10 Mbytes. Specify as an integer value
MiBytes instead of MBytes I assume.
Cheers,
Quentin
PATCH v2 1/1 kickstart: document which options accept units
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
--- documentation/ref-manual/kickstart.rst | 30 +++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-)
documentation/ref-manual/kickstart.rst +20 -10
@@ -65,13 +65,17 @@ Here is an example that uses "/" as the mountpoint. The command uses Here is a list that describes other supported options you can use with the ``part`` and ``partition`` commands: -- ``--size``: The minimum partition size in MBytes. Specify an - integer value such as 500. Do not append the number with "MB". You do - not need this option if you use ``--source``. - -- ``--fixed-size``: The exact partition size in MBytes. You cannot - specify with ``--size``. An error occurs when assembling the disk - image if the partition data is larger than ``--fixed-size``. +- ``--size``: The minimum partition size. Specify as an integer value + optionally followed by one of the units "k" / "K" for kibibyte, + "M" for mebibyte and "G" for gibibyte. The default unit if none is + given is "M". You do not need this option if you use ``--source``. + +- ``--fixed-size``: The exact partition size. Specify as an integer + value optionally followed by one of the units "k" / "K" for kibibyte, + "M" for mebibyte and "G" for gibibyte. The default unit if none is + given is "M". Cannot be specify together with ``--size``. An error + occurs when assembling the disk image if the partition data is larger + than ``--fixed-size``. - ``--source``: This option is a Wic-specific option that names the source of the data that populates the partition. The most common
@@ -134,10 +138,13 @@ the ``part`` and ``partition`` commands: - ``--align (in KBytes)``: This option is a Wic-specific option that says to start partitions on boundaries given x KBytes. -- ``--offset (in KBytes)``: This option is a Wic-specific option that +- ``--offset``: This option is a Wic-specific option that says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image build - will fail. + will fail. Specify as an integer value optionally followed by one of + the units "s" / "S" for 512Byte sector, "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "k". - ``--no-table``: This option is a Wic-specific option. Using the option reserves space for the partition and causes it to become
@@ -151,7 +158,10 @@ the ``part`` and ``partition`` commands: - ``--extra-space``: This option is a Wic-specific option that adds extra space after the space filled by the content of the partition. The final size can exceed the size specified by the ``--size`` - option. The default value is 10 Mbytes. + option. The default value is 10M. Specify as an integer value + optionally followed by one of the units "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "M". - ``--overhead-factor``: This option is a Wic-specific option that multiplies the size of the partition by the option's value. You must
Signature · 1 line
2.20.1
Hi Olaf,
Quoted 6 lines · Olaf Mandel
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
Signed-off-by Olaf Mandel <[email protected]>CC Quentin Schulz <[email protected]>
Thanks!
Quentin
PATCH v3 1/1 kickstart: document which options accept units
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
--- documentation/ref-manual/kickstart.rst | 30 +++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-)
documentation/ref-manual/kickstart.rst +20 -10
@@ -65,13 +65,17 @@ Here is an example that uses "/" as the mountpoint. The command uses Here is a list that describes other supported options you can use with the ``part`` and ``partition`` commands: -- ``--size``: The minimum partition size in MBytes. Specify an - integer value such as 500. Do not append the number with "MB". You do - not need this option if you use ``--source``. - -- ``--fixed-size``: The exact partition size in MBytes. You cannot - specify with ``--size``. An error occurs when assembling the disk - image if the partition data is larger than ``--fixed-size``. +- ``--size``: The minimum partition size. Specify as an integer value + optionally followed by one of the units "k" / "K" for kibibyte, + "M" for mebibyte and "G" for gibibyte. The default unit if none is + given is "M". You do not need this option if you use ``--source``. + +- ``--fixed-size``: The exact partition size. Specify as an integer + value optionally followed by one of the units "k" / "K" for kibibyte, + "M" for mebibyte and "G" for gibibyte. The default unit if none is + given is "M". Cannot be specify together with ``--size``. An error + occurs when assembling the disk image if the partition data is larger + than ``--fixed-size``. - ``--source``: This option is a Wic-specific option that names the source of the data that populates the partition. The most common
@@ -134,10 +138,13 @@ the ``part`` and ``partition`` commands: - ``--align (in KBytes)``: This option is a Wic-specific option that says to start partitions on boundaries given x KBytes. -- ``--offset (in KBytes)``: This option is a Wic-specific option that +- ``--offset``: This option is a Wic-specific option that says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image build - will fail. + will fail. Specify as an integer value optionally followed by one of + the units "s" / "S" for 512Byte sector, "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "k". - ``--no-table``: This option is a Wic-specific option. Using the option reserves space for the partition and causes it to become
@@ -151,7 +158,10 @@ the ``part`` and ``partition`` commands: - ``--extra-space``: This option is a Wic-specific option that adds extra space after the space filled by the content of the partition. The final size can exceed the size specified by the ``--size`` - option. The default value is 10 Mbytes. + option. The default value is 10M. Specify as an integer value + optionally followed by one of the units "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "M". - ``--overhead-factor``: This option is a Wic-specific option that multiplies the size of the partition by the option's value. You must
Signature · 1 line
2.20.1
Hi Olaf,
Quoted 6 lines · On Fri, Aug 13, 2021 at 08:48:55AM +0000, [email protected] wrote:
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
Signed-off-by Olaf Mandel <[email protected]>Reviewed-by Quentin Schulz <[email protected]>
If the content of the patch is the same as v2, there's no need to send a v3 to add my Reviewed-by, the maintainer will do it when merging the patch :)
Thanks again!
Cheers,
Quentin
Quoted 7 lines · Quentin Schulz
Hi Olaf,
Quoted 4 lines · On Fri, Aug 13, 2021 at 08:48:55AM +0000, [email protected] wrote:
Document which units are accepted as parameters for the four options that accept units. Also be pedantic about using binary instead of decimal prefixes so readers don't have to wonder.
Quoted 5 lines
Quoted 2 lines
Signed-off-by Olaf Mandel <[email protected]>Reviewed-by Quentin Schulz <[email protected]>If the content of the patch is the same as v2, there's no need to send a v3 to add my Reviewed-by, the maintainer will do it when merging the patch :)
Indeed. But that's natural to assume this when you begin. I did too :) Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hi Olaf,
Many thanks for the patch, and thanks to Quentin for the review!
documentation/ref-manual/kickstart.rst the ``part`` and ``partition`` commands: · line 147
Quoted 11 lines · On 8/13/21 10:48 AM, [email protected] wrote:
-- ``--offset (in KBytes)``: This option is a Wic-specific option that +- ``--offset``: This option is a Wic-specific option that
says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image builddocumentation/ref-manual/kickstart.rst +4
-1- will fail. + will fail. Specify as an integer value optionally followed by one of + the units "s" / "S" for 512Byte sector, "k" / "K" for kibibyte, "M" + for mebibyte and "G" for gibibyte. The default unit if none is given + is "k".
I replaced "512Byte" by "512 byte".
Don't hesitate to protest if you disagree!
and merged into the "master-next" branch.
Thanks again!
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hello Quentin,
thank you for having a look. I haven't figured out how to prepend a reply in front of the v2 patch, so replying here as a separate eMail.
Am 13.08.2021 um 10:05 schrieb Quentin Schulz:
Quoted 10 lines · On Thu, Aug 12, 2021 at 04:01:33PM +0000, [email protected] wrote:
Quoted 3 lines
-- ``--size``: The minimum partition size in MBytes. Specify an [...]
+- ``--size (in MBytes)``: The minimum partition size. Specify as anI'm not really fond of saying it's in MBytes here just to say a sentence later that it can be something else. Especially since I would understand 35K to be 35000 MBytes and not 35 KiB.
The explanation is sufficient to me, it's less confusing IMO.
Removed in v2. I tried to unify the format I saw in some other options, but yes: it makes no sense here.
Quoted 8 lines
[...]
documentation/ref-manual/kickstart.rst the ``part`` and ``partition`` commands: · line 162
Quoted 4 lines
extra space after the space filled by the content of the partition. The final size can exceed the size specified by the ``--size``
documentation/ref-manual/kickstart.rst +1
-1- option. The default value is 10 Mbytes. + option. The default value is 10 Mbytes. Specify as an integer valueMiBytes instead of MBytes I assume.
Yes. I went with just saying 10M in v2 for brevity: the explanation of that is right in the next sentence.
Thanks,
Olaf
Signature · 12 lines
Olaf Mandel Tel +49 89 189 166 0 Fax +49 89 189 166 111 [email protected] https://www.menlosystems.com Menlo Systems GmbH Bunsenstraße 5, D-82152 Martinsried Geschäftsführung: Dr Michael Mei, Dr Ronald Holzwarth USt-IdNr. DE217772017, St.-Nr. 14316170324 Amtsgericht München HRB 138145