kickstart: document which options accept units

Submitted by Olaf Mandel on Aug. 12, 2021, 4:01 p.m. | Patch ID: 180053

Details

Message ID 20210812160133.22232-1-o.mandel@menlosystems.com
State Superseded
Headers show

Commit Message

Olaf Mandel Aug. 12, 2021, 4:01 p.m.
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 <o.mandel@menlosystems.com>
---
 documentation/ref-manual/kickstart.rst | 31 +++++++++++++++++---------
 1 file changed, 21 insertions(+), 10 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst
index fc723ccbe..b5ffb2a4e 100644
--- a/documentation/ref-manual/kickstart.rst
+++ b/documentation/ref-manual/kickstart.rst
@@ -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

Comments

Quentin Schulz Aug. 13, 2021, 8:05 a.m.
Hi Olaf,

Thanks for the patch!

On Thu, Aug 12, 2021 at 04:01:33PM +0000, o.mandel@menlosystems.com 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 <o.mandel@menlosystems.com>
> ---
>  documentation/ref-manual/kickstart.rst | 31 +++++++++++++++++---------
>  1 file changed, 21 insertions(+), 10 deletions(-)
> 
> diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst
> index fc723ccbe..b5ffb2a4e 100644
> --- a/documentation/ref-manual/kickstart.rst
> +++ b/documentation/ref-manual/kickstart.rst
> @@ -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

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.

> +   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.

> +   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".
>  

Same remark.

>  -  ``--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.

>     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

MiBytes instead of MBytes I assume.

Cheers,
Quentin
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1686): https://lists.yoctoproject.org/g/docs/message/1686
Mute This Topic: https://lists.yoctoproject.org/mt/84843235/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Olaf Mandel Aug. 13, 2021, 8:44 a.m.
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:
> On Thu, Aug 12, 2021 at 04:01:33PM +0000, o.mandel@menlosystems.com wrote:
>> --  ``--size``: The minimum partition size in MBytes. Specify an
>> [...]
>> +-  ``--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.
> 
Removed in v2. I tried to unify the format I saw in some other options, 
but yes: it makes no sense here.

> [...]
>>      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
> 
> MiBytes 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
Olaf Mandel Aug. 13, 2021, 6:36 p.m.
This is a system generated Comment: Patch 180053 was automatically marked as superseded by patch 180066.