Issue 546 in webp: Inaccurate file format byte snippets in documentation

[bril… via monorail]

Status: New
Owner: ----
Labels: Type-Defect Priority-Medium

New issue 546 by bril...@hotmail.com: Inaccurate file format byte snippets in documentation
https://bugs.chromium.org/p/webp/issues/detail?id=546

I believe the "code snippet" sections in the specification to be irritating and confusing:

While the code snippet headings clearly state "bits 0 to 32", the rows below in the code snippets don't adhere to that format (see image attached, left panel).

I suggest to improve readability of the WebP specification by ...

(a)
outputting a separate line for each 4 bytes if the number of bytes is fixed and less than 13 bytes (i.e. three rows max)

(b)
using the ┊ Box Drawings Light Quadruple Dash Vertical Unicode character as line delimiters in the code snippet if the number of bytes is unknown or exceeds 12 bytes

For an example, please refer to image attached, right panel.

Attachments:
WebP File Format snippets.png 204 KB

--
You received this message because:
1. The project was configured to send all issue notifications to this address

You may adjust your notification preferences at:
https://bugs.chromium.org/hosting/settings

[jz… via monorail]

Updates:
Owner: jz...@google.com
Status: Accepted

Comment #1 on issue 546 by jz...@google.com: Inaccurate file format byte snippets in documentation
https://bugs.chromium.org/p/webp/issues/detail?id=546#c1

Thanks for the suggestions. This was loosely based on rfc-like ascii-art tables with some things like ChunkHeader() not done to scale as it's defined separately, but you're right this could be self-contained.

As part of the image/webp registration [1] I've been asked to embed this information in that doc so I expect there will be some more clean up here.

> using the ┊ Box Drawings Light Quadruple Dash Vertical Unicode character ...

I think '...' would work to keep the source doc as ASCII text.

[1] https://datatracker.ietf.org/doc/draft-zern-webp/

[Git Watcher via monorail]

Updates:
Status: Fixed

Comment #2 on issue 546 by Git Watcher: Inaccurate file format byte snippets in documentation
https://bugs.chromium.org/p/webp/issues/detail?id=546#c2

The following revision refers to this bug:
https://chromium.googlesource.com/webm/libwebp/+/70fe3063a5ef3368e26ecab9d4e770bca278ccca

commit 70fe3063a5ef3368e26ecab9d4e770bca278ccca
Author: James Zern <jz...@google.com>
Date: Tue Aug 02 01:44:26 2022

webp-container-spec.txt: rightsize table entries

Use the correct number of lines for fixed width entries like
ChunkHeader(). ':' is used instead of '|' for variable length entries.

Bug: webp:546
Change-Id: I6ec60af674c0777d5ea6ae99c8aa3c7854ddd9f9
Fixed: webp:546

[modify] https://crrev.com/70fe3063a5ef3368e26ecab9d4e770bca278ccca/doc/webp-container-spec.txt

[jz… via monorail]

Comment #3 on issue 546 by jz...@google.com: Inaccurate file format byte snippets in documentation
https://bugs.chromium.org/p/webp/issues/detail?id=546#c3

Thanks again for the report. In the end, rather than the unicode character, I used a colon (':') which is common in ASCII tables of this type.

[bril… via monorail]

Comment #4 on issue 546 by bril...@hotmail.com: Inaccurate file format byte snippets in documentation
https://bugs.chromium.org/p/webp/issues/detail?id=546#c4

Excellent work! Thank you.