[PATCH 1/1] doc: man-page for cp

[Simon Glass]

Hi Heinrich,

On Fri, 28 Apr 2023 at 13:43, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
>
>
> On 4/28/23 21:21, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt
> > <heinrich.schuchardt at canonical.com> wrote:
> >>
> >> Add a man-page for the cp command.
> >>
> >> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> >> ---
> >>   doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++
> >>   doc/usage/index.rst  |  1 +
> >>   2 files changed, 84 insertions(+)
> >>   create mode 100644 doc/usage/cmd/cp.rst
> >>
> >> diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst
> >> new file mode 100644
> >> index 0000000000..897c0bb7df
> >> --- /dev/null
> >> +++ b/doc/usage/cmd/cp.rst
> >> @@ -0,0 +1,83 @@
> >> +.. SPDX-License-Identifier: GPL-2.0+:
> >> +
> >> +cp command
> >> +==========
> >> +
> >> +Synopsis
> >> +--------
> >> +
> >> +::
> >> +
> >> +    mm source target count
> >> +    mm.b source target count
> >> +    mm.w source target count
> >> +    mm.l source target count
> >> +    mm.q source target count
> >
> > Is this the cp or the mm command?
>
> Thanks for reviewing. It must be cp.
>
> >
> > I think it is better to do:
> >
> > mm.<size>
> >
> > or something like that, to avoid repetition
>
> We cannot completely avoid repetition as 'cp' without postfix exists.
> With size I would associate a number.
> Having to look into multiple places to find out that there is a cp.q
> form is not helpful.

You could do:

  cp[.b | w | l | q]

I suppose

But I agree it is a bit painful

   cp[.<size>]

might be better

>
> I think the current format is the easiest way to see at a glance how to
> use the command.
>
> >
> >> +
> >> +Description
> >> +-----------
> >> +
> >> +The cp command is used to copy *count* words of memory from the *source*
> >
> > To me it is confusing to use the term 'words' here. A word typically
> > means a machine word in a computer, e.g. 32- or 64-bits.
> >
> > How about just referring to 'transfer size' or 'access size'?
>
> When hearing 'transfer size' I would think of the total number of bytes
> being transferred. How about 'chunk'?

It is better than word or transfer size, yes. But chunk seems like a
group of things and isn't quite right, I think.

Do you not like 'access size'? If not, then chunk is OK I suppose.

Regards,
Simon