On Fri, Sep 11, 2009 at 08:00:41PM -0500, Manoj Srivastava wrote: > 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---
I have to say, I find the latter more readable. The former is ambiguous. > 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. Autonumbering seems a nice feature, but for some one reading the plain text version, this probably not so much a good idea. > 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**. I do not find *emphasis* very readable in plain text. However a case could be made for marking some words as having a special meaning , for example if policy stated that writing *foobar* denotes that foobar is the name of a Debian package, then HTML converted could link foobar to packages.debian.org/foobar automatically. For example the description of xfig could be written as: ... You should also think about installing *xfig-doc*, which contains the documentation and *xfig-libs*, which contains several clip art libraries. ... and converted to HTML as You should also think about installing <a href="packages.debian.org/xfig-doc"> xfig-doc</a>, which contains ... (Sorry I am lacking useful English terminology here). > 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. Would you rewrite this spec in both Markdown and restructured text so that we can compare ? (two/third joking of course :)) Cheers, -- Bill. <ballo...@debian.org> Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
