Bug#525843: support for encoding long descriptions using a "standard" text-based markup language

[Manoj Srivastava <srivasta@debian.org>]

Hi,

        There are some differences in how thee systems define lists; and
 I think markdown is more forgiving with simple lists Consider that
 continuing lines in markdown lists do not have to be aligned after the
 white space:
Markdown
--8<---------------cut here---------------start------------->8---
* blah blah blah
more blah blah is fine
--8<---------------cut here---------------end--------------->8---

restructured.
--8<---------------cut here---------------start------------->8---
* blah blah blah
  more blah blah needs to be precisely aligned
--8<---------------cut here---------------end--------------->8---

        Numbered list in markdown do not have to be sequential, but in
 Rst you use #. or you need to have them sequential. On the other hand,
 rst is way better with definition lists or field lists; I just think
 that plain lists are more likely to belong in a description field.

        Block quotes in Rst are just indented paragraphs, and seem
 closer to the behaviour we currently have (Markdown uses > to do
 block quotes) . Advantage Rst here, I think.

        So, here is my take on a subset that needs to be supported in
 policy (I do not think we need titles, don't you agree?)

 a) Unordered lists use asterisks, pluses, and hyphens — interchangeably
    — as list markers.
 b) Ordered lists use numbers followed by periods. 
    1) The numbers need not be i sequence -- but  you should still start
       the list with the number 1.
    2) The numbers need to be in sequence -- but may use #. instead to
       get auto numbering.
 c) List markers typically start at the left margin, but may be indented
    by up to three spaces. List markers must be followed by one or more
    spaces or a tab.
 d) A hyperlink reference may directly embed a target URI inline, within
    angle brackets: <http://www.debian.org>
 e) nested lists are created by indenting the nested list
    1) by at least 4 spaces, or 
    2) have a blank line above, and line up with the previous
       paragraph.
 f) List items may consist of multiple paragraphs. Each subsequent
    paragraph in a list item must
    1)  have its first line indented by at least 4 spaces, or
    2)  must line up with the paragraph above, relative to the bullet
        marker
 g) Emphasis is provided by surrounding the text with '*'. Like
    *emphasis*. Stronger emphasis is provided by doubling the '*' --
    like **strong**.
 
        Once we decide on which language to use, I can tighten up the
 spec above. By sticking to these conventions, I think the plain text
 description is readable, and indeed, conveys the intent.

        manoj
-- 
Honesty is for the most part less profitable than dishonesty. Plato
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C