Hi Justin, On 09/29/2013 11:00 AM, Justin B Rye wrote: > > There are quite a few minor English language problems in the package > description for python-livereload. None of them are bad enough to > make it unintelligible, and description bugs like this are especially > low-priority for library packages, but I happened to notice this one > in the new packages list, so here's a patch.
I try to do the best I can, but my English is still not so good. I really appreciate your corrections, and I invite you (if you can/want) to review the descriptions of my other packages. >> Package: python-livereload > [...] >> Description: Refresh the browser automatically when a file has been updated > > This has a very slightly unidiomatic use of "has been" where a > native-speaker would probably use simply "is"; and as it happens > DevRef recommends not using (capitalised) verb-phrase-based synopses > like this. "Best practice" is to use something noun-phrase-based (and > uncapitalised) that fits the template "this package provides a..." > >> Web Developers need to refresh a browser everytime when he saved a file >> (css, >> javascript, html), it is really boring. [...] > > This is full of low-level errors: > * web developers don't get a capital D; > * there's no such word as "everytime"; > * developers can be female, and are plural anyway; > * they need to refresh "their" browser rather than just "a" browser; > * "saved" is the wrong tense - it's "every time X happens", present; > * CSS/JavaScript/HTML shouldn't be written all-lowercase; > * it's "CSS/JavaScript/HTML file", so shift the parentheses earlier; > * the list needs a conjunction - "CSS, JavaScript, or HTML"; > * tacking "it is really boring" on the end is ungrammatical. > > I suspect a real pedant might also argue that you don't "refresh" a > browser; you refresh the page by reloading the browser. But even if > that usage is technically wrong then it's far too late to stop it > becoming the idiom that's most widely understood. I'll just make sure > the word "reload" is there at least once in the description for the > sake of people doing searches. > >> [...] LiveReload will take care of that >> for >> you. When you saved a file, your browser will refresh itself. And what's >> more, > > Again, "when you save", not past tense. Otherwise this is a lot > better, though I would suggest stringing together everything from > "LiveReload will..." instead of having so many short choppy sentences. > For a start this would neatly eliminate the first problem with the > following sentence. > >> it can do some tasks like compiling less to css before the browser >> refreshing. > > More problems: > * it's not immediately obvious what "it" is - the subject of the > previous sentence was "your browser"; > * "do" is weak - say "can perform"; > * "some" is unnecessary here; > * using "like" this way is very, very slightly colloquial - while I'm > rewriting this I'll change it to a more formal "such as"; > * "compiling less" would mean doing reduced amounts of compilation; > * "before the browser refreshing" doesn't work, which looks like an > opening for the plain noun "reload". > > My suggested rewrite: > > # Description: automatic browser refresher > # It is really boring for Web developers to need to refresh their browser > # every time they save a (CSS, JavaScript, or HTML) file. LiveReload will > # take care of that for you, so that when you save a file, your browser > # will refresh itself - and what's more, it can perform tasks such as > # compiling LESS to CSS before the browser reload. I agree with all suggestions and I'll apply the patch in the next version. Thank you very much. -- TiN
signature.asc
Description: OpenPGP digital signature
