What I'm going to do: Was: RFC: Description text in packages

[Richard Hughes]

On Wed, 2008-12-17 at 13:04 -0800, Toshio Kuratomi wrote:
> In that case, you're going to have a lot of problems with adding
> Markdown in PackageKit upstream.

http://www.packagekit.org/pk-faq.html#markup

> I doubt heavily that we'll be able to
> get people within Fedora to agree to format their %descriptions as
> markdown let alone the larger community of distributions.

I don't want people to change anything. If you use markdown syntax (or
something similar to the syntax) then everything just works. If you use
something oddball (☠), then PackageKit is going to give up and just
display the text as it is, probably with incorrect wrapping.

> The problem is that Markdown and other non-intrusive formats (like
> reStructuredText) don't have enough information to tell if it's
> "invalid".  For instance, if my Bodhi comments have:
> 
> # Fix an issue with char *foobar and all void* on gcc-5
> # Fix call to __init__ in python bindings.

Then you're going to get two titles. Seriously - who does that? If you
follow what 99% of other people are doing and either do:

* lists
 * that
 - most
- people
 +   use

Then it'll just work.

> Markdown will mangle what I intended because there are three constructs
> in there that look like valid Markdown.

Right, it'll make italic the "foobar and all void" line. I really don't
think putting code in update descriptions is a good idea, for the very
point of them is to tell people if they need to do the update. A better
message would be:

* Fix compile on GCC-5

and then provide a link to the mailing list with more information. If
that's not acceptable, writing "*foobar and all void *" would prevent it
being marked italic.

> To use a non-intrusive format, we need to specify the format being used
> either in a specification or as metadata to the %description tag.  Both
> of those solutions would have to be hashed out with the rpm authors.

That's never going to happen. Most busy people struggle with good
descriptions and bodhi update text in plain text, ask them to do it in
SGML/html/some-other-markup and even less people will be bothered.

Richard.