Re: RFC: Better formatting for long descriptions
On Thu, 16 Apr 2009, Manoj Srivastava wrote:
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.
I tried to suggest *any* rule which works. I'm not in favour of invanting
new rules. But the rules should be simple enough to not break any existing
tool.
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.
If I interpret your first link [1] right this are even *more* rules as
I suggested.
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.
Please do not split my paragraphs to blur my arguing. Thanks.
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
Have you tested this suggestion whether the current long descriptions will
render correctly?
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.
I'm sorry - I do not know markdown whether it is clever enough to render
the lists in all long descriptions. But as long as the hint "please
make sure that your long description renders with markdown" is not
written in any of our documents I really doubt that. May I draw the
conclusion that you are also in favour of some rules but not really
happy with the rules I suggested? That's really fine for me. I just
want *any* rule which *works* and is written down somewhere to enable
us filing bug reports against packages which do not follow this rule.
I think I mentioned this in my postings of this thread.
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 do not want any complicated tool to parse our long descriptions.
In principle they are really easy to parse. I want to have the
simplest possible rule set which enables us to reliable parse the
logic of our long descriptions. While you claim to be against rules
you propose even harder to apply rules. At least for me your suggestions
are confusing and just bluring the issue.
I suggest, for readability, to use a subset of markdown; the
link and image tags are not that human readable.
Yes - that's perfectly fine. We are just using a subset of markdown
actually - a much simpler one than the suggested, without features like
italics and strong, headings etc. And we do not really need it - we
just should keep it simple to not break any existing tool. If there
is a library which reliably can detect the logic of the current long
descriptions probably nothing has to be changed. But I doubt there is
one and I really wonder why anybody who is happy with the current rendering
is suggesting even more complex things.
Kind regards
Andreas.
[1] http://en.wikipedia.org/wiki/Markdown
--
http://fam-tille.de
Reply to: