Re: [PATCH] docs/interop: convert text files to restructuredText

["souleymane conté" <conte.souleymane@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4256 bytes --]

Hi,
Thanks a lot for your review and helpful suggestions.

I will address the following points in v2:
- Fix the typo: "Each entry look" → "Each entry looks"
- Improve the layout for the LUKS section in the visual diagram
- Check whether nested tables are possible in reStructuredText
- Update "qemu" to "QEMU" for consistency, where appropriate

I'll prepare and send a v2 shortly.

Souleymane Conte

Le jeu. 15 mai 2025 à 21:54, Eric Blake <eblake@redhat.com> a écrit :

> On Thu, May 15, 2025 at 10:24:00AM +0000, conte.souleymane@gmail.com
> wrote:
> > From: Souleymane Conte <conte.souleymane@gmail.com>
> >
> > buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
> >
> > Signed-off-by: Souleymane Conte <conte.souleymane@gmail.com>
> > ---
> >  docs/interop/index.rst                |   1 +
> >  docs/interop/{qcow2.txt => qcow2.rst} | 210 +++++++++++++++-----------
> >  2 files changed, 123 insertions(+), 88 deletions(-)
> >  rename docs/interop/{qcow2.txt => qcow2.rst} (89%)
> >
>
> As long as we're touching this file,...
>
> > +Feature name table
> > +------------------
> >
> >  The feature name table is an optional header extension that contains
> the name
> >  for features used by the image. It can be used by applications that
> don't know
> > @@ -288,7 +300,7 @@ the respective feature (e.g. because the feature was
> introduced only later) to
> >  display a useful error message.
> >
> >  The number of entries in the feature name table is determined by the
> length of
> > -the header extension data. Each entry look like this:
> > +the header extension data. Each entry look like this::
>
> s/look/looks/
>
> > @@ -377,35 +392,40 @@ Logically the layout looks like
> >
> >    +-----------------------------+
> >    | QCow2 header                |
> > +  +-----------------------------+
> >    | QCow2 header extension X    |
> > +  +-----------------------------+
> >    | QCow2 header extension FDE  |
> > +  +-----------------------------+
> >    | QCow2 header extension ...  |
> > +  +-----------------------------+
> >    | QCow2 header extension Z    |
> >    +-----------------------------+
> > +  | ...                         |
> > +  +-----------------------------+
> > +  | ...                         |
> > +  +-----------------------------+
> >    | ....other QCow2 tables....  |
> > -  .                             .
> > -  .                             .
> >    +-----------------------------+
> > -  | +-------------------------+ |
> > -  | | LUKS partition header   | |
> > -  | +-------------------------+ |
> > -  | | LUKS key material 1     | |
> > -  | +-------------------------+ |
> > -  | | LUKS key material 2     | |
> > -  | +-------------------------+ |
> > -  | | LUKS key material ...   | |
> > -  | +-------------------------+ |
> > -  | | LUKS key material 8     | |
> > -  | +-------------------------+ |
> > +  | LUKS partition header       |
> > +  +-----------------------------+
> > +  | LUKS key material 1         |
> > +  +-----------------------------+
>
> Is there no way to nest a table in .rst?
>
> > +Host cluster management
> > +-----------------------
> >
> >  qcow2 manages the allocation of host clusters by maintaining a
> reference count
> >  for each host cluster. A refcount of 0 means that the cluster is free,
> 1 means
> > @@ -453,14 +474,15 @@ Although a large enough refcount table can reserve
> clusters past 64 PB
> >  large), note that some qcow2 metadata such as L1/L2 tables must point
> >  to clusters prior to that point.
> >
> > -Note: qemu has an implementation limit of 8 MB as the maximum refcount
> > -table size.  With a 2 MB cluster size and a default refcount_order of
> > -4, it is unable to reference host resources beyond 2 EB (61 bits); in
> > -the worst case, with a 512 cluster size and refcount_order of 6, it is
> > -unable to access beyond 32 GB (35 bits).
> > +.. note::
> > +    qemu has an implementation limit of 8 MB as the maximum refcount
>
> Should we be changing s/qemu/QEMU/ while editing this file?
>
> --
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.
> Virtualization:  qemu.org | libguestfs.org
>
>

[-- Attachment #2: Type: text/html, Size: 5639 bytes --]