Re: Errors in man pages, here: st.4.po: Wording

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Kai,

On Mon, 20 Apr 2020 at 20:49, "Kai Mäkisara (Kolumbus)"
<kai.makisara@kolumbus.fi> wrote:
>
> Hello,
>
> > On 20. Apr 2020, at 21.25, Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> >
> > Hello Kai,
> >
> > On Mon, 20 Apr 2020 at 17:59, "Kai Mäkisara (Kolumbus)"
> > <kai.makisara@kolumbus.fi> wrote:
> >>
> >>
> >>
> >>> On 20. Apr 2020, at 12.48, Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> >>>
> >>> [CC += Kai]
> >>>
> >>> On 4/19/20 8:48 AM, Helge Kreutzmann wrote:
> >>>> Dear manpages maintainers.
> >>>>
> >> ...
> >>>> **
> >>>>
> >>>> media → data
> >>>>
> >>>> msgid "Go to the end of the recorded media (for appending files)."
> >>>>
> >> End of media is the end of the tape. End of recorded media means
> >> after the last record/filemark that has been written to the tape. Usually
> >> (not always) you can write more data after what has been written
> >> so far. End of recorded media is standard tape terminology.
> >>
> >>>> --
> >>>> drive → media
> >>>>
> >>>> "B<GMT_WR_PROT>(I<x>): The drive is write-protected.  For some drives this "
> >>>> "can also mean that the drive does not support writing on the current medium "
> >>>> "type."
> >>>
> >> This basically means that the drive refuses to write to the media. It can be
> >> write-protected by the user. The additional text hints at the possibility
> >> that the drive can only read the media type in the drive. It is quite
> >> common that drives can read, for instance, several old formats
> >> (usually with smaller capacity) but can write only the newest types.
> >> Many times the user may not know very well the properties of the
> >> drive and wonders, why can’t I write even if the tape can be read
> >> and the write protect tab is off.
> >
> > So, if I understand right, then no changes to the wording are required?
> >
> I don’t think changes are necessarily needed. I don’t find any errors
> here. But when the text is not clear to readers, I always ask myself,
> should it be made clearer. I have understood that the man pages
> must be precise, but not too long. The requirements are different
> for the different sections of man pages. For instance, section 1 is
> meant for “ordinary” users but section 4 is for low-level interface
> to device drivers. I think we can assume that the users of
> section 4 have some technical knowledge about the device they
> are interested in programming.

Agreed.

> So, I don’t think changes are necessary. But I don’t object if someone
> wants to enhance the descriptions

> Okay.

> as long as they are precise and not too long.

Rather like your mails :-).

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/