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

3 views
Skip to first unread message

bril… via monorail

unread,
Dec 13, 2021, 1:19:49 PM12/13/21
to webp-d...@webmproject.org
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

unread,
Dec 13, 2021, 1:43:53 PM12/13/21
to webp-d...@webmproject.org
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/
Reply all
Reply to author
Forward
0 new messages