[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: RFC: Better formatting for long descriptions

On Fri, Mar 20, 2009 at 02:45:09PM +0100, Andreas Tille wrote:
> I do not propose drastic changes but a start for "Best practices"
> might be reasonable and perhaps some lintian warnings might help to
> remind developers to move to some standard.

Laudable initiative, thanks for raising the issue. The current
handling of "list" is dumb at best.

I agree with Martin that we should avoid the NIH syndrome though, but
that does not necessarily mean that we should switch entirely control
files to a new format. It just means that we should think big.

In particular, I observe that we (IIRC) already have psuedo-parsing
code which is used at least by packages.d.o to render as proper HTML
lists the pseudo-lists which come from long descriptions. That makes
evident, at least to me, that long descriptions need some kind of
formatting for most of their use cases (packages.d.o is one, the
interface of a GUI package manager is another one).

In that respect, resisting the NIH syndrome just means choose an
already existing text-based markup language and adopt its
convention. For instance, we can just say that long description lists
have to be formatted as Markdown lists (modulo some extra bits needed
to not violate 822 parsing). That would be synergistic with a possible
future switch to Markdown for the whole markup of long
descriptions. Note that I don't care in particular about Markdown, it
can also be restructured text for what I care.

But please check that your convention matches such a markup language
and please say explicitly so in your proposal. That would also
implement a somewhat principle of least surprise for people coming
from those languages.


Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
zack@{upsilon.cc,pps.jussieu.fr,debian.org} -<>- http://upsilon.cc/zack/
Dietro un grande uomo c'è ..|  .  |. Et ne m'en veux pas si je te tutoie
sempre uno zaino ...........| ..: |.... Je dis tu à tous ceux que j'aime

Attachment: signature.asc
Description: Digital signature

Reply to: