Re: RFC: Better formatting for long descriptions
On Thu, Apr 16 2009, Andreas Tille wrote:
> On Thu, 16 Apr 2009, Manoj Srivastava wrote:
>
>> Any script should be able to take the top 4 symbols currently
>> used, and be able to detect them. I think *, +, - and o cover most
>> packages, and the scripts in question can be readily expanded. All
>> kinds of markup languages already do something similar. (markdown,
>> Emacs org-mode, mediawiki, etc)
>
> Perhaps you missed the point that it is not only the very character
> which is used but also the broken spacing which prevents scripts from
> detecting levels of itemizing list.
>
> Yes, we have more than one level itemizings in our descriptions (see
> my initial posting. Detecting these would need either a defined
> character or a defined spacing (IMHO an 'and' would be better than
> a non-exclusive 'or' here).
Umm. I am not sure that follows. I am also not convinced we need
to invent our own rules. Text::Markdown or Text::MultiMarkdown could
help. And they do not seem to have issues with recognizing
indentation/different characters as denoting levels of lists.
>
>> I find the descriptions on packages.d.o just fine right now.
>
> IMHO it is no argument that a specific person is happy with the layout
> everybody else is.
Just like it is no argument that someone think something is ugly
that means everyone thinks so too.
> If a text has a certain logic it should to be
> supported by the means a certain output style has. HTML can express a
> list and so it should if we want to express lists.
And we do not need to specify any more rigid rules than
established systems like markdown do in order to achieve that. Indeed,
we can just pipe the description though markdown, and use the html
>
>> Having sad that, I would not be averse to specifying that leading
>> white space and *, +, and - would be acceptable as bullet marks (I
>> thought specifying which mark at which level was overspecification).
>
> So you would be in favour of specifying only the amount of white space
> to define a level?
You do not have to specify the level. Just that the indentation
be sufficient for the user or markdown to be able to differentiate what
level the item is at.
> If this might be accepted as a rough consensus it is at least helpful
> to enable tools detecting what they need to detect. Even if my
> esthetical feeling goes beyond this I can accept this. But you also
> specified three characters (*, +, and -) so do you want to restrict
> the acceptable set yourself (for instance not accept 'o')?
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.
manoj
http://en.wikipedia.org/wiki/Markdown
http://markdown.infogami.com/
http://daringfireball.net/projects/markdown/syntax
--
Man's horizons are bounded by his vision.
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: