Bug#661689: Bad formatting of package description, perhaps improvable wording

Justin B Rye jbr at edlug.org.uk
Wed Feb 29 14:36:58 UTC 2012 

Martin Eberhard Schauer wrote:
> Package: src:rheolef
[...]

(By the way, just before sending this I've found
https://www.projet-plume.org/fr/fiche/rheolef
which looks like the French original version.)

> Description: Finite elements for partial differential equations

That looks like a claim that the packages provide "finite elements",
which can't be right - surely they provide software for doing 
computations using the Finite Element Method?  That could easily make
it far too longwinded for a synopsis, but you're allowed abbreviations
like "FEM" or "PDE" as long as you explain them in the long
description.  And is it really essential to mention partial
differential equations anyway?  Wikipedia tells me FEM is only used
for two things: PDEs and integral equations.  Is rheolef any use for
integral equations?

And what is it about rheolef that makes it different from the
alternatives?  Is it a "simple FEM system"?  Or maybe a "flexible FEA
environment"?  What's it's selling point?  Google shows me a page
advertising "efficient C++ finite element computing with Rheolef",
so how about:

  Description: efficient Finite Element environment

>  Rheolef is a computer environment that serves as a convenient
>  laboratory for computations in applied mathematics, involving finite
                                                     ^
If these are computations *such that* they involve FE-like methods,
you've got an excess comma there.

>  element-like methods. It provides a set of unix commands and C++
>  algorithms and containers.

Drop the "unix" (see below).  Are these "C++ containers"?  Or are the
containers themselves algorithms implemented in C++?  Or what?

>  .
>  Containers cover first the classic graph data structure for sparse
                    ^^^^^
>  matrix formats and finite element meshes.

Huh?  What do they cover second?

>  .
>  An higher level of abstraction is provided by containers related to
    ^
>  approximate finite element spaces, discrete fields and bilinear forms.

It's "a higher" - H is a consonant.

Is the "higher level of abstraction" the second thing?  If so this
would be clearer as one paragraph, maybe:

   Most basically, containers cover the classic graph data structure for
   sparse matrix formats and finite element meshes. At a higher level of
   abstraction, they can handle approximate finite element spaces, discrete
   fields, and bilinear forms.

>  .
>  Current applications cover
>  .
>   - Poisson problems in 1D 2D and 3D with P1 or P2 elements
>   - Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements
>   - linear elasticity in 2D and 3D, with P1 and P2 elements,
>     including the incompressible and nearly incompressible elasticity
                ^^^
That looks like a surplus article.

>   - characteristic method for convection-diffusion, time-dependent
>     problems and Navier-Stokes equations.
>   - auto-adaptive mesh based for 2D problems
>   - axisymmetric problems
>   - multi-regions and non-constant coefficients
>   - axisymmetric problems
      ^^^^^^^^^^^^^^^^^^^^^
You already said that.

Okay, bear in mind that I'm only an arts graduate with wikipedia
access, and I don't really understand any of the content here!  But
I'd suggest some repunctuation and reformatting:

   Current applications include:
    * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
    * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
    * linear elasticity in 2D and 3D, with P1 and P2 elements, including
      incompressible and nearly incompressible elasticity;
    * characteristic method for convection-diffusion, time-dependent
      problems and Navier-Stokes equations;
    * auto-adaptive mesh approaches for 2D problems;
    * axisymmetric problems;
    * multi-region and non-constant coefficients.

>  .
>  Input and output in various file format for meshes generators
>  and numerical data visualization systems (mayavi, vtk, plotmtv, gnuplot).
                                             MayaVi, VTK, PLOTMTV, gnuplot

That's hard to parse, but I assume it means something like:

   Rheolef supports input and output in various file formats for
   mesh-generators and numerical data visualization systems such as
   MayaVi, VTK, PLOTMTV, and gnuplot.

That still really isn't enough for the package-specific part - it
hasn't given any real clue what rheolef provides.  The "unix
commands"?

> In this version there are some issues still not covered:
>  - The easiest is the correct spelling of Unix (2).

As your Wikipedia reference points out, sometimes "UNIX" is even more
correct.  But what is the word doing here anyway?  As far as users of
the Debian package are concerned, rheolef provides Linux, kFreeBSD,
and Hurd commands!

>  - I don't understand "auto-adaptive mesh based for 2D problems". Without
>    "based" I would have an idea.

Google shows me people talking about auto-adaptive (FE) mesh
"approaches" in similar contexts, so that's the word I've inserted
above.

>  - Isn't a non-constant coefficient just a variable one?
>  - What are multi-regions coefficients?

I don't know, but the "-s" on "regions" looks like a
non-native-speakerism.

Revised version and patch attached.

obWhyTheName: something to do with logiciel and éléments finis...
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

-------------- next part --------------
diff -ru rheolef-5.93.pristine/debian/control rheolef-5.93/debian/control
--- rheolef-5.93.pristine/debian/control	2011-03-31 09:55:19.000000000 +0100
+++ rheolef-5.93/debian/control	2012-02-29 14:26:21.607727244 +0000
@@ -17,31 +17,29 @@
 Conflicts: librheolef5.89, librheolef5.90
 Replaces: librheolef5.89, librheolef5.90
 Suggests: rheolef-doc
-Description: Finite elements for partial differential equations (shared library)
+Description: efficient Finite Element environment - shared library
  Rheolef is a computer environment that serves as a convenient
- laboratory for computations in applied mathematics, involving finite
- element-like methods. It provides a set of unix commands and C++
- algorithms and containers.
- .
- Containers covers first the classic graph data structure for sparse
- matrix formats and finite element meshes.
- .
- An higher level of abstraction is provided by containers related to
- approximate finite element spaces, discrete fields and bilinear forms.
- .
- .
- Current applications cover
- .
-  - Poisson problems in 1D 2D and 3D with P1 or P2 elements
-  - Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements
-  - linear elasticity in 2D and 3D, with P1 and P2 elements,
- including the incompressible and nearly incompressible elasticity
-  - characteristic method for convection-difusion, time-dependent problems
- and Navier-Stokes equations.
-  - auto-adaptive mesh based for 2D problems
-  - axisymetric problems
-  - multi-regions and non-constant coefficients
-  - axisymetric problems
+ laboratory for computations in applied mathematics involving finite
+ element-like methods. It provides a set of commands and C++ algorithms
+ and containers.
+ .
+ Most basically, containers cover the classic graph data structure for
+ sparse matrix formats and finite element meshes. At a higher level of
+ abstraction, they can handle approximate finite element spaces, discrete
+ fields, and bilinear forms.
+ .
+ Current applications include:
+  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
+  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
+  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
+    incompressible and nearly incompressible elasticity;
+  * characteristic method for convection-diffusion, time-dependent
+    problems and Navier-Stokes equations;
+  * auto-adaptive mesh approaches for 2D problems;
+  * axisymmetric problems;
+  * multi-region and non-constant coefficients.
+ .
+ This package provides the shared library.
 
 Package: librheolef-dev
 Section: libdevel
@@ -50,31 +48,29 @@
  libsuitesparse-dev, ${misc:Depends}
 Recommends: rheolef-doc(= ${binary:Version})
 Suggests:
-Description: Finite elements for partial differential equations (headers)
+Description: efficient Finite Element environment - development files
  Rheolef is a computer environment that serves as a convenient
- laboratory for computations in applied mathematics, involving finite
- element-like methods. It provides a set of unix commands and C++
- algorithms and containers.
- .
- Containers covers first the classic graph data structure for sparse
- matrix formats and finite element meshes.
- .
- An higher level of abstraction is provided by containers related to
- approximate finite element spaces, discrete fields and bilinear forms.
- .
- .
- Current applications cover
- .
-  - Poisson problems in 1D 2D and 3D with P1 or P2 elements
-  - Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements
-  - linear elasticity in 2D and 3D, with P1 and P2 elements,
- including the incompressible and nearly incompressible elasticity
-  - characteristic method for convection-difusion, time-dependent problems
- and Navier-Stokes equations.
-  - auto-adaptive mesh based for 2D problems
-  - axisymetric problems
-  - multi-regions and non-constant coefficients
-  - axisymetric problems
+ laboratory for computations in applied mathematics involving finite
+ element-like methods. It provides a set of commands and C++ algorithms
+ and containers.
+ .
+ Most basically, containers cover the classic graph data structure for
+ sparse matrix formats and finite element meshes. At a higher level of
+ abstraction, they can handle approximate finite element spaces, discrete
+ fields, and bilinear forms.
+ .
+ Current applications include:
+  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
+  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
+  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
+    incompressible and nearly incompressible elasticity;
+  * characteristic method for convection-diffusion, time-dependent
+    problems and Navier-Stokes equations;
+  * auto-adaptive mesh approaches for 2D problems;
+  * axisymmetric problems;
+  * multi-region and non-constant coefficients.
+ .
+ This package provides the headers required for development.
 
 Package: rheolef-doc
 Section: doc
@@ -82,64 +78,57 @@
 Depends: ${misc:Depends}, dpkg (>= 1.15.4) | install-info
 Conflicts: librheolef-doc
 Replaces: librheolef-doc
-Description: Finite elements for partial differential equations (documentation)
+Description:  efficient Finite Element environment - documentation
  Rheolef is a computer environment that serves as a convenient
- laboratory for computations in applied mathematics, involving finite
- element-like methods. It provides a set of unix commands and C++
- algorithms and containers.
- .
- Containers covers first the classic graph data structure for sparse
- matrix formats and finite element meshes.
- .
- An higher level of abstraction is provided by containers related to
- approximate finite element spaces, discrete fields and bilinear forms.
- .
- .
- Current applications cover
- .
-  - Poisson problems in 1D 2D and 3D with P1 or P2 elements
-  - Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements
-  - linear elasticity in 2D and 3D, with P1 and P2 elements,
- including the incompressible and nearly incompressible elasticity
-  - characteristic method for convection-difusion, time-dependent problems
- and Navier-Stokes equations.
-  - auto-adaptive mesh based for 2D problems
-  - axisymetric problems
-  - multi-regions and non-constant coefficients
-  - axisymetric problems
+ laboratory for computations in applied mathematics involving finite
+ element-like methods. It provides a set of commands and C++ algorithms
+ and containers.
+ .
+ Most basically, containers cover the classic graph data structure for
+ sparse matrix formats and finite element meshes. At a higher level of
+ abstraction, they can handle approximate finite element spaces, discrete
+ fields, and bilinear forms.
+ .
+ Current applications include:
+  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
+  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
+  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
+    incompressible and nearly incompressible elasticity;
+  * characteristic method for convection-diffusion, time-dependent
+    problems and Navier-Stokes equations;
+  * auto-adaptive mesh approaches for 2D problems;
+  * axisymmetric problems;
+  * multi-region and non-constant coefficients.
+ .
+ This package provides the documentation.
 
 Package: rheolef
 Section: math
 Architecture: any
 Depends: ${shlibs:Depends}, librheolef1(= ${binary:Version}), ${misc:Depends}
 Recommends: librheolef-dev, rheolef-doc, gnuplot, imagemagik, tcl-vtk | vtk-tcl, gmsh, mayavi2 | mayavi, paraview, ffmpeg
-Description: Finite elements for partial differential equations
+Description: efficient Finite Element environment
  Rheolef is a computer environment that serves as a convenient
- laboratory for computations in applied mathematics, involving finite
- element-like methods. It provides a set of unix commands and C++
- algorithms and containers.
- .
- Containers covers first the classic graph data structure for sparse
- matrix formats and finite element meshes.
- .
- An higher level of abstraction is provided by containers related to
- approximate finite element spaces, discrete fields and bilinear forms.
- .
- .
- Current applications cover
- .
-  - Poisson problems in 1D 2D and 3D with P1 or P2 elements
-  - Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements
-  - linear elasticity in 2D and 3D, with P1 and P2 elements,
- including the incompressible and nearly incompressible elasticity
-  - characteristic method for convection-difusion, time-dependent problems
- and Navier-Stokes equations.
-  - auto-adaptive mesh based for 2D problems
-  - axisymetric problems
-  - multi-regions and non-constant coefficients
-  - axisymetric problems
- .
- Input and Output in various file format for meshes generators
- and numerical data visualization systems (mayavi, vtk, plotmtv, gnuplot).
-
-
+ laboratory for computations in applied mathematics involving finite
+ element-like methods. It provides a set of commands and C++ algorithms
+ and containers.
+ .
+ Most basically, containers cover the classic graph data structure for
+ sparse matrix formats and finite element meshes. At a higher level of
+ abstraction, they can handle approximate finite element spaces, discrete
+ fields, and bilinear forms.
+ .
+ Current applications include:
+  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
+  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
+  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
+    incompressible and nearly incompressible elasticity;
+  * characteristic method for convection-diffusion, time-dependent
+    problems and Navier-Stokes equations;
+  * auto-adaptive mesh approaches for 2D problems;
+  * axisymmetric problems;
+  * multi-region and non-constant coefficients.
+ .
+ This package provides the rheolef commands. These support input and
+ output in various file formats for mesh-generators and numerical data
+ visualization systems such as MayaVi, VTK, PLOTMTV, and gnuplot.
-------------- next part --------------
Source: rheolef
Section: math
Priority: optional
Maintainer: Debian Science Maintainers <debian-science-maintainers at lists.alioth.debian.org>
Uploaders: Christophe Prud'homme <prudhomm at debian.org>, 
 Pierre Saramito <pierre.saramito at imag.fr>
Homepage: http://ljk.imag.fr/membres/Pierre.Saramito/rheolef
Build-Depends: debhelper (>=7), autoconf, automake, libtool, libltdl-dev | libltdl3-dev, flex, bison, xutils-dev, libboost-dev, libboost-iostreams-dev, libboost-serialization-dev, libginac-dev, ginac-tools, libsuitesparse-dev, libstdc++6, texi2html, texinfo, texlive-latex-recommended, texlive-latex-extra, texlive-math-extra, texlive-font-utils, ghostscript, gnuplot, xfig, transfig, texinfo, imagemagick, graphviz
Standards-Version: 3.9.1
Vcs-Svn: svn://svn.debian.org/svn/debian-science/packages/rheolef/trunk/
Vcs-Browser: http://svn.debian.org/viewsvn/debian-science/packages/rheolef/trunk/

Package: librheolef1
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Conflicts: librheolef5.89, librheolef5.90
Replaces: librheolef5.89, librheolef5.90
Suggests: rheolef-doc
Description: efficient Finite Element environment - shared library
 Rheolef is a computer environment that serves as a convenient
 laboratory for computations in applied mathematics involving finite
 element-like methods. It provides a set of commands and C++ algorithms
 and containers.
 .
 Most basically, containers cover the classic graph data structure for
 sparse matrix formats and finite element meshes. At a higher level of
 abstraction, they can handle approximate finite element spaces, discrete
 fields, and bilinear forms.
 .
 Current applications include:
  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
    incompressible and nearly incompressible elasticity;
  * characteristic method for convection-diffusion, time-dependent
    problems and Navier-Stokes equations;
  * auto-adaptive mesh approaches for 2D problems;
  * axisymmetric problems;
  * multi-region and non-constant coefficients.
 .
 This package provides the shared library.

Package: librheolef-dev
Section: libdevel
Architecture: any
Depends: librheolef1(= ${binary:Version}), rheolef(= ${binary:Version}), libboost-dev, libboost-iostreams-dev, libboost-serialization-dev,
 libsuitesparse-dev, ${misc:Depends}
Recommends: rheolef-doc(= ${binary:Version})
Suggests:
Description: efficient Finite Element environment - development files
 Rheolef is a computer environment that serves as a convenient
 laboratory for computations in applied mathematics involving finite
 element-like methods. It provides a set of commands and C++ algorithms
 and containers.
 .
 Most basically, containers cover the classic graph data structure for
 sparse matrix formats and finite element meshes. At a higher level of
 abstraction, they can handle approximate finite element spaces, discrete
 fields, and bilinear forms.
 .
 Current applications include:
  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
    incompressible and nearly incompressible elasticity;
  * characteristic method for convection-diffusion, time-dependent
    problems and Navier-Stokes equations;
  * auto-adaptive mesh approaches for 2D problems;
  * axisymmetric problems;
  * multi-region and non-constant coefficients.
 .
 This package provides the headers required for development.

Package: rheolef-doc
Section: doc
Architecture: all
Depends: ${misc:Depends}, dpkg (>= 1.15.4) | install-info
Conflicts: librheolef-doc
Replaces: librheolef-doc
Description:  efficient Finite Element environment - documentation
 Rheolef is a computer environment that serves as a convenient
 laboratory for computations in applied mathematics involving finite
 element-like methods. It provides a set of commands and C++ algorithms
 and containers.
 .
 Most basically, containers cover the classic graph data structure for
 sparse matrix formats and finite element meshes. At a higher level of
 abstraction, they can handle approximate finite element spaces, discrete
 fields, and bilinear forms.
 .
 Current applications include:
  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
    incompressible and nearly incompressible elasticity;
  * characteristic method for convection-diffusion, time-dependent
    problems and Navier-Stokes equations;
  * auto-adaptive mesh approaches for 2D problems;
  * axisymmetric problems;
  * multi-region and non-constant coefficients.
 .
 This package provides the documentation.

Package: rheolef
Section: math
Architecture: any
Depends: ${shlibs:Depends}, librheolef1(= ${binary:Version}), ${misc:Depends}
Recommends: librheolef-dev, rheolef-doc, gnuplot, imagemagik, tcl-vtk | vtk-tcl, gmsh, mayavi2 | mayavi, paraview, ffmpeg
Description: efficient Finite Element environment
 Rheolef is a computer environment that serves as a convenient
 laboratory for computations in applied mathematics involving finite
 element-like methods. It provides a set of commands and C++ algorithms
 and containers.
 .
 Most basically, containers cover the classic graph data structure for
 sparse matrix formats and finite element meshes. At a higher level of
 abstraction, they can handle approximate finite element spaces, discrete
 fields, and bilinear forms.
 .
 Current applications include:
  * Poisson problems in 1D, 2D, and 3D with P1 or P2 elements;
  * Stokes problems in 2D and 3D, with P2-P1 or P1 bubble-P1 elements;
  * linear elasticity in 2D and 3D, with P1 and P2 elements, including
    incompressible and nearly incompressible elasticity;
  * characteristic method for convection-diffusion, time-dependent
    problems and Navier-Stokes equations;
  * auto-adaptive mesh approaches for 2D problems;
  * axisymmetric problems;
  * multi-region and non-constant coefficients.
 .
 This package provides the rheolef commands. These support input and
 output in various file formats for mesh-generators and numerical data
 visualization systems such as MayaVi, VTK, PLOTMTV, and gnuplot.

More information about the debian-science-maintainers mailing list