Re: [virtio-dev] Re: [virtio] [PATCH] intro: add advice on transition from legacy interfaces

[James Bottomley <jbottomley@odin.com>]

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