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

Re: Proposal/Request for Comments: Formally extending package Descriptions to handle bulleted lists.



On Mon, Dec 12, 2005 at 05:49:02PM -0600, Peter Samuelson <peter@p12n.org> was heard to say:
> 
> [Daniel Burrows]
> >   (1) The first line begins with N > 2 spaces,
> 
> Don't you mean N >= 2?
> 
> >   (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 think that's overgeneral.  I do not see the point in allowing M != 1.
> I say keep the spec simple; forcing frontends to include parsing
> complexity that doesn't even add anything useful is a Bad Thing.
> 
> (If aptitude wants to handle M != 1 in order to make certain legacy
> descriptions look better, fine, but I don't think it should be
> explicitly condoned.)

  Good point.  I've adjusted this in my copy (updated version attached).

  Daniel
			      Abstract:

  This document describes a proposed extension to the Description
formatting policy (policy section 5.6.13) to support better formatting
of bullet lists in package descriptions.  The proposed policy is
primarily a formalization of existing best practice regarding bullets;
most current package descriptions will parse as expected with no
changes, and packages that do not can easily be converted to the new
format without degrading presentation in legacy package management
tools.

  The Description extensions described in this document are presently
implemented in aptitude (>= 0.4.0).

		      Background and Motivation:

  Policy 5.6.23 provides for "preformatted" lines in descriptions.
These are lines beginning with at least two spaces, and will be
displayed verbatim; they are either unwrapped or hard-wrapped.  The
current best-practice approach to including bullet lists in package
descriptions is to write each line of the list as a preformatted line;
for instance,

===== snip here =====
 QEMU is a FAST! processor emulator: currently the package supports
 arm, powerpc, sparc and x86 emulation. By using dynamic translation
 it achieves reasonable speed while being easy to port on new host
 CPUs. QEMU has two operating modes:
 .
  * User mode emulation: QEMU can launch Linux processes compiled for
    one CPU on another CPU.
  * Full system emulation: QEMU emulates a full system, including a
    processor and various peripherials. It enables easier testing and
    debugging of system code. It can also be used to provide virtual
    hosting of several virtual PC on a single server.
 .
 As QEMU requires no host kernel patches to run, it is very safe and
 easy to use.
===== snip here =====

  This convention has several serious limitations, however.  Perhaps
most importantly, it does not gracefully accomadate smaller terminals;
while other paragraphs are word-wrapped by conforming user interfaces,
word-wrapping of these preformatted paragraphs is (rightly) forbidden.
This leads to poor readability when the terminal size is decreased;
for instance, formatting to 60 columns produces:

===== snip here ===== 
QEMU is a FAST! processor emulator: currently the package
supports arm, powerpc, sparc and x86 emulation. By using
dynamic translation it achieves reasonable speed while being
easy to port on new host CPUs. QEMU has two operating modes:

* User mode emulation: QEMU can launch Linux processes compi
led for
  one CPU on another CPU.
* Full system emulation: QEMU emulates a full system, includ
ing a
  processor and various peripherials. It enables easier test
ing and
    debugging of system code. It can also be used to provide
 virtual
    hosting of several virtual PC on a single server.
 .
 As QEMU requires no host kernel patches to run, it is very
safe and easy to use.
===== snip here =====

  In contrast, the proposed mechanism allows this description to be
formatted in 60 columns as follows:

===== snip here =====
 QEMU is a FAST! processor emulator: currently the package
 supports arm, powerpc, sparc and x86 emulation. By using
 dynamic translation it achieves reasonable speed while
 being easy to port on new host CPUs. QEMU has two operating
 modes: 
 
 * User mode emulation: QEMU can launch Linux processes
   compiled for one CPU on another CPU. 
 * Full system emulation: QEMU emulates a full system,
   including a processor and various peripherials. It
   enables easier testing and debugging of system code. It
   can also be used to provide virtual hosting of several
   virtual PC on a single server. 
 
 As QEMU requires no host kernel patches to run, it is very
 safe and easy to use.
===== snip here =====

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:

  (1) The first line begins with N >= 2 spaces,

  (2) The first non-space character of the first line is a bullet
      character; it is followed by a single space and a non-bullet
      character, and

  (3) Each subsequent line begins with at least N + 2 spaces.

  For the purposes of this definition, the bullet characters are [*-+].

  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

     * In
        - Hartford,
        - Hereford,
          and
        - Hampshire,
       hurricanes hardly happen.
===== snip here =====

  The third example above demonstrates that bulleted blocks may be
nested: while the entire sentence is itself a block, there are three
sub-blocks: one each for the second and fifth lines of the outer
block, and one comprising the third and fourth lines.

  The individual lines within a bulleted block should be parsed as if
N+1 characters were stripped from the left-hand side of the block.
For instance, in the second example above, the contents of the block
should be parsed as if the following non-bulleted text had been
encountered:

===== snip here =====
 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
===== snip here =====

  In particular, the first four lines will form a word-wrapped
paragraph, the fifth will generate a blank line, and the sixth will be
displayed literally, without wrapping.

		Presentation guidelines for frontends:

  Bulleted blocks at the same nesting level should be indented
equally; bulleted blocks at deeper nesting levels should be indented
farther than those at outer nesting levels.  The bullet characters
themselves may, at the frontend's discretion, be displayed literally,
replaced with other characters, or replaced with a graphical bullet
representation.  The recommended approach is to choose a bullet
depiction according to the nesting level of the block.

	       Recommendations for Description writers:

  Follow best practices for lists.  When writing a bulleted list,
indent the entire list by at least two spaces, place a space after the
bullet, and indent subsequent lines of each item to align with the
text following the bullet:

===== snip here =====
  * Yet another silly example
    bulleted list.
===== snip here =====

  Avoid placing bullet characters at the beginning of a line when they
are not meant to act as a bullet.  This is most likely to occur with
hyphens:

===== snip here ======
  It was the greatest -- the most extravagent
  -- nay, the most decadent abuse of punctuation
  that the English language had yet seen.
===== snip here =====

  While it is probably good form to avoid this everywhere, it is only
required to do so for preformatted lines.

	       Backwards compatibility of Descriptions:

  Descriptions written to the guidelines above will degrade gracefully
in older package management frontends.  Indeed, these guidelines are
the current best practice for writing bulleted lists.

	Backwards compatibility of the new parsing algorithm:

  Unfortunately, not all descriptions are parsed "correctly" by this
new algorithm.  The sources of "incorrect" parses are:


  (1) Invalid list formatting; for instance,
===== snip here =====
 * This bulleted list is not
   properly formatted anyway.

  * This one isn't either; these lists
 will not display properly in any frontend.
===== snip here =====

      These are bugs and should be fixed regardless of whether this
proposal is generally accepted.



  (2) Valid but unorthodox list formatting.  One common example of
      this is a variable amount of indentation following the bullet:

===== snip here =====
  * This bulleted list was
   written before the list policy.
===== snip here =====

      Although this list will not receive the benefits of the
      bulleted-item support, its presentation will not be worse than
      in old frontends: the first line will be word-wrapped and the
      remainder will be hard-wrapped.  Furthermore, fixing the
      description in this case is trivial.

      It would be possible to extend the new syntax to cover some such
      cases, but it is probably easier to simply adjust package
      descriptions that fail in this way (possibly by providing a
      lintian test, e.g.).


      Another common problem is the use of 'o' as a bullet character;
      again, this is trivially fixed. (Parsing 'o' as a bullet
      character was rejected, due to the fact that it may be a word in
      some languages)

  (3) Bullet characters that appear at the beginning of a
      pre-formatted line, but are not actually bullets.

      This case is (so far) purely theoretical: I have yet to see any
      example of a description that triggers it.  I mention it only
      for the sake of completeness.  As with the other cases, this can
      be easily fixed (by reflowing the unformatted description so
      that the bullet character appears at the end of the previous
      line).

Attachment: signature.asc
Description: Digital signature


Reply to: