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

Re: RFC: Better formatting for long descriptions

On Thu, 16 Apr 2009, Guillem Jover wrote:

,-- count-bullet-chars.sh --
total=`grep "^ *[-+\*o] " $lists | wc -l`
for tag in "\*" "-" "+" "o"; do
 items=`grep "^ *$tag " $lists | wc -l`
 percent=`echo "scale=4; $items / $total * 100" | bc`
 echo "Tag $tag was used $items times ($percent%)"

Tag \* was used 9277 times (68.0900%)
Tag - was used 3837 times (28.1600%)
Tag + was used 120 times (.8800%)
Tag o was used 390 times (2.8600%)

Regardless of the numbers though (which have moved lately slightly in
favour of '-' due to the recommendations from the Smith reviewing

I have not found any recommendation regarding this at the SRP Wiki page [1].
I vaguely remember that this Smith project was initially driven by a French
guy who might try to push a French habit into the English world. ;-)
Do you have any link to those recommendation which perhaps should be fixed
in the first place.  IMHO the Smith Review Project would be a first place
were we could start kind of a standardisation of this issue - it seems there
is no "stronger" place to move this suggestion to.

I've always found the asterisk the obvious character to use
for bulleted lists, as it's the one ressembling the most a bullet, and
it's the one we use in changelog entries and similar.

I perfectly agree here.  Even if I tend to a "I do not care about the actual
character we use as long as it is a defined one" opinion the statistics above
shows clearly a preference and we should turn this preference in a
recommendation and ask people to stick to this recommendation.

So could we settle down with the agreement:

  '  * '   for first order lists and
  '    - ' for second order lists.

I would like to push this to SRP *and* "6.2. Best practices for debian/control"
of developers reference.  This would finally allow us to file wishlist bug
reports against packages which do not follow this recommendation.

Kind regards


[1] http://wiki.debian.org/I18n/SmithReviewProject


Reply to: