Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Thu, 23 Apr 2009, Daniel Burrows wrote: For the sorts of markup our descriptions have now it'll be fine, but it's my experience that when you give people a hammer they start hitting everything that's vaguely nail-shaped with it. :-) ROFL. The whole time of discussion was well spent just for this quote. ;-) I took the freedom to put a German translation into the fortunes-de. But if people want to use markdown, I'll render it. Same for me Andreas. -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, Apr 21, 2009 at 09:31:31AM +0200, Andreas Tille til...@rki.de was heard to say: Moreover I see no reason to bind anybody to a certain library like markdown. My experience has shown that people will insist on their very own way to do things. Do you think apt, aptitude, synaptic etc. developers would be happy if you start filing bug reports to make them use markdown? So my suggestion leaves perfectly space for using markdown as well as even raw text output - which would look also better with consistent formatting. I'm happy to support whatever markup language people want to use. My only concern with markdown is that I use it for my blog, and I periodically run into weird cases where the formatting doesn't work as expected. It seems to be especially bad when you start nesting formatting elements inside each other (quoted text inside a list inside a list is one example I found in the past). I've made a Markdown version of the release notes for aptitude releases for the last year or so and I always seem to find myself randomly adjusting indents until it stops producing the wrong HTML. For the sorts of markup our descriptions have now it'll be fine, but it's my experience that when you give people a hammer they start hitting everything that's vaguely nail-shaped with it. :-) But if people want to use markdown, I'll render it. Daniel -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, Apr 21, 2009 at 11:36:31PM +0200, Vincent Danjean wrote:
I've the impression that you didn't read my post, I might be wrong
though.
Do you read mine ?
Yes, but not the prev(prev(.)), sorry about that.
With that convention, you can use Markdown out of the box (on each
paragraph) as long as each list is on a single paragraph (which
sounds like a reasonable requirement to pose).
No: lots of description do not put list in a single paragraph. In
plain ASCII, it would be uggly to have a blank line before a list
introduced by a colon...
The fact it would be ugly is totally subjective. I personally prefer
to leave a empty line than not; FWIW Markdown has been designed on top
of (perceived) mail habits, and that's why the blank line is
there. But tastes are not to be discussed in a thread like this.
Still you do have a point in saying that lots of description do not
put list in a single paragraph. That was not my feeling, but it is
true, as you can verify roughly skimming through something like:
grep -B 1 '*' /var/lib/apt/lists/*_Packages | less
Looks like half lists are on a single paragraphs, half are not.
Note that the only pre-processor needed seems to be the one which
separate paragraphs using the single dot we already use.
No. Adding blank lines before lists is also required.
... so, agreed. The extra price to pay to use Markdown would be that
additional line insertion.
Cheers.
--
Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
z...@{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
signature.asc
Description: Digital signature
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Wed, Apr 22, 2009 at 07:34:45AM +0200, Andreas Tille wrote: Well, *if* something is *recommended* in the docs filing wishlist bugs against packages that ignore the recommendation are fine. Why else should we issue recommendations? For people writing new long descriptions, first off. That the review recommended to use a different itemize symbol than what seemed to be mostly silent consensus was problematic I think and I am glad that their recommendations have been adjusted. Also, I did not necessarily mean the Policy Manual when refererring to recommending above (once it gets accepted there, filing wishlist bugs looks sensible) but other possibly existing (or non-existing) style-guides, like the dev-ref etc. Michael -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Don Armstrong wrote:
There's no point to defining rules without a working implementation,
because we don't know what the rules should be.
So I tried to do an implementation for the tasks pages of Blends which
works for unordered lists as discussed here and I also made sure that
URLs will be handled by markdown correctly (just used
re.sub('*([fh]t?tp://[-./\w?=~;]+)*', '[\\1](\\1)', line)
for the input).
Once there is a
working implementation that works for a reasonable majority of the
descriptions, we can define rules based on the implementation, and
then file bugs against those few descriptions which are problematic
according to the rules.
This implementation shows that markdown needs at least one more
preprocessing step: Concerning the other reasons for verbatim
printing, which means if you are not in a list but there are more
than one space in the beginning of a line, replace the first space
by a tab or four spaces. This needs a leading empty line as well
as the lists as I found. If you are interested I have a Python
implementation of this which works (at least for the cases I
observed - see the links below). In case we might accept markdown
as a standard it might make sense to move this to python-apt or
something like this.
What you appear to be calling the next step (getting a working
implementation) is actually the first step from my perspective (and is
presumably shared by others.)
I perfectly respect your opinion even if I do not share it myself
but I hope we might meet in the middle of both ends.
On Tue, 21 Apr 2009, Holger Levsen wrote:
Perfect is the enemy of good.
... so I hope you like the stuff. ;-)
For comparison of the change you might like to compare two links
which show a working list and a working verbatim text one page:
http://debian-med.alioth.debian.org/tasks/bio#fastlink (old)
http://debian-med.debian.net/tasks/bio#fastlink (new)
Looking at these pages we might consider defining another preformating
rule to enable description lists - but I guess we might run another
bunch of circles if we continue on the road I started to go.
You might be interested in comparing Debian Edu
http://blends.alioth.debian.org/edu/tasks (old)
http://blends.debian.net/edu/tasks (new)
Nitpicking comment: Please note that I do NOT like the currently used
CSS style for the lists. The design was done by David Paleino for the
general page navigation (where it looks cute) but I would change it
definitely for the description layout. I delay this a bit until the
other parts of the code which are using the style are adapted first.
Kind regards
Andreas.
PS: Thanks to Raphael Hertzog python-markdown was installed on alioth
immediately after my request. I'd like to use this chance to say
thanks to those admins publicly.
--
http://fam-tille.de
--
To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Mon, Apr 20, 2009 at 11:24:42PM +0200, Andreas Tille wrote:
Here is the URL of the poll:
http://doodle.com/2bp8rrh3i35sr4s7
Heya, thanks for the poll.
Nevertheless, I think I got a bit lost in the discussion.
Following it, I had the impression that there was a quasi-agreement on
Markdown. Hence, I'm wondering what is the exact purpose of your
poll. With Markdown, you have alternative markers for denoting
bullet list (which is reasonable and consistent with what we do in
email), so what is the point of choosing one?
More generally (and given that even you are unsure about what you
didn't like of Markdown :-)), can you please you two explain why we
can't just say something like long descriptions are paragraph
separated by dots on single lines; each paragraph is formatted
according to markdown syntax.
Cheers.
--
Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
z...@{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
signature.asc
Description: Digital signature
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Stefano Zacchiroli wrote: Nevertheless, I think I got a bit lost in the discussion. Following it, I had the impression that there was a quasi-agreement on Markdown. Hence, I'm wondering what is the exact purpose of your poll. With Markdown, you have alternative markers for denoting bullet list (which is reasonable and consistent with what we do in email), so what is the point of choosing one? I think my whole point was just blured. I never wanted to change the format of long descriptions. I wanted to make it consistently parseable. I consider it a good idea to use a formating library and Manoj has mentioned that this is perfectly possible with the current format provided you are doing some preprocessing while it was shown as well that some consistent formatting has to be done to do this reliable (see the links I gave in the poll). More generally (and given that even you are unsure about what you didn't like of Markdown :-)), To say it explicitely: I like markdown and if this whole discussion might have no outcome for the descriptions at least I have decided to use it in my Blends tools. can you please you two explain why we can't just say something like long descriptions are paragraph separated by dots on single lines; each paragraph is formatted according to markdown syntax. I'm afraid that this leaves to much space for broken input as the airport-utils example in the end of [1] shows. Manoj tried to prove that markdown works perfectly - but it does not because the indentantion of the original input is just wrong. I want to fix THIS. Moreover I see no reason to bind anybody to a certain library like markdown. My experience has shown that people will insist on their very own way to do things. Do you think apt, aptitude, synaptic etc. developers would be happy if you start filing bug reports to make them use markdown? So my suggestion leaves perfectly space for using markdown as well as even raw text output - which would look also better with consistent formatting. Kind regards Andreas. [1] http://lists.debian.org/debian-devel/2009/04/msg00713.html -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Andreas Tille wrote: I'm afraid that this leaves to much space for broken input as the airport-utils example in the end of [1] shows. Manoj tried to prove that markdown works perfectly - but it does not because the indentantion of the original input is just wrong. I want to fix THIS. So long as we have an implementation which works for the vast majority of cases we can file bugs to make it work for the few cases where it doesn't. (Or the output can just be slightly broken in those cases; it's not like that's a huge problem.) Moreover I see no reason to bind anybody to a certain library like markdown. It's perfectly ok to punt the specification of the format to an external library, at least initially. If enough people don't want to use the markdown libraries, they'll either code up patches to policy to codify the equivalent of markdown formatting in policy or write equivalent code to markdown. It seems to me like the next step is to go ahead and make a few patches to packages.debian.org to change to a markdown (or equivalent) formatting of the long description with whatever pre-processing is necessary, see how well it works, submit a patch to policy to codify, and move on with filing bugs for those bits that don't work properly. Don Armstrong -- Sentenced to two years hard labor (for sodomy), Oscar Wilde stood handcuffed in driving rain waiting for transport to prison. If this is the way Queen Victoria treats her prisoners, he remarked, she doesn't deserve to have any. http://www.donarmstrong.com http://rzlab.ucr.edu -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
Don Armstrong wrote: On Tue, 21 Apr 2009, Andreas Tille wrote: Moreover I see no reason to bind anybody to a certain library like markdown. It's perfectly ok to punt the specification of the format to an external library, at least initially. If enough people don't want to use the markdown libraries, they'll either code up patches to policy to codify the equivalent of markdown formatting in policy or write equivalent code to markdown. As shown before in the other thread, markdown does not work with the current long description : it needs pre-processing to add some blank lines before each list. So, I see Andreas proposition has a way to formalize what we want to accept (that will allow most current long description to be good) in order to be able to send them with a preprocessor to tools such as markdown. It seems to me like the next step is to go ahead and make a few patches to packages.debian.org to change to a markdown (or equivalent) formatting of the long description with whatever pre-processing is necessary, see how well it works, submit a patch to policy to codify, and move on with filing bugs for those bits that don't work properly. No current tools¹ works with current long descriptions. If we add some preprocessor, I think we will hit the reason why, for example, markdown requires this additional blank line. This means that we will not support all what markdown support. It is not a problem but it means that markdown specifications can not be used as it. Regards, Vincent ¹: at least, I did not notice one in this discussion -- Vincent Danjean GPG key ID 0x9D025E87 vdanj...@debian.org GPG key fingerprint: FC95 08A6 854D DB48 4B9A 8A94 0BF7 7867 9D02 5E87 Unofficial pacakges: http://moais.imag.fr/membres/vincent.danjean/deb.html APT repo: deb http://perso.debian.org/~vdanjean/debian unstable main -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
ti, 2009-04-21 kello 10:37 +0200, Vincent Danjean kirjoitti: As shown before in the other thread, markdown does not work with the current long description : it needs pre-processing to add some blank lines before each list. That's true. Because the Packages and debian/control files are in pseudo-RFC822 format, it needs to escape the long description a bit. Otherwise an empty line between paragraphs in the description would separate records in the Packages file, for example. The two things that need to be done to un-escape are these: remove the leading single space, and remove lines consisting of a single period. This is really, really simple to do. After that is done, the long description can be fed to something that understands the markdown language. One such tool is the markdown command line tool or library, but anything that interprets markdown-the-language is fine. (This really, really shouldn't need all the discussion it's had already.) -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, Apr 21, 2009 at 10:37:00AM +0200, Vincent Danjean wrote:
As shown before in the other thread, markdown does not work with
the current long description : it needs pre-processing to add some
blank lines before each list.
I've the impression that you didn't read my post, I might be wrong
though. Anyhow, what I said there is that *each single paragraph* can
be considered Markdown (and not the whole long description), using
single-dot lines as paragraph separators. With that convention, you
can use Markdown out of the box (on each paragraph) as long as each
list is on a single paragraph (which sounds like a reasonable
requirement to pose).
Anticipating a potential objection: nested lists do work without
needing blank lines to separate nesting levels; I've just tried that
out.
If we add some preprocessor, I think we will hit the reason why, for
example, markdown requires this additional blank line. This means that
we will not support all what markdown support. It is not a problem but
it means that markdown specifications can not be used as it.
Note that the only pre-processor needed seems to be the one which
separate paragraphs using the single dot we already use. Such
pre-processor is most likely already implemented by all tools
processing long descriptions.
Cheers.
--
Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
z...@{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
signature.asc
Description: Digital signature
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
ti, 2009-04-21 kello 12:00 +0200, Andreas Tille kirjoitti: In principle this is fine as well. That's why my initial mail[1] said This suggestion is far from complete and should be enhanced. If there is a need to relax my strictly German habit to trimm everything very tidy - people should have told me so. Very well: your tendency towards strict consistency needs to be relaxed. :) Thus as far as I can see there is a rough consensus and the following should happen: * packages.debian.org needs to be modified to use markdown * GUI package managers need similar modification * other places that format long descriptions need similar changes * once at least packages.d.o works, someone needs to write a Policy change (5.6.13 needs to refer to markdown). * once the Policy has been changed, bugs for the handful of packages that are problematic need to be filed, perhaps with patches Anything else? -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Andreas Tille wrote: On Tue, 21 Apr 2009, Don Armstrong wrote: So long as we have an implementation which works for the vast majority of cases we can file bugs to make it work for the few cases where it doesn't. (Or the output can just be slightly broken in those cases; it's not like that's a huge problem.) IMHO this whole discussion is the problem. I just wanted to define rules to enable us filing bugs. There's no point to defining rules without a working implementation, because we don't know what the rules should be. Once there is a working implementation that works for a reasonable majority of the descriptions, we can define rules based on the implementation, and then file bugs against those few descriptions which are problematic according to the rules. The discussion just runs circles about the next step before doing the first. What you appear to be calling the next step (getting a working implementation) is actually the first step from my perspective (and is presumably shared by others.) Don Armstrong -- A one-question geek test. If you get the joke, you're a geek: Seen on a California license plate on a VW Beetle: 'FEATURE'... -- Joshua D. Wachs - Natural Intelligence, Inc. http://www.donarmstrong.com http://rzlab.ucr.edu -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Don Armstrong wrote: There's no point to defining rules without a working implementation, because we don't know what the rules should be. Once there is a working implementation that works for a reasonable majority of the descriptions, we can define rules based on the implementation, and then file bugs against those few descriptions which are problematic according to the rules. Hmm, considering the discussion which went quite badly you probably have a point. But how would you implement lintian checks for works with markdown. You have less chances to verify whether the result is really what the author intended to express. I probably will calm down a bit in this issue and will think about it. You certainly have a point that the motivation to implement my suggestion is void as long as there is no need. I started from the other end: There is no point in implementing better markup for the Blends pages if I know from the beginning that I will end up with broken pages for an undetermined time. Kind regards Andreas. -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Don Armstrong wrote: So long as we have an implementation which works for the vast majority of cases we can file bugs to make it work for the few cases where it doesn't. (Or the output can just be slightly broken in those cases; it's not like that's a huge problem.) IMHO this whole discussion is the problem. I just wanted to define rules to enable us filing bugs. The discussion just runs circles about the next step before doing the first. Kind regards Andreas. -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Lars Wirzenius wrote: Properly here should mean anything that the markdown language says is OK. The markdown language is remarkably relaxed about indentation. It can handle it fine if one list is indented by two space, and other by three. There seems to be no need for Debian to impose stricter definitions. Or am I misunderstanding what you are saying, Andreas? No. l...@dorfl$ cat foo.mdwn This is a normal paragraph. * this is top level item * this is second level item * this is another second level item * this is again a top level item This is another paragraph. * this is top level item * this is second level item * this is another second level item * this is again a top level item l...@dorfl$ markdown foo.mdwn pThis is a normal paragraph./p ul lithis is top level item ul lithis is second level item/li lithis is another second level item/li /ul/li lithis is again a top level item/li /ul pThis is another paragraph./p ul lithis is top level item ul lithis is second level item/li lithis is another second level item/li /ul/li lithis is again a top level item/li /ul l...@dorfl$ In principle this is fine as well. That's why my initial mail[1] said This suggestion is far from complete and should be enhanced. If there is a need to relax my strictly German habit to trimm everything very tidy - people should have told me so. But the discussion drifted away very much. I'm a fan of stricter rules feel free to relax this. Finally I want something which *works*. Thanks for helping out to explain my point Andreas. [1] http://lists.debian.org/debian-devel/2009/03/msg01165.html -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, Apr 21, 2009 at 01:08:24PM +0300, Lars Wirzenius wrote:
Very well: your tendency towards strict consistency needs to be
relaxed. :)
Thus as far as I can see there is a rough consensus and the following
should happen:
That's my reading as well. (Adding back -policy to the recipient list,
to check whether they agree with this interpretation or not.)
* packages.debian.org needs to be modified to use markdown
* GUI package managers need similar modification
* other places that format long descriptions need similar changes
* once at least packages.d.o works, someone needs to write a Policy
change (5.6.13 needs to refer to markdown).
* once the Policy has been changed, bugs for the handful of packages
that are problematic need to be filed, perhaps with patches
Anything else?
Well, yes, a big thanks to Andreas for digging into this discussion
:-) *If* we manage to have consensus on this, it will be mostly due
to him insisting on this topic!
Cheers.
--
Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
z...@{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
signature.asc
Description: Digital signature
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
ti, 2009-04-21 kello 11:27 +0200, Andreas Tille kirjoitti: On Tue, 21 Apr 2009, Stefano Zacchiroli wrote: Anticipating a potential objection: nested lists do work without needing blank lines to separate nesting levels; I've just tried that out. ... provided that lists are formated properly in the first place (keyword: broken spacings). That's why I would like to give advises for the spacing directly. Properly here should mean anything that the markdown language says is OK. The markdown language is remarkably relaxed about indentation. It can handle it fine if one list is indented by two space, and other by three. There seems to be no need for Debian to impose stricter definitions. Or am I misunderstanding what you are saying, Andreas? l...@dorfl$ cat foo.mdwn This is a normal paragraph. * this is top level item * this is second level item * this is another second level item * this is again a top level item This is another paragraph. * this is top level item * this is second level item * this is another second level item * this is again a top level item l...@dorfl$ markdown foo.mdwn pThis is a normal paragraph./p ul lithis is top level item ul lithis is second level item/li lithis is another second level item/li /ul/li lithis is again a top level item/li /ul pThis is another paragraph./p ul lithis is top level item ul lithis is second level item/li lithis is another second level item/li /ul/li lithis is again a top level item/li /ul l...@dorfl$ -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Stefano Zacchiroli wrote: Anticipating a potential objection: nested lists do work without needing blank lines to separate nesting levels; I've just tried that out. ... provided that lists are formated properly in the first place (keyword: broken spacings). That's why I would like to give advises for the spacing directly. Kind regards Andreas. -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
Hi, On Dienstag, 21. April 2009, Andreas Tille wrote: There is no point in implementing better markup for the Blends pages if I know from the beginning that I will end up with broken pages for an undetermined time. Perfect is the enemy of good. regards, Holger signature.asc Description: This is a digitally signed message part.
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
Stefano Zacchiroli wrote: On Tue, Apr 21, 2009 at 10:37:00AM +0200, Vincent Danjean wrote: As shown before in the other thread, markdown does not work with the current long description : it needs pre-processing to add some blank lines before each list. I've the impression that you didn't read my post, I might be wrong though. Do you read mine ? Anyhow, what I said there is that *each single paragraph* can be considered Markdown (and not the whole long description), using single-dot lines as paragraph separators. This part is so easy that I did not even talk about it in my mail (I talked about it in my previous mail when I showed with an example that Markdown need more preprocessing that this one) With that convention, you can use Markdown out of the box (on each paragraph) as long as each list is on a single paragraph (which sounds like a reasonable requirement to pose). No: lots of description do not put list in a single paragraph. In plain ASCII, it would be uggly to have a blank line before a list introduced by a colon... So, you need to know where to add blank lines in long description before sending them to Markdown. Note that the only pre-processor needed seems to be the one which separate paragraphs using the single dot we already use. No. Adding blank lines before lists is also required. Regards, Vincent -- Vincent Danjean GPG key ID 0x9D025E87 vdanj...@debian.org GPG key fingerprint: FC95 08A6 854D DB48 4B9A 8A94 0BF7 7867 9D02 5E87 Unofficial pacakges: http://moais.imag.fr/membres/vincent.danjean/deb.html APT repo: deb http://perso.debian.org/~vdanjean/debian unstable main -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, Apr 21, 2009 at 12:36:14PM +0300, Lars Wirzenius wrote: ti, 2009-04-21 kello 11:27 +0200, Andreas Tille kirjoitti: On Tue, 21 Apr 2009, Stefano Zacchiroli wrote: Anticipating a potential objection: nested lists do work without needing blank lines to separate nesting levels; I've just tried that out. ... provided that lists are formated properly in the first place (keyword: broken spacings). That's why I would like to give advises for the spacing directly. Properly here should mean anything that the markdown language says is OK. The markdown language is remarkably relaxed about indentation. It can handle it fine if one list is indented by two space, and other by three. There seems to be no need for Debian to impose stricter definitions. I for one like visual consistency even when reading package descriptions via apt-cache etc. So having at least a uniform indentation level (and, if possibly, a uniform itemize symbol, but this seems to be heavily opposed against) *as a recommended* way of writing long descriptions would be desirable. I don't think it warrants filing bugs, though. cheers, Michael -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
On Tue, 21 Apr 2009, Michael Banck wrote: I for one like visual consistency even when reading package descriptions via apt-cache etc. It must be a boring German habit - I always felt this way myself. I started some action when I noticed that my feeling turned out to have technical advantages in the task I wanted to tackle. So having at least a uniform indentation level (and, if possibly, a uniform itemize symbol, but this seems to be heavily opposed against) *as a recommended* way of writing long descriptions would be desirable. I don't think it warrants filing bugs, though. Well, *if* something is *recommended* in the docs filing wishlist bugs against packages that ignore the recommendation are fine. Why else should we issue recommendations? Kind regards Andreas. -- http://fam-tille.de -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)
Hi,
as promissed in the overlongish thread [1] I would like to
sort out the details how we should enhance the consistency and
parseability of our long descriptions in a poll. I agree that
it is not a good idea to solve technical issues in a poll.
But this is not about a technical issue. There is a fact that
we need a defined structure (technical issue 1) to be able
to parse the long descriptions (whatever library or self invented
code will be used - technical issue 2). But the details how
the structure should look like is more or less an aesthetical
question (because several tools print the long descriptions
in verbose mode) and so the question is about this aesthetics.
If you want to discuss the technical issues please read all mails
of the thread and continue discussing this (preferably with a
new subject).
Here is the URL of the poll:
http://doodle.com/2bp8rrh3i35sr4s7
Kind regards
Andreas.
On Thu, 16 Apr 2009, Andreas Tille wrote:
If you make a suggestion please answer the following question:
A. Does the suggestion enable parsing logical structures like
two level itemize lists?
(This is what I want to approach and what is IMHO needed)
B. Does the suggestion enable keeping the majority of description
untouched and enables keeping the currently existing tools?
(This is important to gain any acceptance)
If one of the question above is answered with no please mention
whether you are volunteering to do the work which is needed to
port the existing stuff to match your suggestion.
Currently I would feed the poll with 4 suggestions:
0. Keep anything as unstructured as it is.
Answer to A: no
Answer to B: yes
1. Use '*' for first order item lists, '-' for second order
item lists and use ' ' (exactly two spaces) before the
'*' and '' (exactly four spaces) before the '-'. After
'*' and '-' exactly one space should be used and continued
lines should start in the same column as the text starts
above.
Answer to A: yes
Answer to B: yes
2. Use '*' for first order item lists, '-' for second order
item lists. Spacing does not matter as long as continued
lines will start in the same column as the text above.
Answer to A: yes
Answer to B: yes
3. Use any character of ('*', '-', '+') to start a list and
mark the level of the list by strictly following spacing
rules and use ' ' (exactly two spaces) before the selected
character for starting first order list and '' (exactly
four spaces) before the character for starting second order
list. After the marker symbold exactly one space should be
used and continued lines should start in the same column as
the text starts above.
Answer to A: yes
Answer to B: yes
If you want to make further suggestions just append this list.
I'll start a doodle poll next Monday. Depending from the outcome
of this poll I will submit a patch for 6.2. Best practices for
debian/control.
[1] http://lists.debian.org/debian-devel/2009/03/msg01165.html
--
http://fam-tille.de
--
To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
