Re: debian/control description text review for udav package
Salvatore Bonaccorso wrote:
> I firstly picked the wrong list to ask this review request. Please
> keep me in Cc.
Okay.
> Source: udav
[...]
> Description: data visualization based on MathGL
That's got all the right grammatical features, but doesn't fit the
"template" - it's not a description of what udav _is_. I'd suggest:
Description: data visualization application based on MathGL
Or would it be better to call it an "environment"?
> UDAV is cross-platform program for data arrays visualization
> based on MathGL library. It support wide spectrum of
> graphics, simple script language and visual data handling and
> editing. It has window interface for data viewing, changing
> and plotting. Also it can execute MGL scripts, setup and
> rotate graphics and so on. MathGL is a free library of fast
> C++ routines for the plotting
I see a few minor grammar problems, but I'll fix them in passing.
The advert for MathGL, and the selling points of being free and
cross-platform, are appropriate on a homepage, but rather useless
here. And I can't tell whether the "simple script language" and the
M(ath)GL scripting are talking about the same thing.
Oh, the name means Unguessable-first-word Data Array Visualization?
Make that easier to spot.
What does it mean when it says it can "setup graphics"?
Chopping it up a bit more than strictly necessary I get:
UDAV provides a graphical environment for Data Array Visualization based
on the MathGL library. It allows easy viewing, manipulation and plotting
of datasets, and supports a wide range of graphical effects with a simple
scripting language. It can also execute MathGL scripts. Features include:
> UDAV Features:
> .
> * Wide spectrum of graphics.
^
Excess indent; it just needs one extra space before the bullet.
You said that. "Spectrum" is probably worth avoiding, and you mean
a range of effects, not just lots of different images - I've changed
it above to "a wide range of graphical effects", but here I'd drop
it.
> * There are smoothed lightning, transparency, TeX symbols
> and formulas, arbitrary curvelinear coordinates and a
> lot of other things.
Top-and-tail, correct spellings.
> * Simple and fast data and formulas plotting:
My own preferred solution to the question of how to handle
lists-within-lists is to say that they're almost always
worth getting rid of. Here, each sub-item could equally well be
rewritten as a main "feature".
> o You can plot the data by one click (just type
> 'udav datafile.dat' or open it in UDAV)
Typing it isn't one click.
> o You can see the script and graphical result at
> the same time.
> o You can rotate, shift, zoom plot by toolbuttons
> or by mouse.
Does "shift" here mean "pan"?
> o You can switch on/off lightning and transparency.
> o You can run animation.
> * Table for data editing support up to 3-dimensional data
> arrays.
> * Minimal set of tools for data handling (smoothing,
> resizing, cropping, filling by formula, summation,
> differentiation, histogram creation and so on).
Is the minimalness a feature, or is this only a prototype? What's
"filling by formula"?
> * Export graphics to bitmap (PNG, JPEG or EPS) and vector
> (EPS or SVG) files.
It would be easier to list the formats at the end.
So that's:
* Simple and fast plotting of data and formulas;
* One-click interface - just open the datafile in UDAV;
* Scripts and graphical output both shown at the same time;
* Rotate, pan, and zoom controls (via buttons or mouse);
* Toggleable lighting and transparency;
* GIF Animation;
* Support for smoothed lighting, transparency, arbitrary curvilinear
coordinates, and TeX symbols and formulas;
* Tables for data editing, with support for 3-dimensional arrays;
* Basic toolset for data handling (smoothing, resizing, cropping,
filling by formula, summation, differentiation, histogram creation,
and so on);
* Export to bitmap and vector formats (PNG, JPEG, EPS, or SVG).
(Input from people who use this sort of tool more often than me
would be welcome. For instance, would you call them formulas or
formulae?)
> ----------------------------------------------------------------------
> .SH NAME
> udav \- program for data visualization based on MathGL
> .SH SYNOPSIS
> .B udav
> .RI [ file(s) ]
> .SH DESCRIPTION
> This manual page documents briefly the
> .B udav
> command. This manual page was written for the Debian GNU/Linux distribution
> because the original program does not have a manual page.
> .PP
> udav has no options which can be passed. This manpage is created to point to the
> documentation found under /usr/share/doc/udav/help.
> .SH AUTHOR
> This manual page was written by Salvatore Bonaccorso <salvatore.bonaccorso@gmail.com> for the
> Debian GNU/Linux system (but may be used by others).
Seems fair enough, under the circumstances, except that I'm used to
seeing that "zero or more arguments" thing as:
.RI [FILE]...
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: