Re: [netbsd-10] src bus_dma.9 copyedit

[Valery Ushakov <uwe%stderr.spb.ru@localhost>]

On Sat, Oct 05, 2024 at 05:17:59 +0000, Van Ly wrote:

> Valery Ushakov <uwe%stderr.spb.ru@localhost> writes:
> 
> > On Fri, Oct 04, 2024 at 18:58:39 +0000, Van Ly wrote:
> >
> >> => http://sdf.org/~van.ly/art/bus-dma-9-copyedit.jpeg
> >
> > I don't think so.  "Exclusive" here means that the given flag is
> > mutually exclusive with another flag.  It doesn't make sense to
> > combine nocache and prefetchable exclusive and that's what the
> > highlighted sentences say.
>
> I haven't made the cognitive effort.  The indenting in the presentation
> and separation distance of tokens had my eyes wanting to group them that
> way on skim reading, perhaps an xor flag demonstration gets the intended
> point across succinctly
>
>  1              BUS_DMA_NOCACHE   This flag is a hint to machine-
>  2                                dependent code.  If possible, map the
>  3                                memory uncached.  This flag may be
>  4                                useful in the case that the memory
>  5                                cache causes unexpected behavior of the
>  6                                device.
>  7
>  8                                Exclusive with BUS_DMA_PREFETCHABLE.
>  9              BUS_DMA_PREFETCHABLE
> 10                                This flag is a hint to machine-
> 11                                dependent code.  If possible, map the
> 12                                memory prefetchable/write-combining.
> 13
> 14                                Exclusive with BUS_DMA_NOCACHE.

Yeah, .Pp and -compact don't mix too well.

(I never quite understood the heavy use of -compact in our man pages.
I'd chalk it up to the cargo cult approach that people seem to take
when it comes to man pages, copy-pasting bad practices and markup
errors all over the place).

Anyway, unfortunately it's not an isolated fix, the whole man page
needs markup revamp.  I'll try to find time.

-uwe