Re: Request for review of a package description
Dmitrijs Ledkovs <dmitrij.ledkov@gmail.com> writes:
> Please CC me - I'm not subscribed, thanks =)
Done.
> Package: xiphos
> Description: environment for Bible reading, study, and research
This synopsis is fine.
Is Xiphos essentially one program, or several?
> Xiphos is Bible study software for GNOME.
This is grammatically correct (“software” is an uncounted noun), but a
bit vague. If it's one program, I would expect “a Bible study program”.
Also, we may as well be explicit about what GNOME is:
Xiphos is a Bible study program for the GNOME desktop environment.
In fact, taking inspiration from your later description of the
‘xiphos-data’ package, I would say this description would do well to
start with:
Xiphos is a Bible study program for the GNOME desktop environment.
It is based on The SWORD Project by the CrossWire Bible Society, a
framework for tools to assist studying the Bible and additional
information like commentaries, dictionaries and other texts.
> It is a digital text reader with
> bookmarks and full text search. One of the exclusive reader features is
> parallel view of alternative and translated versions of the same text.
> .
> In addition it allows you to keep personal per-verse notes. For larger
> commentaries there is also a dedicated rich-text study pad. The personal
> commentary supports spell checking and can also be searched.
I would re-work these into “what's this about” features, versus “what
makes this package special” features:
This package provides the main Xiphos program. It is a digital text
reader with bookmarks and full-text search.
.
Xiphos allows viewing multiple versions of the same text, for
parallel reading of alternatives or translations. It also provides
personal verse-specific notes and a rich-text study pad, both of
which have spell checking and full-text search.
> Xiphos is based on The SWORD Project by the CrossWire Bible Society, a
> framework for providing tools useful for studying the Bible and additional
> information like commentaries, dictionaries and other texts using your
> computer.
> .
> Xiphos has a built-in facility to browse CrossWire repositories of freely
> distributed content and install it.
> .
> Other software based on The SWORD Project are: BibleTime, BibleMemorizer and
> Bibledit.
These three paragraphs seem to dominate the description; hopefully you
agree that the re-worked intruduction above makes most of this redundant.
Xiphos has a built-in facility to browse and install
freely-distributed content from CrossWire repositories.
> Package: xiphos-data
> Description: data files for Xiphos Bible study software
> Xiphos is Bible study software for GNOME. It is based on The SWORD Project by
> the CrossWire Bible Society, a framework for providing tools useful for
> studying the Bible and additional information like commentaries, dictionaries
> and other texts using your computer.
> .
> This package contains the data files that are necessary to use Xiphos.
Good, but I would re-work this so the introduction is equally applicable
to both ‘xiphos’ and ‘xiphos-data’, as above. So:
Xiphos is a Bible study program for the GNOME desktop environment.
It is based on The SWORD Project by the CrossWire Bible Society, a
framework for tools to assist studying the Bible and additional
information like commentaries, dictionaries and other texts.
.
This package contains the data files that are necessary to use Xiphos.
> Package: gnomesword
> Description: Dummy upgrade package for GnomeSword, now Xiphos
The package synopsis should be written as it would appear within a full
sentence. So leading capitalisation is wrong here. Instead:
transitional package for GnomeSword, now Xiphos
> This is a transitional package and can safely be removed. GnomeSword has been
> renamed to Xiphos.
> .
> Xiphos is Bible study software for GNOME. It is based on The SWORD Project by
> the CrossWire Bible Society, a framework for providing tools useful for
> studying the Bible and additional information like commentaries, dictionaries
> and other texts using your computer.
> .
> See xiphos package instead.
For a transitional package, there's no real need to go into long
description about the target package; just reference the reader to that
package:
This is a transitional package and can safely be removed. GnomeSword
has been renamed to Xiphos; see the ‘xiphos’ package instead.
--
\ “I have a microwave fireplace in my house. The other night I |
`\ laid down in front of the fire for the evening in two minutes.” |
_o__) —Steven Wright |
Ben Finney <ben@benfinney.id.au>
Reply to: