From rfg@tristatelogic.com  Thu Mar 28 03:21:16 2013
Return-Path: <rfg@tristatelogic.com>
Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115])
	by hub.freebsd.org (Postfix) with ESMTP id 4667BC03
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2013 03:21:16 +0000 (UTC)
	(envelope-from rfg@tristatelogic.com)
Received: from outgoing.tristatelogic.com (segfault.tristatelogic.com [69.62.255.118])
	by mx1.freebsd.org (Postfix) with ESMTP id 2A2A1396
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2013 03:21:15 +0000 (UTC)
Received: by segfault.tristatelogic.com (Postfix, from userid 1237)
	id F349B3B3F7; Wed, 27 Mar 2013 20:21:11 -0700 (PDT)
Message-Id: <20130328032111.F349B3B3F7@segfault.tristatelogic.com>
Date: Wed, 27 Mar 2013 20:21:11 -0700 (PDT)
From: Ronald F.Guilmette <rfg@tristatelogic.com>
Reply-To: Ronald F.Guilmette <rfg@tristatelogic.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc: rfg@tristatelogic.com
Subject: dd(1) man page is unclear about semantics of conv=sync
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         177429
>Category:       docs
>Synopsis:       dd(1) man page is unclear about semantics of conv=sync
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 28 03:30:00 UTC 2013
>Closed-Date:    
>Last-Modified:  Sat Mar 30 13:44:44 UTC 2013
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 9.1-RELEASE amd64
>Organization:
entr0py
>Environment:

FreeBSD 9.1-RELEASE amd64

>Description:

The man page for dd(1) describes the "sync" parameter of the "conv=" option
thusly:

              sync     Pad every input block to the input buffer size.  Spaces
                       are used for pad bytes if a block oriented conversion
                       value is specified, otherwise NUL bytes are used.

This verbage is entirely unclear. What is a "block oriented conversion value"
and how would a user know whether or not he had specified one?

The man page should make this more clear & explicit.

>How-To-Repeat:

man 1 dd

>Fix:

I don't know what the fix is because I don't have the vaguest idea what a
"block oriented conversion value" is.

>Release-Note:
>Audit-Trail:

From: Peter Pentchev <roam@ringlet.net>
To: "Ronald F.Guilmette" <rfg@tristatelogic.com>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/177429: dd(1) man page is unclear about semantics of
 conv=sync
Date: Fri, 29 Mar 2013 15:18:35 +0200

 --OXfL5xGRrasGEqWY
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 Well, the "conversion value" is the set of all parameters that you have
 supplied to "conv" - you can supply more than one using commas.  And I
 think that "block-oriented" should mean that some of the things that you
 have specified say that the output should be in blocks - either that it
 is in blocks by default (and you have *not* requested unblocking it by
 using "ascii", "oldascii" or "unblock"), or that you've requested that
 dd(1) make it into blocks using one of the "block", "ebcdic", "ibm",
 "oldebcdic" and "oldibm" conversion specifiers.
 
 Of course, I could be wrong, but that's how I myself understand the
 manual page.
 
 G'luck,
 Peter
 
 --=20
 Peter Pentchev	roam@ringlet.net roam@FreeBSD.org p.penchev@storpool.com
 PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 Key fingerprint 2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
 No language can express every thought unambiguously, least of all this one.
 
 --OXfL5xGRrasGEqWY
 Content-Type: application/pgp-signature; name="signature.asc"
 Content-Description: Digital signature
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.12 (GNU/Linux)
 
 iQIcBAEBCAAGBQJRVZSnAAoJEGUe77AlJ98TpmEP/RrJ4OU7UR2dGVPUaytgBHEi
 TChwd7dyi6p49CRhdlnnnDSEnLqHzhE5KQN1did21fIPSX5uTVaca3J21quKL9hG
 6bU86vgrDNS4BD71AH1r5cpx/+6gncGYuy0ic/qo0MlbozasSzfzE7pVp7DTFko7
 LgWeBTUHw6tdDKxul9kP5uiRMBYdT95zSGDoltRx2rdtY9JtBpwyFbnZtXmccxFM
 QsnCt922G80pqL6gVpLwx0kUMa7L9MWQGGVUPydg8ExH/WZb3AfwZgFlykqahJHQ
 6t+q9BOt668Jca+CsWrbJ0V5DNo5cUf7p6kvA+YdduBe2+g/N9EZu+veMwVK7xQe
 b3BmdnUY2beQ/ZbbW1Kw/6sbevBuHkXNlIP2DTVDDQVuhyFaEYt5t00bXjER1PXD
 XoTJwkNdVB7cnpdRsmGPK2Iy1b+Yul6yxBymMRybzUTBB64JIivd+wLnLOKhgXQ1
 Zx/zd8vnm8DPZz3vNQK1sWqt5d95k5yLk/hFqZ+5ZhMJ6zd0FmnazPiNEPRk9wFt
 ooKimDTsAYaw4UyFMjPSDy5sAqh6JnO8MzWmuUjd9p0kvDhhYhHBWrv9ZvI7qqQi
 +ScXn3fhFztMVyG0FuxJVf/xRkHJ46CEHVpXmHHdIN4syncN8pn6TYcLm8U0qgO8
 7eOt/UVjlza4uiVUkg+J
 =m9Qy
 -----END PGP SIGNATURE-----
 
 --OXfL5xGRrasGEqWY--

From: "Ronald F. Guilmette" <rfg@tristatelogic.com>
To: Peter Pentchev <roam@ringlet.net>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/177429: dd(1) man page is unclear about semantics of conv=sync
Date: Fri, 29 Mar 2013 13:56:51 -0700

 In message <20130329131835.GA15952@straylight.m.ringlet.net>, you wrote:
 
 >Of course, I could be wrong, but that's how I myself understand the
 >manual page.
 
 Thank you, but I think that the important point here is that the man
 page should be clear about all this, so that people can use the tool
 without guessing as to the semantics, and without having to rely on
 additional sources of information about the semantics (e.g. the source
 code).
 
 
 Regards,
 rfg
>Unformatted:
