Re: RFC: Better formatting for long descriptions

[Andreas Tille <tillea@rki.de>]

On Thu, 16 Apr 2009, Ben Finney wrote:

> Note that, like Manoj, I'm suggesting only a *subset*, not the full
> specification.

Well, in this thread we had several suggestions reaching from complete
change to different format up to "not in detail specified" subsets of
other formats.  IMHO this does not bring us foreward a single step.
If we want to move foreward we have to make sure that we will not be
forced to touch every single package because such an intend will be
bound to fail and every minute spended in discussion here is simply
wasted.  So if you suggest a subset of a specification please state
clearly which subset and whether it works with currently existing
descriptions.  I'd volunteer to set up a doodle poll with suggestions.

If you make a suggestion please answer the following question:

  A. Does the suggestion enable parsing logical structures like
     two level itemize lists?
     (This is what I want to approach and what is IMHO needed)
  B. Does the suggestion enable keeping the majority of description
     untouched and enables keeping the currently existing tools?
     (This is important to gain any acceptance)

If one of the question above is answered with "no" please mention
whether you are volunteering to do the work which is needed to
port the existing stuff to match your suggestion.

Currently I would feed the poll with 4 suggestions:

  0. Keep anything as unstructured as it is.
     Answer to A: no
     Answer to B: yes

  1. Use '*' for first order item lists, '-' for second order
     item lists and use '  ' (exactly two spaces) before the
     '*' and '    ' (exactly four spaces) before the '-'. After
     '*' and '-' exactly one space should be used and continued
     lines should start in the same column as the text starts
     above.
     Answer to A: yes
     Answer to B: yes

  2. Use '*' for first order item lists, '-' for second order
     item lists.  Spacing does not matter as long as continued
     lines will start in the same column as the text above.
     Answer to A: yes
     Answer to B: yes

  3. Use any character of ('*', '-', '+') to start a list and
     mark the level of the list by strictly following spacing
     rules and use '  ' (exactly two spaces) before the selected
     character for starting first order list and '    ' (exactly
     four spaces) before the character for starting second order
     list. After the marker symbold exactly one space should be
     used and continued lines should start in the same column as
     the text starts above.
     Answer to A: yes
     Answer to B: yes

If you want to make further suggestions just append this list.
I'll start a doodle poll next Monday.  Depending from the outcome
of this poll I will submit a patch for "6.2. Best practices for
debian/control".

Does this sound reasonable?

Kind regards

        Andreas.

--
http://fam-tille.de