[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [RFH] libfm package description



Andrew Lee wrote:
> I need native speakers to help on improving the package description for
>  libfm which is a library that needed for newer version of pcmanfm.
> 
> It's a new package for newer pcmanfm and also tend to be easy to reuse
> in other applications which needs file management functions and widgets
> that missing in GTK+ and glib.
> 
> Here are the debian/control file:
> 
[...]
> Package: libfm0
> Section: libs
> Architecture: any
> Depends: ${shlibs:Depends}, ${misc:Depends}
> Description: libraries for file management programming needs

If this was a library to serve the "programming needs" of
developers, it would belong in libdevel.  Describe the function of
libfm0 for the end users who are going to have it installed:

  Description: file management support - core library

>  LibFM is a library packaging GLIB/GIO and provide higher level API and
>  related window components as a library for file management programming
>  needs, and make it easy to reuse for other programs.

This again is the wrong content (as well as being obviously
non-native-speakerish); this stuff about APIs is a completely
developer-centric description of the library's function.

It wouldn't be hard to fix if I could understand it, but I can't
make sense of it.  What is "a library packaging GLIB/GIO"?  How does
LibFM "provide [an] API and related window components as a library"?

Cutting ruthlessly, I'll suggest:

   LibFM provides Glib/GIO file management widgets.

>  Features:
>   * Independent to any platform/desktop environment

Pedantically speaking, I'm fairly sure it's dependent on a
von-Neumann-architecture programmable computer... will it even
work if I don't have X installed?  It requires *some* desktop
environment, it's just not explicitly part of GNOME.

Except that in fact it Depends on libgconf2, libgnome-keyring0, and
libgvfscommon0, which together pull in so much GNOME stuff that I've
uninstalled pcmanfm on Squeeze.  How does this count as
desktop-neutral?

>   * Use gio/gvfs as same as Nautilus to support remote storage, with
>     faster experience to users.
>   * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
>     WebDav...)

Merge, Englishify and treat end-users as the default.  Also,
incorporate the line lower down about Trash support:

    * Uses GIO/GVFS (like Nautilus) for Trash Can support and access to
      remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);

>   * Fast, low memory usage and low latency which is friendly to less
>     powerful hardware such as netbook and thin client/server.

When you say "low latency", is that talking about *network* latency?
You've already said libfm's fast... but I can't see how it's going
to reduce the latency of connections to my file server, or why that 
would be particularly helpful on antique hardware.

(And why would a thin client *server* be "less powerful hardware"?
Do you just mean the client?)

    * Fast and light on memory usage, which is friendly to less
      powerful hardware such as netbooks and thin clients;

>   * Trash can support (provided by gvfs).

Absorbed into the GIO/GVFS bulletpoint above.

>   * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE

If GTK+ and GNOME are separate options, shouldn't the same apply to
QT and KDE?  Or would it make more sense to say:

    * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;

>   * Core function separated from GUI, be able reuse with UI toolkit other
>     than GTK+, eg Qt4 or Enlightenment.

This should be explained in terms of what benefit (if any) that
brings to end users of libfm0.  The nearest I can get is

    * Reusable design with the core functions separated out to simplify
      porting to other GUIs;

I've left out the names of GUIs that aren't currently supported on
the grounds that you probably don't want to have to keep editing
this to keep the list up to date.

>   * Supports Drag and drop handling and supports XDS (X Direct Save).

Abbreviations are pointless if they have to have their expanded
forms following them around everywhere.  Not that X Direct Save is
much more intelligible than the raw TLA, but never mind.

    * Supports Drag-and-Drop, using the X Direct Save protocol.

>   * Provides some widgets for file management needs that are missing in
>     GTK+ and glib.

This as far as I can tell is just a restatement of what should have
been the first line.

(Quite a lot of the above might boil down to a single bulletpoint
saying "Freedesktop standards-compliant", but I'm not sure how
much.)

>  .
>  This package contains the core function library.

That bit's fine.  So reshuffling into a more coherent order I get:

  Description: file management support - core library
   LibFM provides Glib/GIO file management widgets. Features:
    * Fast and light on memory usage, which is friendly to less
      powerful hardware such as netbooks and thin clients;
    * Uses GIO/GVFS (like Nautilus) for Trash support and access to
      remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
    * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
    * Supports Drag-and-Drop, using the X Direct Save protocol;
    * Reusable design with the core functions separated out to
      simplify porting to other GUIs.
   .
   This package contains the core function library.

(With bulleted lists it's nice if you can make them all structurally
parallel - all adjectival, all nouns, or whatever.  Here, I haven't
managed that, so I'd be glad to see suggestions.)

> Package: libfm-gtk0
[...]
> Description: libraries for file management programming needs - GTK+ GUI
[...]
>  .
>  This package contains the GTK+ GUI.

  Description: file management support - GTK+ GUI library
   $BOILERPLATE
   .
   This package contains the GTK+ GUI.

> Package: libfm-dev
[...]
> Description: libraries for file management programming needs - developments headers

(Well, for a start that's too long.  I also notice these packages
have the word "Features:" in the boilerplate unindented, as if it
was a field in its own right.  Or is that just an artefact of the
quoted-printable mail format?)

[...]
>  .
>  This package contains the development headers.

  Description: file management support - development headers
   $BOILERPLATE
   .
   This package contains the development headers.

> 
> Package: libfm-utils
[...]
> Description: libraries for file management programming needs - utilities
[...]
>  .
>  This package contains the utilities(demo program).

If this is a single "demo" X executable interesting only to C
programmers, the package probably shouldn't be called "-utils"; if
it's multiple commandline tools, it might not belong in "Section:
libs".  I was going to cheat and read the filelist from the Ubuntu
version to find out, but that says it's empty:
 "http://packages.ubuntu.com/lucid/i386/libfm-utils/filelist";

I'm guessing that ideally it would be:

  Package: libfm-bin
  Description: file management support - demo binary
   $BOILERPLATE
   .
   This package contains a demonstration program.

...though my patch doesn't go so far as to change the name.

> Package: libfm0-dbg
[...]
> Description: library for creating files manager - debugging symbols
[...]
>  This package contains the debugging symbols.

This one just needs the boilerplate changes.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
--- control.orig	2010-03-28 12:09:51.000000000 +0100
+++ control	2010-03-28 12:32:44.000000000 +0100
@@ -17,25 +17,16 @@
 Section: libs
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: libraries for file management programming needs
- LibFM is a library packaging GLIB/GIO and provide higher level API and
- related window components as a library for file management programming
- needs, and make it easy to reuse for other programs.
- Features:
-  * Independent to any platform/desktop environment
-  * Use gio/gvfs as same as Nautilus to support remote storage, with
-    faster experience to users.
-  * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
-    WebDav...)
-  * Fast, low memory usage and low latency which is friendly to less
-    powerful hardware such as netbook and thin client/server.
-  * Trash can support (provided by gvfs).
-  * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE
-  * Core function separated from GUI, be able reuse with UI toolkit other
-    than GTK+, eg Qt4 or Enlightenment.
-  * Supports Drag and drop handling and supports XDS (X Direct Save).
-  * Provides some widgets for file management needs that are missing in
-    GTK+ and glib.
+Description: file management support - core library
+ LibFM provides Glib/GIO file management widgets. Features:
+  * Fast and light on memory usage, which is friendly to less
+    powerful hardware such as netbooks and thin clients;
+  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
+    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
+  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
+  * Supports Drag-and-Drop, using the X Direct Save protocol;
+  * Reusable design with the core functions separated out to
+    simplify porting to other GUIs.
  .
  This package contains the core function library.
 
@@ -43,25 +34,16 @@
 Section: libs
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: libraries for file management programming needs - GTK+ GUI
- LibFM is a library packaging GLIB/GIO and provide higher level API and
- related window components as a library for file management programming
- needs, and make it easy to reuse for other programs.
-Features:
-  * Independent to any platform/desktop environment
-  * Use gio/gvfs as same as Nautilus to support remote storage, with
-    faster experience to users.
-  * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
-    WebDav...)
-  * Fast, low memory usage and low latency which is friendly to less
-    powerful hardware such as netbook and thin client/server.
-  * Trash can support (provided by gvfs).
-  * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE
-  * Core function separated from GUI, be able reuse with UI toolkit other
-    than GTK+, eg Qt4 or Enlightenment.
-  * Supports Drag and drop handling and supports XDS (X Direct Save).
-  * Provides some widgets for file management needs that are missing in
-    GTK+ and glib.
+Description: file management support - GTK+ GUI library
+ LibFM provides Glib/GIO file management widgets. Features:
+  * Fast and light on memory usage, which is friendly to less
+    powerful hardware such as netbooks and thin clients;
+  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
+    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
+  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
+  * Supports Drag-and-Drop, using the X Direct Save protocol;
+  * Reusable design with the core functions separated out to
+    simplify porting to other GUIs.
  .
  This package contains the GTK+ GUI.
 
@@ -69,26 +51,16 @@
 Section: libdevel
 Architecture: any
 Depends: libfm0 (= ${binary:Version}), ${misc:Depends}, libfm-gtk0 (${binary:Version})
-Description: libraries for file management programming needs -
-developments headers
- LibFM is a library packaging GLIB/GIO and provide higher level API and
- related window components as a library for file management programming
- needs, and make it easy to reuse for other programs.
-Features:
-  * Independent to any platform/desktop environment
-  * Use gio/gvfs as same as Nautilus to support remote storage, with
-    faster experience to users.
-  * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
-    WebDav...)
-  * Fast, low memory usage and low latency which is friendly to less
-    powerful hardware such as netbook and thin client/server.
-  * Trash can support (provided by gvfs).
-  * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE
-  * Core function separated from GUI, be able reuse with UI toolkit other
-    than GTK+, eg Qt4 or Enlightenment.
-  * Supports Drag and drop handling and supports XDS (X Direct Save).
-  * Provides some widgets for file management needs that are missing in
-    GTK+ and glib.
+Description: file management support - development headers
+ LibFM provides Glib/GIO file management widgets. Features:
+  * Fast and light on memory usage, which is friendly to less
+    powerful hardware such as netbooks and thin clients;
+  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
+    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
+  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
+  * Supports Drag-and-Drop, using the X Direct Save protocol;
+  * Reusable design with the core functions separated out to
+    simplify porting to other GUIs.
  .
  This package contains the development headers.
 
@@ -96,27 +68,18 @@
 Section: libs
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: libraries for file management programming needs - utilities
- LibFM is a library packaging GLIB/GIO and provide higher level API and
- related window components as a library for file management programming
- needs, and make it easy to reuse for other programs.
-Features:
-  * Independent to any platform/desktop environment
-  * Use gio/gvfs as same as Nautilus to support remote storage, with
-    faster experience to users.
-  * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
-    WebDav...)
-  * Fast, low memory usage and low latency which is friendly to less
-    powerful hardware such as netbook and thin client/server.
-  * Trash can support (provided by gvfs).
-  * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE
-  * Core function separated from GUI, be able reuse with UI toolkit other
-    than GTK+, eg Qt4 or Enlightenment.
-  * Supports Drag and drop handling and supports XDS (X Direct Save).
-  * Provides some widgets for file management needs that are missing in
-    GTK+ and glib.
+Description: file management support - demo binary
+ LibFM provides Glib/GIO file management widgets. Features:
+  * Fast and light on memory usage, which is friendly to less
+    powerful hardware such as netbooks and thin clients;
+  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
+    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
+  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
+  * Supports Drag-and-Drop, using the X Direct Save protocol;
+  * Reusable design with the core functions separated out to
+    simplify porting to other GUIs.
  .
- This package contains the utilities(demo program).
+ This package contains a demonstration program.
 
 Package: libfm0-dbg
 Section: debug
@@ -125,23 +88,14 @@
 Depends: libfm0 (= ${binary:Version}), libfm-gtk0 (= ${binary:Version}),
 ${misc:Depends}
 Description: library for creating files manager - debugging symbols
- LibFM is a library packaging GLIB/GIO and provide higher level API and
- related window components as a library for file management programming
- needs, and make it easy to reuse for other programs.
-Features:
-  * Independent to any platform/desktop environment
-  * Use gio/gvfs as same as Nautilus to support remote storage, with
-    faster experience to users.
-  * Support GVFS and remote storage access (Windows SMB, FTP, SFTP,
-    WebDav...)
-  * Fast, low memory usage and low latency which is friendly to less
-    powerful hardware such as netbook and thin client/server.
-  * Trash can support (provided by gvfs).
-  * Clipboard operations are compatible for both GTK+, Gnome and QT/KDE
-  * Core function separated from GUI, be able reuse with UI toolkit other
-    than GTK+, eg Qt4 or Enlightenment.
-  * Supports Drag and drop handling and supports XDS (X Direct Save).
-  * Provides some widgets for file management needs that are missing in
-    GTK+ and glib.
+ LibFM provides Glib/GIO file management widgets. Features:
+  * Fast and light on memory usage, which is friendly to less
+    powerful hardware such as netbooks and thin clients;
+  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
+    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
+  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
+  * Supports Drag-and-Drop, using the X Direct Save protocol;
+  * Reusable design with the core functions separated out to
+    simplify porting to other GUIs.
  .
  This package contains the debugging symbols.
Source: libfm
Section: libs
Priority: extra
Maintainer: Debian LXDE Packaging Team
<pkg-lxde-maintainers@lists.alioth.debian.org>
Uploaders: Julien Lavergne <julien.lavergne@gmail.com>, Andrew Lee (李健
秋) <ajqlee@debian.org>
Build-Depends: cdbs, debhelper (>= 7.0.50~), autotools-dev,
libglib2.0-dev (>= 2.16), libgtk2.0-dev (>= 2.16), libmenu-cache1-dev,
intltool
Standards-Version: 3.8.4
Homepage: http://pcmanfm.sourceforge.net/
Vcs-Git: git://git.debian.org/git/collab-maint/libfm.git
Vcs-Browser: http://git.debian.org/?p=collab-maint/libfm.git;a=summary

Package: libfm0
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: file management support - core library
 LibFM provides Glib/GIO file management widgets. Features:
  * Fast and light on memory usage, which is friendly to less
    powerful hardware such as netbooks and thin clients;
  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
  * Supports Drag-and-Drop, using the X Direct Save protocol;
  * Reusable design with the core functions separated out to
    simplify porting to other GUIs.
 .
 This package contains the core function library.

Package: libfm-gtk0
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: file management support - GTK+ GUI library
 LibFM provides Glib/GIO file management widgets. Features:
  * Fast and light on memory usage, which is friendly to less
    powerful hardware such as netbooks and thin clients;
  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
  * Supports Drag-and-Drop, using the X Direct Save protocol;
  * Reusable design with the core functions separated out to
    simplify porting to other GUIs.
 .
 This package contains the GTK+ GUI.

Package: libfm-dev
Section: libdevel
Architecture: any
Depends: libfm0 (= ${binary:Version}), ${misc:Depends}, libfm-gtk0 (${binary:Version})
Description: file management support - development headers
 LibFM provides Glib/GIO file management widgets. Features:
  * Fast and light on memory usage, which is friendly to less
    powerful hardware such as netbooks and thin clients;
  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
  * Supports Drag-and-Drop, using the X Direct Save protocol;
  * Reusable design with the core functions separated out to
    simplify porting to other GUIs.
 .
 This package contains the development headers.

Package: libfm-utils
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: file management support - demo binary
 LibFM provides Glib/GIO file management widgets. Features:
  * Fast and light on memory usage, which is friendly to less
    powerful hardware such as netbooks and thin clients;
  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
  * Supports Drag-and-Drop, using the X Direct Save protocol;
  * Reusable design with the core functions separated out to
    simplify porting to other GUIs.
 .
 This package contains a demonstration program.

Package: libfm0-dbg
Section: debug
Priority: extra
Architecture: any
Depends: libfm0 (= ${binary:Version}), libfm-gtk0 (= ${binary:Version}),
${misc:Depends}
Description: library for creating files manager - debugging symbols
 LibFM provides Glib/GIO file management widgets. Features:
  * Fast and light on memory usage, which is friendly to less
    powerful hardware such as netbooks and thin clients;
  * Uses GIO/GVFS (like Nautilus) for Trash support and access to
    remote file systems (FTP, SFTP, WebDav, Windows shares, etc.);
  * Clipboard operations are compatible with GTK+/GNOME and QT/KDE;
  * Supports Drag-and-Drop, using the X Direct Save protocol;
  * Reusable design with the core functions separated out to
    simplify porting to other GUIs.
 .
 This package contains the debugging symbols.

Reply to: