Re: RFC: Better formatting for long descriptions

[Ben Finney <ben+debian@benfinney.id.au>]

(following up on IRC discussion)

Manoj Srivastava <srivasta@debian.org> writes:

>         I suggest we follow a convention and tool set already in place,
>  with multiple language bindings, if you must insist on adding rules to
>  the long description.
> 
>         There are alternatives (Text::Textile comes to mind), but
>  Markdown has better language support, so long description parsers might
>  have an easier time.
> 
>         I suggest, for readability, to use a subset of markdown; the
>  link and image tags are not that human readable.

reStructuredText <URL:http://docutils.sourceforge.net/rst.html> (reST)
is, I argue, a superior choice to Markdown for our existing format.

Markdown explicitly assumes the writer is going to punt to HTML for
anything not covered by Markdown, which severely limits its future
flexibility in contexts where we don't want to put HTML in the source.

reST, on the other hand, makes no such assumptions about enclosing
context; it was initially designed for documentation in program source
code, which is much closer to our needs for text in a control field.

It also helps that the simple bullet lists that are the most common case
are perfectly valid in reST too.

-- 
 \           “Never express yourself more clearly than you are able to |
  `\                                               think.” —Niels Bohr |
_o__)                                                                  |
Ben Finney