OASIS Virtual I/O Device (VIRTIO) TC

Reading legacy chapters gives a hint about what changed, let's help readers discover this useful shortcut. Signed-off-by: Michael S. Tsirkin <mst@redhat.com> --- introduction.tex 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/introduction.tex b/introduction.tex index ac7eefa..0c076f8 100644 --- a/introduction.tex +++ b/introduction.tex @@ -126,6 +126,16 @@ Similarly, a driver MAY implement: Devices or drivers with no legacy compatibility are referred to as non-transitional devices and drivers, respectively. +subsection{Transition from earlier specification drafts} +label{intro:Transition from earlier specification drafts} + +If a device or a driver already implement the legacy interface, +some changes would have to be made to support this specification. + +In this case, it might be benefitial for the reader to focus on +sections tagged "Legacy Interface" in the section title. +These highlight the changes made since these earlier drafts. + section{Structure Specifications} Many device and driver in-memory structure layouts are documented using -- MST

On Thu, 2 Jul 2015 10:21:03 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Reading legacy chapters gives a hint about what changed,
> let's help readers discover this useful shortcut.
>
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
> introduction.tex | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
> diff --git a/introduction.tex b/introduction.tex
> index ac7eefa..0c076f8 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -126,6 +126,16 @@ Similarly, a driver MAY implement:
> Devices or drivers with no legacy compatibility are referred to as
> non-transitional devices and drivers, respectively.
>
> +\subsection{Transition from earlier specification drafts}
> +\label{intro:Transition from earlier specification drafts}
> +
> +If a device or a driver already implement the legacy interface,
> +some changes would have to be made to support this specification.

"For devices and drivers already implementing the legacy interface,
some changes will have to be made to support this specification."

> +
> +In this case, it might be benefitial for the reader to focus on

s/benefitial/beneficial/

> +sections tagged "Legacy Interface" in the section title.
> +These highlight the changes made since these earlier drafts.

", as these highlight the changes made since the earlier drafts."

> +
> \section{Structure Specifications}
>
> Many device and driver in-memory structure layouts are documented using

On Thu, 2 Jul 2015 10:21:03 +0200 "Michael S. Tsirkin" <mst@redhat.com> wrote: > Reading legacy chapters gives a hint about what changed, > let's help readers discover this useful shortcut. > > Signed-off-by: Michael S. Tsirkin <mst@redhat.com> > --- > introduction.tex 10 ++++++++++ > 1 file changed, 10 insertions(+) > > diff --git a/introduction.tex b/introduction.tex > index ac7eefa..0c076f8 100644 > --- a/introduction.tex > +++ b/introduction.tex > @@ -126,6 +126,16 @@ Similarly, a driver MAY implement: > Devices or drivers with no legacy compatibility are referred to as > non-transitional devices and drivers, respectively. > > +subsection{Transition from earlier specification drafts} > +label{intro:Transition from earlier specification drafts} > + > +If a device or a driver already implement the legacy interface, > +some changes would have to be made to support this specification. "For devices and drivers already implementing the legacy interface, some changes will have to be made to support this specification." > + > +In this case, it might be benefitial for the reader to focus on s/benefitial/beneficial/ > +sections tagged "Legacy Interface" in the section title. > +These highlight the changes made since these earlier drafts. ", as these highlight the changes made since the earlier drafts." > + > section{Structure Specifications} > > Many device and driver in-memory structure layouts are documented using

On 02/07/2015 10:29, Cornelia Huck wrote:
> On Thu, 2 Jul 2015 10:21:03 +0200
> "Michael S. Tsirkin" <mst@redhat.com> wrote:
>
>> Reading legacy chapters gives a hint about what changed,
>> let's help readers discover this useful shortcut.
>>
>> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
>> ---
>> introduction.tex | 10 ++++++++++
>> 1 file changed, 10 insertions(+)
>>
>> diff --git a/introduction.tex b/introduction.tex
>> index ac7eefa..0c076f8 100644
>> --- a/introduction.tex
>> +++ b/introduction.tex
>> @@ -126,6 +126,16 @@ Similarly, a driver MAY implement:
>> Devices or drivers with no legacy compatibility are referred to as
>> non-transitional devices and drivers, respectively.
>>
>> +\subsection{Transition from earlier specification drafts}
>> +\label{intro:Transition from earlier specification drafts}
>> +
>> +If a device or a driver already implement the legacy interface,
>> +some changes would have to be made to support this specification.
>
> "For devices and drivers already implementing the legacy interface,
> some changes will have to be made to support this specification."
>
>> +
>> +In this case, it might be benefitial for the reader to focus on
>
> s/benefitial/beneficial/
>
>> +sections tagged "Legacy Interface" in the section title.
>> +These highlight the changes made since these earlier drafts.
>
> ", as these highlight the changes made since the earlier drafts."

I prefer Michael's version for this sentence. English strongly prefers
simpler sentences, or so I was explained by native speakers. This is
unlike Italian, and my high school experience dealing with Kant suggests
that German is similar. :)

Paolo

On 02/07/2015 10:29, Cornelia Huck wrote: > On Thu, 2 Jul 2015 10:21:03 +0200 > "Michael S. Tsirkin" <mst@redhat.com> wrote: > >> Reading legacy chapters gives a hint about what changed, >> let's help readers discover this useful shortcut. >> >> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> >> --- >> introduction.tex 10 ++++++++++ >> 1 file changed, 10 insertions(+) >> >> diff --git a/introduction.tex b/introduction.tex >> index ac7eefa..0c076f8 100644 >> --- a/introduction.tex >> +++ b/introduction.tex >> @@ -126,6 +126,16 @@ Similarly, a driver MAY implement: >> Devices or drivers with no legacy compatibility are referred to as >> non-transitional devices and drivers, respectively. >> >> +subsection{Transition from earlier specification drafts} >> +label{intro:Transition from earlier specification drafts} >> + >> +If a device or a driver already implement the legacy interface, >> +some changes would have to be made to support this specification. > > "For devices and drivers already implementing the legacy interface, > some changes will have to be made to support this specification." > >> + >> +In this case, it might be benefitial for the reader to focus on > > s/benefitial/beneficial/ > >> +sections tagged "Legacy Interface" in the section title. >> +These highlight the changes made since these earlier drafts. > > ", as these highlight the changes made since the earlier drafts." I prefer Michael's version for this sentence. English strongly prefers simpler sentences, or so I was explained by native speakers. This is unlike Italian, and my high school experience dealing with Kant suggests that German is similar. :) Paolo

On Thu, 2 Jul 2015 10:34:41 +0200
Paolo Bonzini <pbonzini@redhat.com> wrote:

> >> +In this case, it might be benefitial for the reader to focus on
> >
> > s/benefitial/beneficial/
> >
> >> +sections tagged "Legacy Interface" in the section title.
> >> +These highlight the changes made since these earlier drafts.
> >
> > ", as these highlight the changes made since the earlier drafts."
>
> I prefer Michael's version for this sentence. English strongly prefers
> simpler sentences, or so I was explained by native speakers. This is
> unlike Italian, and my high school experience dealing with Kant suggests
> that German is similar. :)

Heh, I'd already have classified that as a simple sentence :) But no
objections from my side. I'd still prefer s/these/the/, though.

On Thu, 2 Jul 2015 10:34:41 +0200 Paolo Bonzini <pbonzini@redhat.com> wrote: > >> +In this case, it might be benefitial for the reader to focus on > > > > s/benefitial/beneficial/ > > > >> +sections tagged "Legacy Interface" in the section title. > >> +These highlight the changes made since these earlier drafts. > > > > ", as these highlight the changes made since the earlier drafts." > > I prefer Michael's version for this sentence. English strongly prefers > simpler sentences, or so I was explained by native speakers. This is > unlike Italian, and my high school experience dealing with Kant suggests > that German is similar. :) Heh, I'd already have classified that as a simple sentence :) But no objections from my side. I'd still prefer s/these/the/, though.

On 02/07/2015 10:52, Cornelia Huck wrote:
> > > > +sections tagged "Legacy Interface" in the section title.
> > > > +These highlight the changes made since these earlier drafts.
> > >
> > > ", as these highlight the changes made since the earlier drafts."
> >
> > I prefer Michael's version for this sentence. English strongly prefers
> > simpler sentences, or so I was explained by native speakers. This is
> > unlike Italian, and my high school experience dealing with Kant suggests
> > that German is similar. :)
>
> Heh, I'd already have classified that as a simple sentence :) But no
> objections from my side. I'd still prefer s/these/the/, though.

Agreed.

Paolo

On 02/07/2015 10:52, Cornelia Huck wrote: > > > > +sections tagged "Legacy Interface" in the section title. > > > > +These highlight the changes made since these earlier drafts. > > > > > > ", as these highlight the changes made since the earlier drafts." > > > > I prefer Michael's version for this sentence. English strongly prefers > > simpler sentences, or so I was explained by native speakers. This is > > unlike Italian, and my high school experience dealing with Kant suggests > > that German is similar. :) > > Heh, I'd already have classified that as a simple sentence :) But no > objections from my side. I'd still prefer s/these/the/, though. Agreed. Paolo

On Thu, 2015-07-02 at 10:34 +0200, Paolo Bonzini wrote: > > On 02/07/2015 10:29, Cornelia Huck wrote: > > On Thu, 2 Jul 2015 10:21:03 +0200 > > "Michael S. Tsirkin" <mst@redhat.com> wrote: > > > >> Reading legacy chapters gives a hint about what changed, > >> let's help readers discover this useful shortcut. > >> > >> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> > >> --- > >> introduction.tex 10 ++++++++++ > >> 1 file changed, 10 insertions(+) > >> > >> diff --git a/introduction.tex b/introduction.tex > >> index ac7eefa..0c076f8 100644 > >> --- a/introduction.tex > >> +++ b/introduction.tex > >> @@ -126,6 +126,16 @@ Similarly, a driver MAY implement: > >> Devices or drivers with no legacy compatibility are referred to as > >> non-transitional devices and drivers, respectively. > >> > >> +subsection{Transition from earlier specification drafts} > >> +label{intro:Transition from earlier specification drafts} > >> + > >> +If a device or a driver already implement the legacy interface, > >> +some changes would have to be made to support this specification. > > > > "For devices and drivers already implementing the legacy interface, > > some changes will have to be made to support this specification." > > > >> + > >> +In this case, it might be benefitial for the reader to focus on > > > > s/benefitial/beneficial/ > > > >> +sections tagged "Legacy Interface" in the section title. > >> +These highlight the changes made since these earlier drafts. > > > > ", as these highlight the changes made since the earlier drafts." > > I prefer Michael's version for this sentence. English strongly prefers > simpler sentences, or so I was explained by native speakers. This is > unlike Italian, and my high school experience dealing with Kant suggests > that German is similar. :) That's not true at all ... English prose strongly prefers complex sentences with subclauses to get nuanced descriptions; the heyday of this was the 18-19 century: Dickens and Jane Austen have sentences that go on for pages. That said, this is a specification, not a novel, so specs like clarity and simplicity (in any language). I'd still say In this case the reader might like to focus on sections tagged "Legacy Interface" in the section title which highlight the changes made since these earlier drafts. Because it's a single thought unit. Sentence structure should follow the layout of the ideas. Realistically, this should all be a single paragraph because the 'these' in 'these earlier drafts' refers back to the previous paragraph and paragraphs should be separated and self referential idea blocks. James

On Thu, 2015-07-02 at 10:34 +0200, Paolo Bonzini wrote:
>
> On 02/07/2015 10:29, Cornelia Huck wrote:
> > On Thu, 2 Jul 2015 10:21:03 +0200
> > "Michael S. Tsirkin" <mst@redhat.com> wrote:
> >
> >> Reading legacy chapters gives a hint about what changed,
> >> let's help readers discover this useful shortcut.
> >>
> >> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> >> ---
> >> introduction.tex | 10 ++++++++++
> >> 1 file changed, 10 insertions(+)
> >>
> >> diff --git a/introduction.tex b/introduction.tex
> >> index ac7eefa..0c076f8 100644
> >> --- a/introduction.tex
> >> +++ b/introduction.tex
> >> @@ -126,6 +126,16 @@ Similarly, a driver MAY implement:
> >> Devices or drivers with no legacy compatibility are referred to as
> >> non-transitional devices and drivers, respectively.
> >>
> >> +\subsection{Transition from earlier specification drafts}
> >> +\label{intro:Transition from earlier specification drafts}
> >> +
> >> +If a device or a driver already implement the legacy interface,
> >> +some changes would have to be made to support this specification.
> >
> > "For devices and drivers already implementing the legacy interface,
> > some changes will have to be made to support this specification."
> >
> >> +
> >> +In this case, it might be benefitial for the reader to focus on
> >
> > s/benefitial/beneficial/
> >
> >> +sections tagged "Legacy Interface" in the section title.
> >> +These highlight the changes made since these earlier drafts.
> >
> > ", as these highlight the changes made since the earlier drafts."
>
> I prefer Michael's version for this sentence. English strongly prefers
> simpler sentences, or so I was explained by native speakers. This is
> unlike Italian, and my high school experience dealing with Kant suggests
> that German is similar. :)

That's not true at all ... English prose strongly prefers complex
sentences with subclauses to get nuanced descriptions; the heyday of
this was the 18-19 century: Dickens and Jane Austen have sentences that
go on for pages. That said, this is a specification, not a novel, so
specs like clarity and simplicity (in any language).

I'd still say

In this case the reader might like to focus on sections tagged
"Legacy Interface" in the section title which highlight the
changes made since these earlier drafts.

Because it's a single thought unit. Sentence structure should follow
the layout of the ideas.

Realistically, this should all be a single paragraph because the 'these'
in 'these earlier drafts' refers back to the previous paragraph and
paragraphs should be separated and self referential idea blocks.

James

On 02/07/2015 13:17, James Bottomley wrote:
>> > I prefer Michael's version for this sentence. English strongly prefers
>> > simpler sentences, or so I was explained by native speakers. This is
>> > unlike Italian, and my high school experience dealing with Kant suggests
>> > that German is similar. :)
> That's not true at all ... English prose strongly prefers complex
> sentences with subclauses to get nuanced descriptions; the heyday of
> this was the 18-19 century: Dickens and Jane Austen have sentences that
> go on for pages. That said, this is a specification, not a novel, so
> specs like clarity and simplicity (in any language).

I wish this was the case for the few Italian technical documents I've
had the pleasure to read. :)

> I'd still say
>
> In this case the reader might like to focus on sections tagged
> "Legacy Interface" in the section title which highlight the
> changes made since these earlier drafts.
>
> Because it's a single thought unit. Sentence structure should follow
> the layout of the ideas.

I think this last paragraph is interesting. You didn't write "Because
it's a single thought unit, and sentence structure should follow the
layout of the ideas".

But after all this is bikeshedding, and we all know...

Paolo

On 02/07/2015 13:17, James Bottomley wrote: >> > I prefer Michael's version for this sentence. English strongly prefers >> > simpler sentences, or so I was explained by native speakers. This is >> > unlike Italian, and my high school experience dealing with Kant suggests >> > that German is similar. :) > That's not true at all ... English prose strongly prefers complex > sentences with subclauses to get nuanced descriptions; the heyday of > this was the 18-19 century: Dickens and Jane Austen have sentences that > go on for pages. That said, this is a specification, not a novel, so > specs like clarity and simplicity (in any language). I wish this was the case for the few Italian technical documents I've had the pleasure to read. :) > I'd still say > > In this case the reader might like to focus on sections tagged > "Legacy Interface" in the section title which highlight the > changes made since these earlier drafts. > > Because it's a single thought unit. Sentence structure should follow > the layout of the ideas. I think this last paragraph is interesting. You didn't write "Because it's a single thought unit, and sentence structure should follow the layout of the ideas". But after all this is bikeshedding, and we all know... Paolo

On Thu, 2015-07-02 at 15:04 +0200, Paolo Bonzini wrote: > > On 02/07/2015 13:17, James Bottomley wrote: > >> > I prefer Michael's version for this sentence. English strongly prefers > >> > simpler sentences, or so I was explained by native speakers. This is > >> > unlike Italian, and my high school experience dealing with Kant suggests > >> > that German is similar. :) > > That's not true at all ... English prose strongly prefers complex > > sentences with subclauses to get nuanced descriptions; the heyday of > > this was the 18-19 century: Dickens and Jane Austen have sentences that > > go on for pages. That said, this is a specification, not a novel, so > > specs like clarity and simplicity (in any language). > > I wish this was the case for the few Italian technical documents I've > had the pleasure to read. :) I was expounding the ideal not the sad reality ... > > I'd still say > > > > In this case the reader might like to focus on sections tagged > > "Legacy Interface" in the section title which highlight the > > changes made since these earlier drafts. > > > > Because it's a single thought unit. Sentence structure should follow > > the layout of the ideas. > > I think this last paragraph is interesting. You didn't write "Because > it's a single thought unit, and sentence structure should follow the > layout of the ideas". Actually those are two separate thought units. I could make the second sentence a subclause of the first if I wanted to because it could be made an expansion of the previous though unit; however, it also stands on its own as a statement, hence the new sentence (but either way is correct). The comma before the conjunction, by the way, is illegal in English but acceptable in American. > But after all this is bikeshedding, and we all know... It should be red. James > Paolo > > --------------------------------------------------------------------- > To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org >

On Thu, 2015-07-02 at 15:04 +0200, Paolo Bonzini wrote:
>
> On 02/07/2015 13:17, James Bottomley wrote:
> >> > I prefer Michael's version for this sentence. English strongly prefers
> >> > simpler sentences, or so I was explained by native speakers. This is
> >> > unlike Italian, and my high school experience dealing with Kant suggests
> >> > that German is similar. :)
> > That's not true at all ... English prose strongly prefers complex
> > sentences with subclauses to get nuanced descriptions; the heyday of
> > this was the 18-19 century: Dickens and Jane Austen have sentences that
> > go on for pages. That said, this is a specification, not a novel, so
> > specs like clarity and simplicity (in any language).
>
> I wish this was the case for the few Italian technical documents I've
> had the pleasure to read. :)

I was expounding the ideal not the sad reality ...

> > I'd still say
> >
> > In this case the reader might like to focus on sections tagged
> > "Legacy Interface" in the section title which highlight the
> > changes made since these earlier drafts.
> >
> > Because it's a single thought unit. Sentence structure should follow
> > the layout of the ideas.
>
> I think this last paragraph is interesting. You didn't write "Because
> it's a single thought unit, and sentence structure should follow the
> layout of the ideas".

Actually those are two separate thought units. I could make the second
sentence a subclause of the first if I wanted to because it could be
made an expansion of the previous though unit; however, it also stands
on its own as a statement, hence the new sentence (but either way is
correct). The comma before the conjunction, by the way, is illegal in
English but acceptable in American.

> But after all this is bikeshedding, and we all know...

It should be red.

James


> Paolo
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>

On Thu, Jul 02, 2015 at 03:11:42PM +0000, James Bottomley wrote:
> On Thu, 2015-07-02 at 15:04 +0200, Paolo Bonzini wrote:
> >
> > On 02/07/2015 13:17, James Bottomley wrote:
> > >> > I prefer Michael's version for this sentence. English strongly prefers
> > >> > simpler sentences, or so I was explained by native speakers. This is
> > >> > unlike Italian, and my high school experience dealing with Kant suggests
> > >> > that German is similar. :)
> > > That's not true at all ... English prose strongly prefers complex
> > > sentences with subclauses to get nuanced descriptions; the heyday of
> > > this was the 18-19 century: Dickens and Jane Austen have sentences that
> > > go on for pages. That said, this is a specification, not a novel, so
> > > specs like clarity and simplicity (in any language).
> >
> > I wish this was the case for the few Italian technical documents I've
> > had the pleasure to read. :)
>
> I was expounding the ideal not the sad reality ...
>
> > > I'd still say
> > >
> > > In this case the reader might like to focus on sections tagged
> > > "Legacy Interface" in the section title which highlight the
> > > changes made since these earlier drafts.
> > >
> > > Because it's a single thought unit. Sentence structure should follow
> > > the layout of the ideas.
> >
> > I think this last paragraph is interesting. You didn't write "Because
> > it's a single thought unit, and sentence structure should follow the
> > layout of the ideas".
>
> Actually those are two separate thought units. I could make the second
> sentence a subclause of the first if I wanted to because it could be
> made an expansion of the previous though unit; however, it also stands
> on its own as a statement, hence the new sentence (but either way is
> correct). The comma before the conjunction, by the way, is illegal in
> English but acceptable in American.
>
> > But after all this is bikeshedding, and we all know...
>
> It should be red.
>
> James


I think I like the way James' wrote it better but for a different
reason - the way I wrote it, these was repeated twice.
Cornelia suggested replacing "these" by "the" and I did this in v2
but it's more repetitious and less explicit.

>
> > Paolo
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> > For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
> >
>
>

On Thu, Jul 02, 2015 at 03:11:42PM +0000, James Bottomley wrote: > On Thu, 2015-07-02 at 15:04 +0200, Paolo Bonzini wrote: > > > > On 02/07/2015 13:17, James Bottomley wrote: > > >> > I prefer Michael's version for this sentence. English strongly prefers > > >> > simpler sentences, or so I was explained by native speakers. This is > > >> > unlike Italian, and my high school experience dealing with Kant suggests > > >> > that German is similar. :) > > > That's not true at all ... English prose strongly prefers complex > > > sentences with subclauses to get nuanced descriptions; the heyday of > > > this was the 18-19 century: Dickens and Jane Austen have sentences that > > > go on for pages. That said, this is a specification, not a novel, so > > > specs like clarity and simplicity (in any language). > > > > I wish this was the case for the few Italian technical documents I've > > had the pleasure to read. :) > > I was expounding the ideal not the sad reality ... > > > > I'd still say > > > > > > In this case the reader might like to focus on sections tagged > > > "Legacy Interface" in the section title which highlight the > > > changes made since these earlier drafts. > > > > > > Because it's a single thought unit. Sentence structure should follow > > > the layout of the ideas. > > > > I think this last paragraph is interesting. You didn't write "Because > > it's a single thought unit, and sentence structure should follow the > > layout of the ideas". > > Actually those are two separate thought units. I could make the second > sentence a subclause of the first if I wanted to because it could be > made an expansion of the previous though unit; however, it also stands > on its own as a statement, hence the new sentence (but either way is > correct). The comma before the conjunction, by the way, is illegal in > English but acceptable in American. > > > But after all this is bikeshedding, and we all know... > > It should be red. > > James I think I like the way James' wrote it better but for a different reason - the way I wrote it, these was repeated twice. Cornelia suggested replacing "these" by "the" and I did this in v2 but it's more repetitious and less explicit. > > > Paolo > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org > > For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org > > > >