Re: Proposal/Request for Comments: Formally extending package Descriptions to handle bulleted lists.
On Mon, Dec 12, 2005 at 03:09:52PM -0800, Daniel Burrows wrote:
> The attached text is a first draft of a proposed extension to the
> Description field to explicitly handle bulleted lists. The extended
> syntax allows list items to be treated specially by frontends (for
> instance, bullet characters can be replaced with graphics, and the
> body of the list item can be word-wrapped); current Descriptions should
> either parse correctly or be no worse off than they currently are.
> Current versions of aptitude implement this proposal.
Excellent initiative to work on this.
> Extensions to the syntax of Description blocks:
>
> As mentioned above, all lines beginning with two or more spaces are
> treated identically under current Policy. This proposal introduces
> the concept of a /bulleted block/. A bulleted block consists of a
> series of lines such that:
s/lines/series of items/, otherwise, you'd have a a series of lines that
each consist of a number of lines: ambigious (or at least confusing)
wording.
> (1) The first line begins with N > 2 spaces,
That should be N >= 2 I presume, otherwise, your examples are
inconsistent with this definition. Also, I think that for inclusion in
policy the text should make clear that the leading space required for
line continuation in the control file block is included in N.
> (2) The first non-space character of the first line is a bullet
> character, and
>
> (3) Each subsequent line begins with at least N + 1 + M spaces,
> where M is the number of spaces immediately following the first
> non-space character of the first line.
I'd note that M might be as small as zero. This is implied by the lack
of prohibition in (2), but it can't hurt to be clear.
> For the purposes of this definition, the bullet characters are [*-+].
Better write [*+-], to prevent needless ambiguity with regex syntax,
where [*-+] actually means '*' or '+', excluding '-'. Or just list the
three characters.
In concreto, I'd suggest using the following definition instead, also
covering the nested bulleting that's only defined-by-example below:
For in policy 5.6.12:
* Those starting with two or more spaces. These will be displayed
verbatim, unless it is part of a bulleted list. The first line of a
bulleted list will start, after the two or more spaces, with a bullet
character ('*', '-' or '+'), followed by zero or more spaces,
followed by the beginning of the item text. Each line after this line
will be either:
- continued bullet item text, indented at least as far as the
beginning of the bullet item text on the line of the last bullet,
or
- a subsequent bullet item, with the same bullet item character,
indented at the same level, with the item text also starting at
the same (or deeper) level as the first bullet item
- a nested bullet item, according to the rules of a first top-level
bullet item line, but indented at least as deep as the bullet item
text of the current level
Every other line not matching the definition above is considered to be
part of a verbatim text block, and the bullet item list is then
supposed to be terminated on the preceeding line.
</definition>
I do think this does make it a bit complicated though... hm.
> The following are examples of bulleted blocks:
>
> ===== snip here =====
> * If Peter Piper picked a peck of pickled peppers, how many pickled peppers did Peter Piper pick?
>
> *Fourscore and
> seven years ago,
> our forefathers brought forth upon this continent
> a new nation.
> .
> -- Abraham Lincoln, 16th President of the United States of America
According to your and my definition, this would be a bullet item too,
like (in HTML) <li>- Abraham Lincoln (...) America</li> ? Or how do I
misread your definition then, if this is *not* an instance of a bulleted
list?
Alternative:
A totally different way might be to exploit policy's opportunity to
extending the description syntax. Policy 5.6.12 explicitely states that
lines starting with a dot should not be used and are left open for
future expansions. So why not use *that*? Like, definition by example:
Descrition: Great package to moo
This package totally rocks, because:
. It has super cow powers
. The internet access point at the Wig and Pen bar is using this
package too, and customers are happy with it
. This includes Lachlan McOmish
. And more stuff
This
is
a
verbatim
block (indented at least one space more than normal continuation
bullet text would need to be)
. It's written in whitespace, with a level editor in brainfuck
This will allow for both verbatim blocks in bulleted lists, will leave
verbatim blocks totally like they are today, no redefinitions, and
enables to be defined more easily (no need to care for what happens with
looks-like-bulleted-but-isn't-bulleted stuff).
Only disadvantage I see is closing the door for even further expansions,
plus no selection for bullet mark, but that can be helped by writing .*,
.- and .+ instead. It will also allow to extend to .1 (for numbered) and
.o (for the o-bulleted) lists.
--Jeroen
--
Jeroen van Wolffelaar
Jeroen@wolffelaar.nl (also for Jabber & MSN; ICQ: 33944357)
http://Jeroen.A-Eskwadraat.nl
Reply to: