Bug#525843: support for encoding long descriptions using a "standard" text-based markup language
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. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: