On Tue, Dec 13, 2005 at 01:21:41AM +0100, Jeroen van Wolffelaar <jeroen@wolffelaar.nl> was heard to say: > On Mon, Dec 12, 2005 at 03:09:52PM -0800, Daniel Burrows wrote: > > 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. Each bulleted block is one bullet item -- the syntax doesn't care about sequences of items, just individual ones (although the frontend is free to treat sequences differently from lone items). This can probably be made clearer. How about this wording? ===== snip here ===== 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 represents the contents of a single list item; it consists of a series of lines such that: ===== snip here ===== > > (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. As was noted in another reply, it probably makes sense to require M == 1 in the spec; only a few packages that I've seen use anything else and it looks best in legacy frontends. > > 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. Good point. I'm afraid that I'm guilty of being a bit lazy here. > In concreto, I'd suggest using the following definition instead, also > covering the nested bulleting that's only defined-by-example below: It actually is defined, but you have to read between the lines. (it's the bit about parsing as if N+M spaces were stripped) Unfortunately, my example was wrong! (see attachment) > For in policy 5.6.12: [snip] As you noted, this is a bit hard to read; I'll probably tackle the problem of writing this up for Policy at some point in the future, once there's some agreement on what the format should be. > > 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? Yes, that's a good point. My example includes something that parses incorrectly :-). Note, however, that in the wild there are exactly two packages that break this way in aptitude out of the whole archive (checked with a regexp search), and that even these would not break if we required a space after the bullet character. > 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: I don't like this approach as much for a couple reasons -- it's not as natural (the format I proposed looks fine without any interpretation at all), you'd have to edit a lot of packages (most bulleted lists are in the right format already, in my observation), and it might not display properly in legacy frontends (frontends might display them literally, but Policy is silent on how these lines should be handled; aptitude IGNORES everything past the dot!) Daniel
Attachment:
signature.asc
Description: Digital signature