Re: [Xen-devel] [MULTIBOOT2 DOC PATCH 02/10] multiboot2: Clarify meaning of information request header tag

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 09/06/2016 21:30, Daniel Kiper wrote:
> Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  doc/multiboot.texi |   20 ++++++++++++--------
>  1 file changed, 12 insertions(+), 8 deletions(-)
>
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index 27e5a2f..a7e3584 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -443,15 +443,19 @@ u32[n]  | mbi_tag_types     |
>  @end group
>  @end example
>  
> -@samp{mbi_tag_types} is an array of u32 each one representing an information
> -request
> -If this tag is present and @samp{optional} is set to @samp{0} information
> -conveyed by requested tag types must be present. If bootloader is unable
> -to supply this information it must fail with an error
> +@samp{mbi_tag_types} is an array of u32 each one representing an information request.

"u32's, each"

>  
> -Note: it doesn't garantee that any tags of type @samp{mbi_tag_types} will
> -actually be present. E.g. on a videoless system even if you requested tag
> -@samp{8} no tags of type @samp{8} will be present in mbi.
> +If this tag is present and @samp{optional} is set to @samp{0} bootloader must

", the bootloader"

> +support (understand meaning of) requested tag(s) and be able to provide relevant

"the requested".  I don't think you need to explain what supported
means, so I would just drop the brackets entirely.

> +information to image if it is available. If bootloader do not understand meaning

"the image".  "the bootloader does not". "the meaning".

> +of requested tag(s) it must fail with an error. However, if it support a given

"the requested".  "supports".

> +tag(s) but information conveyed by it/them is not available bootloader can do not

"a given tag(s)" is an odd way of phrasing this.  I would recommend just
"supports a given tag, but the information requested by it is".

"available, the bootloader can't provide the requested".

> +provide requested tag(s) in Multiboot information structure and proceed further.

"in the Multiboot".  What do you mean by "and proceed further" in this
case?  It also doesn't parse.  I presume you mean that it is legal for
the bootloader to not provide the requested information, but may
continue booting.

> +
> +Note: Above means that there is not guarantee that any tags of type @samp{mbi_tag_types}

"The above", "there is no guarentee"

> +will actually be present. E.g. on a videoless system even if you requested tag @samp{8}
> +and bootloader support it no tags of type @samp{8} will be present in Multiboot

"the bootloader supports it, no".  "The Multiboot".

~Andrew

> +information structure.
>  
>  
>  @node Address header tag