Re: Package description review for CycloGraph
2012/7/22 Justin B Rye <jbr@edlug.org.uk>:
> Federico Brega wrote:
>> I'm packaging CycloGraph for debian and I'd appreciate if some native
>> english speaker reviews my package description.
>
> Glad to! I hope you don't mind being CCed...
Of course I don't.
>> I also attached a draft of the user manual, whose first part might be
>> useful if some more information is needed.
>> Of course I'm available if something is not clear.
>
> Okay, but I'll do the control file first:
>
> [...]
>> Package: cyclograph
> [...]
>> Description: Application that plots the altimetry of your route
>
> DevRef prefers initial lowercase (s/App/app/), but I'd also consider
> rewriting this to shorten it slightly.
>
> Description: route altimetry plotting application
>
> Then the others can just say " - Qt/GTK/GTK3 interface"... and they
> definitely shouldn't end with full stops.
>
> (Why does cyclograph only recommend the -qt1 and -gtk2 GUIs, not the
> -gtk3 one?)
That's because I forgot to add it, I'll add it immediately.
>> CycloGraph is an application for plotting the elevation profile of routes.
>> It's main purpose is to graphically visualize the difficulty of a
> ^
> Bad apostrophe. The rule's very simple: only contractions with
> missing letters, like "she'll" or "doesn't", need an apostrophe
> (except that possessives also pretend to have a missing letter, so
> "Justin's" and "the woman's" require an apostrophe (except that
> possessive pronouns, like "whose" and "its", *don't* do this (except
> that the possessive pronoun "one's" does after all))).
> It's not entirely clear whether graphically visualising is something
> CycloGraph does (by creating a graphical visualisation) or something
> it (graphically) helps the user do (visualising it mentally). You
> could avoid the issue by saying that "its main purpose is to assist in
> graphical visualization of the difficulty...", but maybe that
> undersells it? I'll try "its main value is in the graphical
> visualization of the difficulty..."?
I meant both: the graphical image produced and the overview in the user's mind.
Your wording sounds good to me.
>> road, in term of slope, difference in height, etc.
> ^
> It's "in terms of".
>
>> These kind of plots are used often in cycling competitions but it's
> ^
> "These kind" (with its plural-versus-singular confusion) does occur in
> native-speaker English, but it's considered a colloquialism; rephrase
> it to "Plots like these..."
>
> "It's" is the right spelling this time, but again it's confused number
> agreement; I'd suggest (adding a comma and) "but are also..."
>
>> useful also in other sports, like hiking or running.
>
> "Like" in this sense is a bit colloquial, too; we'll get away with the
> previous line, but here I'll change it to "such as".
>
>> .
>> This package installs the command-line interface of CycloGraph.
>
> That makes it sound as if you can use it to download a non-free binary
> to /usr/local/bin. Say s/installs/provides/.
I agree, "provides" sounds much better.
> Next the manual.
Oh, you did much more work than expected.
The manual is not yet in the package, and was attached only to give an
overview of the application.
I'll add it to the package as soon as I can.
>> CycloGraph User Manual
>>
>> Federico Brega, Pierluigi Villani
>>
>> 1 Introduction
>>
>> CycloGraph is an application born to let the cyclists visualize
> ^^^
>> their routes and see how difficult they are.
>
> Drop "the". I'm not keen on "born", but it's clear what it means.
>
>> It is important to stress out that plotting the elevation of a
> ^^^
>> path can be interesting also in other sports: i.e. running,
>> hiking or even skiing.
>
> Drop "out". "Stressing that X" means "emphasising that X"; "stressing
> *out* that X" is an informal way of saying "becoming stressed
> (overworked, distressed) over the possibility that X".
>
> "Interesting" should perhaps be "of interest". And surely those are
> just examples, and therefore the abbreviation you want is "e.g."? Or
> preferably, plain "such as".
> It is important to stress that plotting the elevation of a path can
> also be interesting in other sports, such as running, hiking, or
> even skiing.
>
>> The goal of the application is to show the altitude and the slope
>> along the route. The plot shall also be as elegant as possible.
>
> Shall? I think what you're saying is something I'd express as "and to
> do it as elegantly as possible".
That's due to engineering requirements jargon.
>> Many other softwares show a simple plot of the altitude but the
> ^
> Software has no singular/plural; it's a non-count noun, like "water".
> You either want "many other pieces of software" or just "many other
> programs".
>
>> graphics is essential although some of them implements other
> ^ ^^ ^^^^ ^
> Confusing number agreement again. And all of this is a bit
> incoherent... or maybe just underpunctuated. If I'm understanding it
> correctly you mean something like
>
> Many other programs can show a simple plot of the altitude, and some
> of them provide other functionality, but the graphics are essential.
>
>> functionalities. CycloGraph aims to be great to produce
>
> "Great at producing".
>
>> graphically appealing images to be shown on web pages, journals
>> or to document the stages of a race.
>
> This starts as a three-item list and then loses count. Turn it into a
> two-item list and a separate alternative (and in fact reverse the
> order):
>
> CycloGraph aims to be great at producing graphically appealing images
> to document the stages of a race or to be shown on web pages and
> journals.
>
> (If the journals aren't web pages, what are they? Oh well.)
Do you think "newspaper" is a better term, or it's just a
consideration about the obsolescence of paper?
>> 1.1 Features
>>
>> Manual insertion
>>
>> The purpose of the application is to draw a graph; to do this a
>> source of informations is needed. The application can be feed
> ^ ^^^^
> Information doesn't have a singular or plural either; drop the S.
> (Maybe you should be talking about "data sources"?)
"data sources" fits better.
> The passive form you were looking for was "be fed".
>
>> manually, which is very straightforward but soon becomes tiring
>> because the user insert every single information which he
> ^ ^ ^^
>> previously wrote down when he did the trip.
>
> Since female cyclists exist, avoid "he" - just use second person, the
> same way as in the next paragraph.
I had some doubts when I was writing it.
> Number agreement: "inserts". But make it "you need to insert".
>
> There's no such thing as a single information. Here I think we do
> need to resort to "piece of information".
>
> "Previously" is redundant; shuffle the tense/aspect marking slightly.
>
> "Trip" is usually applied to non-recreational travel; the best
> replacement I can think of is "run".
>
> The purpose of the application is to draw a graph; to do this a
> source of information is needed. The application can be fed
> manually, which is very straightforward but soon becomes tiring
> because you need to insert every single piece of information
> you wrote down while you were doing the run.
>
>> GPS tracks
>>
>> GPS devices are very common nowadays, their problem is the very
> ^
> Comma splice - upgrade it to semicolon.
>
>> high rate of recording. CycloGraph allows to import a track
> ^^^^^^^^^
>> recorded and stored in gpx (GPs eXchange format). If your GPS
>
> Probably d-l-e's all-time commonest usage correction: "allow" *must*
> be immediately followed by an object. Say "CycloGraph lets you import
> a track..."
>
> Rebracket: say "stored in GPX (GPs eXchange) format".
>
>> device produces files in another format you may use Gps Babel (www.gpsbabel.org
> ^^^ ^^^^^^^^^
> s/may/can/; upstream say it's "GPSBabel"; strangely placed linebreak.
> (Of course for Debian-specific docs it would be more relevant that I
> can fetch a copy with apt-get.)
Good suggestion.
>> ) to convert it to gpx. Note that GPS tracks are usually not
>> enough to produce an high quality plot because they contains a
> ^
> "A high" - H is a consonant.
>
> Yet more number disagreement: "they contain".
>
>> lot of points, but only a few really add some information to the
>
> I think this is trying to say:
>
> Note that GPS tracking data is usually not enough to produce a
> high-quality plot because although it contains a lot of points,
> only a few really add any information to the plot.
>
> I don't understand the explanation, but then again I'm not familiar
> with GPS data.
The idea is that increasing the number of points over a certain
threshold will add noise instead of information.
My intention was to avoid the concept of noise which can be unfamiliar
for many people.
I think it can be added:
"Using more points would introduce insignificant details, making the
image less clear"
>> plot. CicloGraph tries to import a reasonable number of points,
> ^
> Spell its name right!
>
>> but the best results can be achieved by importing more points
>> than needed and then manually deleting the ones that are not
>> relevant. You may want to edit some point adding a name as well.
>
> I don't understand that last sentence. Maybe:
>
> You may also want to edit some points to add names.
The idea was to let the user do the filtering, but I think it's better
to remove this phrase.
>> Files produced by other applications
>>
>> Interoperability is important and CycloGraph permits to open
> ^^^^^^^ ^^
>> files saved by other applications.Supported formats are:
> ^
> "Permits to" has the same problem as "allows to". Just insert "you".
>
> Trivial punctuation problem.
>
>>
>> • GPS eXchange Format(.gpx)
>
> No, "GPS eXchange format (.gpx)"
>
>> • Keyhole Markup Language (.kml)
>>
>> • Salitaker (.sal)
>
> "Salitaker format (.sal)", and likewise for Ciclotour and Ciclomaniac
> formats below.
>
>> • Training Center xml (.tcx)
>
> Either "XML" or arguably "Xml".
>
>> • Ciclotour (.crp)
>>
>> • Ciclomaniac (.xml and .txt)
>>
>> Kml and draw on map
>
> I think you mean
>
> KML format and drawing on maps
>
> (And s/kml/KML/ throughout below.)
>
>> Importing a slope from a kml file is a unique feature. This is a
>> complex process because a kml file doesn't contain the altitudes
> ^
> Add a comma.
>
>> so they are downloaded from an Internet service. Many services
>> can be chosen, each one has different performances in therm of
>> resolution and and download speed.
> ^^^^^^^
> Can you choose many services all at once, or is it just that there are
> many to choose from? Assuming "therm" is just a typo and not esoteric
> cyclist jargon:
>
> You can choose any of many services, which offer different
> resolution levels and download speeds.
All your assumptions were right.
>> Google Earth (earth.google.com) let you create a route and save
>> it in kml.
>
> s/let/lets/
>
>> CycloGraph embedds a tool to create a kml file by drawing a
> ^
> Only one D in embed, until you add a syllable.
>
>> polyline on a map (Open Street Map or Google Maps). The same tool
>> can also interface to Google Maps' directions.
>
> I really don't know what that's supposed to mean. Its directions?
can also interface to Google Maps' "get directions" service.
Do you think it is clear?
>> Note that this tool permits you to visualize how hard a slope is
> hurrah!
>> even if you have never been there. This is very useful in
>> planning trip. Please note that using an automatic tool might
> ^^^^
> Again "trip" is the wrong word; here we can just make do without it.
>
>> lead to misleading results i.e. if two consecutive point are too
> ^
> Two is plural.
>
> Is this really an "i.e.", or would it make more sense to say "e.g."?
> Even better, avoid both and just lead into it with a colon.
>
> Please note that using an automatic tool may lead to misleading
> results: if two consecutive points are too
>
>> distant the can miss a peak between them. On the other hand if
>
> s/distant/far apart/, and there's a missing word or something.
>
> if two consecutive point are too far apart you can miss a peak
> between them. On the other hand, if
>
>> they are too close the slope may be very inaccurate due to the
>> resolution of the altitude data.
>
> s/close/close together/
>
> How does that work, anyway? Surely it's not saying that the road
> surface is a fractal and therefore gets longer and longer the more
> accurately you measure it...
If the distance between two points is less than the sample dimension
the plot looks like a staircase function.
In addition to that the derivative is very inaccurate ranging from 0
to some very high value.
>>
>> 2 Basic usage
>>
>> 2.1 Start the application
>>
>> CycloGraph has many interfaces either graphical or command line.
> ^
> Four is more "several" than "many". Add a comma.
>
>> If you are a Windows user you're probably interested in the Qt 4
>> interface, because it is the only one which we support in the
>> package for your platform.
>>
>> Note that all graphical interfaces have the same functionalities,
>
> s/functionalities,/functionality;/
>
>> the only difference is in some minor aesthetic detail. This is
> ^
> The en_US (to match "center" above) is "esthetic", but the it would be
> more idiomatic to say "cosmetic details".
>
>> relevant if you are a Linux user since only Qt interface is
> ^
> Insert "the".
>
>> officially supported on Windows and unofficially supported on Mac
>> OS X.
>
> Repetitive, but now with added confusion - if only the Qt interface is
> unofficially supported on Mac OS X, does that mean the other versions
> are officially supported for Mac OS X or not available at all? I'll
> guess the latter, in which case:
>
> This is only relevant if you are a Linux user, since the Qt
> interface is the only one officially supported for Windows, and
> on Mac OS X it's the only one with even unofficial support.
Correct.
> (But I notice the control file says "Architecture: all", so it should
> end up being relevant for Debian GNU/kFreeBSD users too!)
OK I will check if dependencies are met under kFreeBSD.
In principle the should.
>> The same interface (i.e. Qt 4) looks different when used on
>
> Just say "The same Qt 4 interface can look different..." (I suspect
> again you mean "e.g.", but never mind).
>
>> different platforms so don't be confused if the screenshots look
>> a bit different from what you see on your screen.
>>
>> Qt 4
>>
>> The Qt interface uses the Qt4 framework to provide the graphic
> ^
> Make it consistently "Qt 4".
>
>> user interface. While for Windows packages Qt is the only
>> interface available, for GNU/Linux there is also the GTK+
>> interface
> ^
> Missing full stop.
>
>> GTK+
>>
>> The GTK+ interface has two versions, the first one uses the GTK+
> :
>> 2.0 toolkit while the other one uses GTK+ 3.0 .
> ^
> No space before the full stop. If you want to avoid ".0." you can say
> "the first one uses GTK+ 2.0 while the other one uses the GTK+ 3.0
> toolkit."
>
>> Command Line
>>
>> This interface allow to run the application in a console, without
> allows you to
>> the need of a graphical server. This is considered for experts
> for
>> not because it is hard to use but usually only “experts” use the
>> command line.
>
> I think you mean:
>
> This is intended for experts, not because it is hard to use but
> because usually only “experts” use the command line.
>
>> 2.2 Editing and empty file
>
> Huh? Should that perhaps be "Editing a new file"?
>
>> You can start creating a new slope by selecting the first element
>> of the toolbar, alternatively selecting the element “New” on the
> ^or
>> File menu. You can add check-points selecting the “add
> ^by XXX
>> check-point” on the toolbar or by pressing “+” from the keyboard.
>> To modify one point select this on the list and than on the “
>> modify check-point” on the toolbar. You can also delete one or
>
> To modify a point, select it from the list and then “modify
> check-point” on the toolbar.
>
>> more points by selecting them on the list and then press “delete
> pressing
>> check-point” or “-”.
>>
>> 2.3 Show the plot
>>
>> To show the plot after you have created or loaded one slope, you
>> have to press the “plot your slope” button in the toolbar. A new
>> plot window will pop up showing the desired graph, drawn
>> according to the settings on the Options>Preferences menu. If you
>> want to change these settings you can use the menu of the plot
>> window, these changes only affects the current plot window while
> ; X ,
>> the preferences settings are applied at the opening of every plot
>> window.
>>
>> 2.3.1 Save the plot as Image
> ^
> Arbitrary capitalisation and missing article.
>
> 2.3.1 Save the plot as an image
>
>> You can save the image as seen on the new window to a file.
> in
>>
>> Many file formats are supported but the most common are:
>>
>> • svg: It is a vectorial format, which means that can be zoomed
>> without any artifact.
>
> "Vectorial" is only used in mathematics.
>
> The names of formats should be uppercase throughout (you could say
> ".jpg", but not "jpeg").
>
> • SVG: a vector format, which means that it can be zoomed with no
> artifacts.
>
>> • bmp: It is a raster format which means that changing the zoom
>> level of the file will affect the quality of the image. No
>> compression is used so the format is simple but the size is
>> big.
>
> • BMP: a raster format, which means that changing the zoom
> level of the file will affect the quality of the image. No
> compression is used so the format is simple but the files are
> large.
>
>> • png: It is a raster format with loose-less compression which
> ^^^^
>> means that the quality is not affected by the compression
>> level.
>
> • PNG: a raster format with lossless compression, which means that
> the quality is not affected by the compression level.
>
>> • jpeg: It is a raster format that degrades the quality with the
>> level of compression, bu can achieve very small files.
> ^
> • JPEG: a raster format that degrades the quality with the level of
> compression, but can achieve very small files.
>
>>
>> 3 Advanced Usage
>
> I hope you don't expect me to write this for you!
Of course I don't. I apologize if I wasn't clear, but this is still a
work in progress.
>> 4 Expert Usage
>>
>> 4.1 Command Line
>>
>> The command line interface exposes a subset of the features of
>> the graphical interface. Many of them are not accessible because
>> the console is not suitable for this use case i.e. drawing a path
>> on map.
>
> "Not suitable for this use case" is a bit of a non-explanation. And
> again I suspect that's an "e.g." rather than an "i.e."! Since people
> confuse them it's usually best to avoid both and use plain English.
>
> Many features (such as drawing a path on a map) are not accessible,
> because of the limitations of the console.
>
>> Editing is not possible but more appropriate tools can be used
>> instead, see Subsection [sub:Editing-csv].
>
> If this file is the output of some sort of "save as .txt" then you're
> going to have trouble assimilating my corrections...
Yes I will. :)
The document is exported from Lyx but I though it was better not to
attach binary files as pdf.
>> When CycloGraph is invoked without any option the application
> with no options
>> will guess a suitable graphical interface.
>>
>> A specific graphical interface can be selected by means of an
>> option.
>>
>> The complete and updated list of supported flags can be shown
>> using the “--help” option.
>>
>> If no graphical interface is selected but a file is opened (using
>> “--file=filename”) the application will run from commandline.
> the command-line.
>> This means that the slope will be plotted and printed in svg
>> format in the standard output. If you want to save it you can
> to
>> simply use the output redirection operator of your shell (usually
>> “>”).
>>
>> 4.2 Editing the CycloGraph csv file<sub:Editing-csv>
>>
>> Cyclograph csv files use ";" delimiter for fields in the same
>> line.
>
> CycloGraph CSV files use the delimiter “;” for fields in the same line.
>
> (Or perhaps that should be "subfields"? If the delimiter isn't ",",
> how is it a Comma-Separated-Valuse file?)
Even if that's the acronym, the delimiter is not standardized.
In this case is actually a semicolon.
>
>> # line 1: slope informations, 6 fields
>>
>> 1. csv version
>>
>> 2. slope name
>>
>> 3. slope state
>>
>> 4. author
>>
>> 5. author's e-mail
> ^address^
>>
>> 6. comments
>>
>> # line 2,..,n: check points, 3 fields
>
> Is that saying "lines 2+"?
Yes it is.
Probably I should look at some more formal syntax.
>>
>> 1. distance
>>
>> 2. altitude
>>
>> 3. check point name
>
> This is a bit sketchy, but then again it is for experts.
Yes, probably too "dense".
Thank you very much for all your work.
--
Federico Brega
Reply to: