Re: RFC: Better formatting for long descriptions
On Thu, Apr 16 2009, Andreas Tille wrote:
> 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.
Which is good, since Markdown/ReST rules for lists will only
make the lists using o as the bullet out of whack.
>
>> 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.
None of which are mandatory. All the package descriptions I read
in /var/lib/dpkg/available seems to pass, though a couple had italics
in strange places. This is not a fatal flaw.
>
>>>> 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.
Heh. Ever heard of inline answers?
>> 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?
Yup.
>>> 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
Doubt is fine. Actually reading the package descriptions would
have been better.
>>>>> Tag \* was used 9277 times (68.0900%)
>>>>> Tag - was used 3837 times (28.1600%)
>>>>> Tag + was used 120 times (.8800%)
These work.
>>>>> Tag o was used 390 times (2.8600%)
These do not.
Now, using *italic* had a few issues. There are 99 lines in
available where * is not used as a list item tag.
Of these 99 lines, 27 places the *word* is used for emphasis,
meaning that 72 places in the available file * is used as a
wildcard. But not all of these are an issue:
--8<---------------cut here---------------start------------->8---
__> echo ' bsd* and others.' | markdown
<p>bsd* and others.</p>
--8<---------------cut here---------------end--------------->8---
In those 72 places, only 24 descriptions did we have a second *
show up, to anchor the other end of the mistaken emphasis.
> 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 you try it out, before handwaving vague FUD
around. Even tnftp description works fine with either. There are very
few descriptions (about 24 or so) where we might have unwanted
emphasis. I think we can have that fixed.
>> 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 would simplify the rule, as opposed to having a trivial
library call in the tool. Indeed, reusing the libraries provided is
*less* work for the parser, than a NIH new parser.
>
>> 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.
I think we need the emphasis almost as much as we need lists;
and people are already using *word* for emphasis in desciptions
(though not all that many).
manoj
--
Teutonic: Not enough gin.
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: