all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Eli Zaretskii <eliz@gnu.org>
To: Richard Hansen <rhansen@rhansen.org>
Cc: 55815@debbugs.gnu.org, monnier@iro.umontreal.ca
Subject: bug#55815: [PATCH] bindat: Improve str, strz documentation
Date: Mon, 06 Jun 2022 13:59:44 +0300	[thread overview]
Message-ID: <83h74y83bz.fsf@gnu.org> (raw)
In-Reply-To: <3fc223d1-6dc0-6f59-1b27-d72dd8a3004e@rhansen.org> (message from Richard Hansen on Sun, 5 Jun 2022 22:22:01 -0400)

> Cc: monnier@iro.umontreal.ca
> Date: Sun, 5 Jun 2022 22:22:01 -0400
> From: Richard Hansen <rhansen@rhansen.org>
> 
>   @item str @var{len}
> -String of bytes of length @var{len}.
> +String of length @var{len}.

I think it is better to say

  Unibyte string that is @var{len} bytes long.

>   @item strz &optional @var{len}
> -Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size
> -field with length @var{len}.
> +If @var{len} is not provided: Variable-length null-terminated string.

Same here: it is better to mention the unibyte-ness up front, since
it's important.

> +If @var{len} is provided: @code{strz} behaves the same as @code{str}
> +with one difference. When unpacking, the first zero byte (null
                      ^^
Our conventions are to leave two spaces between sentences.

Also, for consistency, I suggest to use "null byte" everywhere, to
avoid potential confusion of non-native English speakers.

Thanks.





  reply	other threads:[~2022-06-06 10:59 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-06-06  2:22 bug#55815: [PATCH] bindat: Improve str, strz documentation Richard Hansen
2022-06-06 10:59 ` Eli Zaretskii [this message]
2022-06-06 23:31   ` Richard Hansen
2022-06-07 16:30     ` Eli Zaretskii
2022-06-07 18:17       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-06-08  4:16       ` Richard Hansen
2022-06-09  7:30         ` Eli Zaretskii

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=83h74y83bz.fsf@gnu.org \
    --to=eliz@gnu.org \
    --cc=55815@debbugs.gnu.org \
    --cc=monnier@iro.umontreal.ca \
    --cc=rhansen@rhansen.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.