[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [virtio-dev] Re: [virtio] [PATCH] intro: add advice on transition from legacy interfaces
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]