Re: Consistent formating long descriptions as input data

[Manoj Srivastava]

On Mon, Apr 20 2009, Andreas Tille wrote:

> 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
>

Frankly, a poll about micromanaging marks for each level of
 unordered list does seem to be technical. It is also an implementation
 detail, and invents our own convention, and options 1 & 2 would cause
 many more packages to be changed than would just adopting markdown or
 ReST. The fact that we need more packages changed for options 1 & 2
 makes them technically inferior.

Is there anyone other than yourself who is actually unhappy
 about markdown/ReST?

And should we have similar silly polls (which I have no
 intention of promoting by voting in them) for emhpasis? for specifying
 bold/italic text? For ordered lists? for a myriad of other useful
 markup already familiar to people who know markdown and ReST?

Also, given that there are more output formats than html
 available for markdown/ReST is another plus point; we might want other
 output formats for Descriptions than plain ol' html.

manoj
-- 
Once the erosion of power begins, it has a momentum all its own.
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
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

[Andreas Tille]

On Mon, 20 Apr 2009, Manoj Srivastava wrote:


   Frankly, a poll about micromanaging marks for each level of
unordered list does seem to be technical. It is also an implementation
detail, and invents our own convention,


I disagree.


and options 1 & 2 would cause
many more packages to be changed than would just adopting markdown or
ReST.


Please specify what you mean by "adopting markdown or ReST" more
precisely.


The fact that we need more packages changed for options 1 & 2
makes them technically inferior.


Best practices do not imply a *need* to change anything.


   Is there anyone other than yourself who is actually unhappy
about markdown/ReST?


Please remind me at which point I was unhappy about markdown/ReST.
I do not really remember that I was.  I just try to enable better
input for any postprocessing.


   And should we have similar silly polls (which I have no
intention of promoting by voting in them) for emhpasis? for specifying
bold/italic text? For ordered lists? for a myriad of other useful
markup already familiar to people who know markdown and ReST?


Manoj, please do not give me the feeling that my English is that bad
that I was unable to explain my point in my last mail[1].  If you would
confirm that you missunderstand me intentionally I would gain back
a small amount of trust in my English teacher.


   Also, given that there are more output formats than html
available for markdown/ReST is another plus point; we might want other
output formats for Descriptions than plain ol' html.


Hmmm, this paragraph confuses me even more.  Going back, reading my
mails again, wondering why I spend so much time in explaining, ...

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

[Charles Plessy]

Le Mon, Apr 20, 2009 at 05:55:20PM -0500, Manoj Srivastava a écrit :
> 
> Is there anyone other than yourself who is actually unhappy
>  about markdown/ReST?

Hi all, hi Andreas,

In the end, I do not think that it is a good idea to do typesetting in long
descriptions. In the packages I maintain, I will remove itemized and ordered
lists if there are. This will solve Andreases problem. In none of the packages
I maintain I have found any need for italics, bold, understrike or other
sophisticated typographical features.

URLs could be an exception, but the only user request I had about this was for
having them in the “External Resources:” section of the packages.debian.org
page.

I do not oppose the use of any markup, but given that nobody is stepping up for
doing some real work apart from Andreas, I suggest that we settle on a simple
recommendation about bullet lists to be put in the Developers Reference.

If we do not agree, we can alternatively go the wishlist patch way: Andreas is
working on a website to present the packages that are installed in Debian Pure
Blends. When we notice that a package description of package we recommend is
difficult to format nicely, we can send a whishlist patch to the BTS. We will
then see if these patches are welcome, and maybe will start a trend. For the
moment, I have the feeling that we are fighting resistance from developpers
whose packages are not an issue for us anyway.

Have a nice day,

-- 
Charles Plessy
Debian Med packaging team,
http://www.debian.org/devel/debian-med
Tsurumi, Kanagawa, Japan


-- 
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

[Ben Finney]

Charles Plessy  writes:

> In the end, I do not think that it is a good idea to do typesetting in
> long descriptions. In the packages I maintain, I will remove itemized
> and ordered lists if there are. This will solve Andreases problem.

What will you replace them with? They are a natural convention even in
plain ASCII text.

-- 
 \   “The man who is denied the opportunity of taking decisions of |
  `\  importance begins to regard as important the decisions he is |
_o__)allowed to take.” —C. Northcote Parkinson |
Ben Finney


-- 
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

[Ben Finney]

Stefano Zacchiroli  writes:

> On Tue, Apr 21, 2009 at 11:36:31PM +0200, Vincent Danjean wrote:
> > 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.

FWIW, the use of reST as a format specification would require the same:
a blank line to precede a list.

-- 
 \“What if the Hokey Pokey IS what it's all about?” —anonymous |
  `\   |
_o__)  |
Ben Finney


pgp923uZwEgYU.pgp
Description: PGP signature

Re: Consistent formating long descriptions as input data

[Manoj Srivastava]

On Wed, Apr 22 2009, Stefano Zacchiroli wrote:

> On Tue, Apr 21, 2009 at 11:36:31PM +0200, Vincent Danjean wrote:

>> 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.

And this is like 6 lines of Pseudo code, and less in compact
 languages like Perl. A fairly trivial exercise in basic CS logic.

manoj
-- 
A violent man will die a violent death. Lao Tsu
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
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

[Manoj Srivastava]

On Tue, Apr 21 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.  The discussion just runs circles
> about the next step before doing the first.

If by rules you mean policy (which seems likely, since your goal
 was to enable us to file bugs), that is not how policy works. Policy
 wants a finished design, which means a tested design, and that means
 youneed to know how to implement things before it becomes policy. And
 policy is all about not having to file too many bugs in the first
 place, so trying to get something going to enable us to file bugs first
 is just plain … wrong headed. Even wishlist bugs, in advance of a
 working design, are a bad idea -- since the implementation might cause
 the draft design to be modified.

manoj
-- 
Education is what survives when what has been learnt has been
forgotten. B.F. Skinner
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


--
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

[Andreas Tille]

On Wed, 22 Apr 2009, Manoj Srivastava wrote:


   And this is like 6 lines of Pseudo code, and less in compact
languages like Perl. A fairly trivial exercise in basic CS logic.


Please do not insist on the number of lines.  I mentioned in my
mail [1] that you need a bit more.  I did not said that it is not
trivial.  But I'm lacking some motivation if I need to *help*
markdown so far that I have to detect all the clues in a
preprocessor myself.

Kind regards

Andreas.

[1] http://lists.debian.org/debian-devel/2009/04/msg00815.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

[Stefano Zacchiroli]

On Wed, Apr 22, 2009 at 10:22:15AM -0500, Manoj Srivastava wrote:
> On Wed, Apr 22 2009, Stefano Zacchiroli wrote:
> > On Tue, Apr 21, 2009 at 11:36:31PM +0200, Vincent Danjean wrote:
> >> 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.
> And this is like 6 lines of Pseudo code, and less in compact
>  languages like Perl. A fairly trivial exercise in basic CS logic.

Did I say anywhere that it was difficult or not worth doing? I was
just pointing out a fact, which was clarified in the discussion.

FWIW, I consider it totally worth to gain the benefit of having some
expressive, yet readable, language such as Markdown.

Considering all this thread, can you please summarize the point of
view of policy maintainers on the issue? (which is why I added back
the -policy Cc: in the first place)

TIA,
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

[Manoj Srivastava]

On Thu, Apr 23 2009, Stefano Zacchiroli wrote:


> Considering all this thread, can you please summarize the point of
> view of policy maintainers on the issue? (which is why I added back
> the -policy Cc: in the first place)

While I can't speak for the policy team (I have not been
 re-delegated yet), I suspect the answer might be to get a working
 implementation out in the wild (it does not have to be packages.d.o or
 anything official -- even a standalone software that takes the output
 from grep-dctrl or parses a Packages file will suffice). This will
 allow us to see what changes to policy might be needed, if any, for
 package descriptions.

Once we ahve a working implementation, and a clear idea of what
 might need to be changed in package descriptions (for example, we
 already know that packages using 'o' as a bullet in unordered lists
 will have to be changed to use one of +.-. or *), we can scan the
 package descriptions to see how many packages would be affected, and
 then decide how to introduce that language into policy (more package
 affected, the more the need for a transition plan)

I do not see any reason this proposal should not become policy,
 eventually, since this deals with the core charter of the technical
 policy: standards that packages need to follow to allow for better
 integration. 

manoj
-- 
Diplomacy is the art of letting the other party have things your
way. Daniele Vare
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
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

[Andreas Tille]

On Thu, 23 Apr 2009, Manoj Srivastava wrote:


   While I can't speak for the policy team (I have not been
re-delegated yet), I suspect the answer might be to get a working
implementation out in the wild (it does not have to be packages.d.o or
anything official -- even a standalone software that takes the output
from grep-dctrl or parses a Packages file will suffice). This will
allow us to see what changes to policy might be needed, if any, for
package descriptions.


Would you consider the tasks pages I announced yesterday [1] as such
an implementation.  I continued to work a bit on this and have two
additions to the preprocessor:

   1. The inlist flag has to be unset not only if a line starts
  in the second column again but also if there is an empty line.
   2. You need to escape '#' signs if they appear as first
  character.

See the implementation at the end of this mail.


   Once we ahve a working implementation, and a clear idea of what
might need to be changed in package descriptions (for example, we
already know that packages using 'o' as a bullet in unordered lists
will have to be changed to use one of +.-. or *), we can scan the
package descriptions to see how many packages would be affected, and
then decide how to introduce that language into policy (more package
affected, the more the need for a transition plan)


I tried to detect some examples which need some changes.  You might
like to have a look at my "Debugging Blend":

   http://blends.debian.net/debug/tasks

Some issues are mentioned there - I intend to add some better
documentation if needed but some issues become clear.


   I do not see any reason this proposal should not become policy,
eventually, since this deals with the core charter of the technical
policy: standards that packages need to follow to allow for better
integration.


After dealing with the issue I would do the following resume:

  1. The preprocessing you have to do for markdown is basically
 the same I did for turning description text into html
 programmatically myself.  There is no real benefit if your
 main target is only HTML - however, other output formats
 might benefit from using the preprocessing + markup step.
  2. Markdown is probably better in detecting second level lists
 thank I would have done it programmatically - so here is
 a benefit.  On the other hand there are some strange false
 positives for second level lists.
  3. If we really are doing preprocessing it would be cheap to
 use 's/\so\s/ * /' and even this marker might be detected
 as list marker.  This would be perfectly in contrast to my
 initial suggestion - but consequent if you prefer
 preprocessing anyway.  BTW, I even detected non-ASCII
 bullets in the burn package and because it is QA maintained
 anyway I took the chance to change this while fixing bug
 #517793.  I think we should catch things like this quite
 quickly because even apt-cache show failed to disply
 the description of burn correctly and so I've though
 fixing the problem myself instead of adding another bug
 to a QA maintained package seems reasonable.
  4. I expect more not yet detected needs for preprocessing.
  5. I expect the lintian checks for the markdown format rather
 complicated because there is a lot more freedom in the
 format (which might be an advantage for the editors) and
 some valid markdown input might be successfully rendered
 but into something which conflicts the intention of the
 author.  Compared to my suggestion of formating the
 long descriptions according to stricter rules this adds
 another level of complecity while the lintien checks
 which would be needed for my suggestions would have been
 really cheap.  I'd consider this as a disadvantage.

I might note that I'm not happy that in the case of pure and
simple ASCII output of long descriptions as it is done by current
tools more or less we will have a rendering which does not fit my
taste at all - but I accept that I probably belong to a minority
and if markdown is widely accepted it leads to my initial goal
(tasks pages) as well.

Kind regards

   Andreas.

[1] http://lists.debian.org/debian-devel/2009/04/msg00815.html

Python implementation:

detect_list_start_re = re.compile("^\s+[-*+]\s+")
detect_code_start_re = re.compile("^\s")
detect_code_end_re   = re.compile("^[^\s]")
detect_url_re= re.compile("[fh]t?tp://")

def PrepareMarkdownInput(lines):
ret= ''
inlist = 0
incode = 0
for line in lines:
# strip leading space from description as well as useless trailing
line = re.sub('^ ', '', line.rstrip())
# a '^\.$' marks in descriptions a new paragraph, markdown uses an 
empty line here
line = re.sub('^\.$', '', line)

if detect_code_start_re.search(line):
if incode == 0: # If a list or verbatim mode starts MarkDown needs 
an empty line

Re: Consistent formating long descriptions as input data

[Manoj Srivastava]

On Thu, Apr 23 2009, Andreas Tille wrote:

> On Thu, 23 Apr 2009, Manoj Srivastava wrote:
>
>>While I can't speak for the policy team (I have not been
>> re-delegated yet), I suspect the answer might be to get a working
>> implementation out in the wild (it does not have to be packages.d.o or
>> anything official -- even a standalone software that takes the output
>> from grep-dctrl or parses a Packages file will suffice). This will
>> allow us to see what changes to policy might be needed, if any, for
>> package descriptions.
>
> Would you consider the tasks pages I announced yesterday [1] as such
> an implementation.

Sure. It would be great to have another implementation, perhaps
 one that people can play with (something that, for example, one can
 pipe the output of a grep-dctrl command to, and get an html snippet
 from (hey, that can then be packaged as an ikiwiki plugin).

But the task pages should count as an implementation.
>
> I tried to detect some examples which need some changes.  You might
> like to have a look at my "Debugging Blend":
>
>http://blends.debian.net/debug/tasks
>
> Some issues are mentioned there - I intend to add some better
> documentation if needed but some issues become clear.

Thanks. Once you are through, perhaps some  directives for long
 description policy can be derived from that.

>   1. The preprocessing you have to do for markdown is basically
>  the same I did for turning description text into html
>  programmatically myself.  There is no real benefit if your
>  main target is only HTML - however, other output formats
>  might benefit from using the preprocessing + markup step.

>   2. Markdown is probably better in detecting second level lists
>  thank I would have done it programmatically - so here is
>  a benefit.  On the other hand there are some strange false
>  positives for second level lists.

These should be something we can look at to provide a policy
 recommendation so these false positives can be reduced. 

>   3. If we really are doing preprocessing it would be cheap to
>  use 's/\so\s/ * /' and even this marker might be detected
>  as list marker.  This would be perfectly in contrast to my
>  initial suggestion - but consequent if you prefer
>  preprocessing anyway.  BTW, I even detected non-ASCII
>  bullets in the burn package and because it is QA maintained
>  anyway I took the chance to change this while fixing bug
>  #517793.  I think we should catch things like this quite
>  quickly because even apt-cache show failed to disply
>  the description of burn correctly and so I've though
>  fixing the problem myself instead of adding another bug
>  to a QA maintained package seems reasonable.

I like the idea of  's/^(\s*)o\s+/$1* /' (to preserve the leading
 indentation, in case this was a second level item) as a preprocessing
 step in the interim, in the long term this usage should go down as
 policy starts to deprecate it.

>   4. I expect more not yet detected needs for preprocessing.

Thanks for working on this.

>   5. I expect the lintian checks for the markdown format rather
>  complicated because there is a lot more freedom in the
>  format (which might be an advantage for the editors) and
>  some valid markdown input might be successfully rendered
>  but into something which conflicts the intention of the
>  author.  Compared to my suggestion of formating the
>  long descriptions according to stricter rules this adds
>  another level of complecity while the lintien checks
>  which would be needed for my suggestions would have been
>  really cheap.  I'd consider this as a disadvantage.


> I might note that I'm not happy that in the case of pure and
> simple ASCII output of long descriptions as it is done by current
> tools more or less we will have a rendering which does not fit my
> taste at all - but I accept that I probably belong to a minority
> and if markdown is widely accepted it leads to my initial goal
> (tasks pages) as well.

manoj
-- 
Hartley's First Law: You can lead a horse to water, but if you can get
him to float on his back, you've got something.
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
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

[Andreas Tille]

On Thu, 23 Apr 2009, Manoj Srivastava wrote:


   Sure. It would be great to have another implementation, perhaps
one that people can play with (something that, for example, one can
pipe the output of a grep-dctrl command to, and get an html snippet
from (hey, that can then be packaged as an ikiwiki plugin).


As I said inclusion of the preprocessing code into python-apt or
any other reasonable place where you could turn it into a general
tool makes perfectly sense.  IMHO it makes sense if I continue with
the tests for a while and than offer it for adoption.


   But the task pages should count as an implementation.


I tried to detect some examples which need some changes.  You might
like to have a look at my "Debugging Blend":

   http://blends.debian.net/debug/tasks

Some issues are mentioned there - I intend to add some better
documentation if needed but some issues become clear.


   Thanks. Once you are through, perhaps some  directives for long
description policy can be derived from that.


Yesterday I had the idea to add a "Remarks of Blends-team" feature
which I will "missuse" to add a verbose output of `apt-cache show`
to the packages in question on the page above.  This should enable
an easy way to see the problems quickly.  I'll announce here once
it is finished.


  2. Markdown is probably better in detecting second level lists
 thank I would have done it programmatically - so here is
 a benefit.  On the other hand there are some strange false
 positives for second level lists.


   These should be something we can look at to provide a policy
recommendation so these false positives can be reduced.


Yes, that's the idea.  On the other hand looking at some examples
I have the feeling that sometime markup has a strange way to handle
some lists.  I'll come up with examples once I implemented the
"Remarks feature" so you can easily see what I mean.


   I like the idea of  's/^(\s*)o\s+/$1* /' (to preserve the leading
indentation, in case this was a second level item) as a preprocessing
step in the interim, in the long term this usage should go down as
policy starts to deprecate it.


OK.


  4. I expect more not yet detected needs for preprocessing.


   Thanks for working on this.


Sure.  I startet this thread not just for the sake of havin fun in a
discussion. ;-)

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

[Daniel Burrows]

On Fri, Apr 24, 2009 at 08:37:22AM +0200, Andreas Tille  was 
heard to say:
>>>   2. Markdown is probably better in detecting second level lists
>>>  thank I would have done it programmatically - so here is
>>>  a benefit.  On the other hand there are some strange false
>>>  positives for second level lists.
>>
>>These should be something we can look at to provide a policy
>> recommendation so these false positives can be reduced.
>
> Yes, that's the idea.  On the other hand looking at some examples
> I have the feeling that sometime markup has a strange way to handle
> some lists.  I'll come up with examples once I implemented the
> "Remarks feature" so you can easily see what I mean.

  One example is the patch I just committed to the online aptitude
release notes to fix a weird Markup problem.  I've attached it for
illustration.  The solution ended up being to indent every paragraph of
a bullet beyond the first one by an extra space.  If you don't do this,
Markdown becomes extremely confused about the status of sub-lists: it
sometimes tries to break out of the top-level list and display them as
new lists, sometimes it makes the second sub-item (but no other
sub-items) a child of the first sub-item, etc.

  I would prefer Restructured Text, for the simple reason that it has an
actual specification with a fairly complete description of its syntax
and semantics.  In constrast, I've never been able to find any useful
documentation of Markdown beyond "what /usr/bin/markdown does".  Having
a decent spec makes it a lot easier to implement alternate parsers or to
understand why the canonical parser is doing an unexpected thing with
your input.

  Compare, for instance:

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
http://daringfireball.net/projects/markdown/syntax

  One manifestation of this: I can't tell you if the behavior I
described regarding nested lists matches the Markdown documentation or
not, because the Markdown syntax documentation doesn't even mention
nested lists, let alone define how exactly they should be written in a
Markdown document.  I guess maybe you could say they're undefined and
the processor will do whatever it does? :-/  In the RST spec this is
described in the section labeled "Indentation".

  Daniel
commit 95e90bf80d8313aa21e1731f2687e3f4c0c853dd
Author: Daniel Burrows 
Date:   Sat Apr 25 10:40:39 2009 -0700

Fix the formatting of the show-summary information.

diff --git a/wiki/projects/aptitude/news/aptitude-0.5.2-release-notes.mdwn b/wiki/projects/aptitude/news/aptitude-0.5.2-release-notes.mdwn
index d29e3e7..e4d9abb 100644
--- a/wiki/projects/aptitude/news/aptitude-0.5.2-release-notes.mdwn
+++ b/wiki/projects/aptitude/news/aptitude-0.5.2-release-notes.mdwn
@@ -66,54 +66,47 @@ also includes major changes to the dependency solver.
 	  [[!img aptitude-0.5.2-fix-upgrade-manually.png size="400x400"]]
 
   + **\[cmdline]** Added a new command-line option,
-  `--show-summary`, to the `why`
-  command-line action.  This option causes aptitude to
-  show a brief list of the first package in each
-  dependency chain that would have been displayed.
-  Dependency chains that contain Suggests are not
-  displayed, so combining this option with `-v` will cause
-  aptitude to display all the packages that require the
-  target.
-
-	  Documentation for this feature is currently missing.
-	  The `--show-summary` option accepts an optional argument
-	  giving the summary mode:
-
-	  - `no-summary`: don't show a summary.
-
-	  - `last-package`: only show the last package in each
-	chain; that is, either the manually installed package
-	that requires the target package, or the package you
-	selected from the command-line.  This is the default
-	if `--show-summary` is used with no argument.  In
-	future releases of aptitude this will be
-	`first-package`, since that name makes a lot more
-	sense.
-
-  - `last-package-and-type`: display the last package in
-each chain, along with an indication of the strength
-of the chain.
-
-	  - `all-packages`: briefly display each chain of packages
-	in its entirety.
-
- 	  - `all-packages-with-dep-versions`: briefly display each
- 		chain of packages in its entirety, along with the
- 		version constraint, if any, of each dependency.
-
- The configuration option
- `Aptitude::CmdLine::Why-Display-Mode` can be set to any
- value that `--show-summary` accepts; if `--show-summary`
- is present on the command-line, it overrides this option.
- In future releases of aptitude, the configuration option
- will be `Aptitude::CmdLine::Show-Summary`.
-
- As you can see from the following screen-shot, this
- op

Re: Consistent formating long descriptions as input data

[Andreas Tille]

On Sat, 25 Apr 2009, Daniel Burrows wrote:


 I would prefer Restructured Text, for the simple reason that it has an
actual specification with a fairly complete description of its syntax
and semantics.


I do not have practical experience with both and so I do not have
any preference.  The only thing I'f fear is that we might loose track
in finally solving the problem in discussing which library to use.
So do you think I should try to switch from markdown to reST in the
debug output project?

For those who are interested: At

  http://blends.debian.net/debug/tasks/

I added remarks to those description which really beed a remark.

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

[Ben Finney]

Daniel Burrows  writes:

>   I would prefer Restructured Text, for the simple reason that it has an
> actual specification with a fairly complete description of its syntax
> and semantics.  In constrast, I've never been able to find any useful
> documentation of Markdown beyond "what /usr/bin/markdown does".  Having
> a decent spec makes it a lot easier to implement alternate parsers or to
> understand why the canonical parser is doing an unexpected thing with
> your input.

+1

-- 
 \  “I am too firm in my consciousness of the marvelous to be ever |
  `\   fascinated by the mere supernatural …” —Joseph Conrad, _The |
_o__) Shadow-Line_ |
Ben Finney


-- 
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

[Stefano Zacchiroli]

[ resent ]

On Thu, Apr 23, 2009 at 08:06:28PM -0500, Manoj Srivastava wrote:
> >> I suspect the answer might be to get a working implementation out
> >> in the wild (it does not have to be packages.d.o or anything
> >> official -- even a standalone software that takes the output from
> >> grep-dctrl or parses a Packages file will suffice)
> > Would you consider the tasks pages I announced yesterday [1] as
> > such an implementation.
> Sure. It would be great to have another implementation, perhaps
>  one that people can play with (something that, for example, one can
>  pipe the output of a grep-dctrl command to, and get an html snippet
>  from (hey, that can then be packaged as an ikiwiki plugin).

Please find one attached as the script "render-dctrl". Sample usage:

  grep-available -s Package,Depends,Description ocaml | render-dctrl > 
packages.html

Sample "packages.html" (obtained with the command above) is available
at [1]. To run it you will need python-debian and python-markdown. The
script will be shipped as an example of python-debian starting from
the next release [2].

I've on purpose not looked at Andreas implementation, in order to see
if we have mutually thought at different issues. That also means that
it can be utterly buggy, you have been warned :-)

Already in the attached sample output you can find what I believe will
be the most problematic issue to deal with (see the
libocamlbricks-ocaml-dev package). Namely: not-indented multi-line
list items which are not surrounded by blank lines. Arguably though, a
long description using a list as in the libocamlbricks-ocaml-dev
package is already "horrible" per se, and deserves to be fixed no
matter what. The interesting snippet is as follows:

> Library OCaml which provide a set of needed and useful macros for developing.
> Modules and functionality are the follows :
> .
>  - Configuration_files: Allow to get information from configuration files
>  - Environments: Environments are useful for maintaining the state, intendend
> as a set of bindings, of a user interaction with a GUI
>  - FilenameExtra: Additional features for the standard module Filename

Cheers.

[1] http://upsilon.cc/~zack/stuff/packages.html
[2] 
http://git.debian.org/?p=pkg-python-debian/python-debian.git;a=commit;h=b90ffafd6a1806ab7e3e7620d1675a53ae38e66e

PS mail like this one of mine should be better stored in the log of a
   bug report against the policy, to keep track of the
   status.
   Andreas: do we have one already? If not, can you please
   submit it with references to the thread? ... or else shout and
   I'll do that.

-- 
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
#!/usr/bin/python

# render-dctrl
# Copyright (C) 2009 Stefano Zacchiroli 
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# Requirements (Debian packages): python-debian python-markdown

usage = """Usage: render-dctrl [OPTION ...] [FILE ...]

Render a 822-like listing of Debian packages (AKA "Packages" file) to
XHTML, rendering (long) descriptions as Markdown text.  Render text
coming from FILEs, if given, or from standard input otherwise. Typical
usage is within a dctrl-tools pipeline, example:

  grep-available -s Package,Depends,Description ocaml | render-dctrl > foo.html

Warning: beware of #525525 and thus avoid using "-s Description" alone."""

import re
import string
import sys
from debian_bundle import deb822
from markdown import markdown
from optparse import OptionParser

options = None  # global, for cmdline options

css = """
body { font-family: sans-serif; }
dt {
  font-weight: bold;
}
dd {
  margin-bottom: 5pt;
}
div.package {
  border: solid 1pt;
  margin-top: 10pt;
  padding-left: 2pt;
  padding-right: 2pt;
}
.raw {
  font-family: monospace;
  background: #ddd;
  padding-left: 2pt;
  padding-right: 2pt;
}
.shortdesc {
  text-decoration: underline;
  margin-bottom: 5pt;
  display: block;
}
.longdesc {
  background: #eee;
}
span.package {
  font-family: monospace;
  font-size: 110%;
}
.uid {
  float: right;
  font-size: x-small;
  padding-right: 10pt;
}
"""
html_header = """http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
http://www.w3.org/1999/xhtml";>
  

%s
  
  
""" % css
html_trailer = """  

"""

mdwn_list_line = re.compile(r'^(\s*)[\*\+\-]')  # Markdown list item line
# mdwn_head_line = re.compile(r'^(\s*)#')   # Markdown header
padding = re.compile(r'^(\s*)')

def get_indent(s):
m = padding.match(s)
if m:
return len(m.group(1))
else:
return 0

def render_longdesc(lines):
p

Re: Consistent formating long descriptions as input data

[Andreas Tille]

On Sun, 26 Apr 2009, Stefano Zacchiroli wrote:


I've on purpose not looked at Andreas implementation, in order to see
if we have mutually thought at different issues. That also means that
it can be utterly buggy, you have been warned :-)


At short look I have the following diff:

--- render-dctrl.orig   2009-04-26 21:31:36.0 +0200
+++ render-dctrl2009-04-26 22:00:13.0 +0200
@@ -104,6 +104,10 @@
 store_para()
 curpara, inlist, listindent = [], False, 0
 else:
+   # accept also '.' and 'o' as bullets
+   l = re.sub('^(\s*)[.o]\s+', '\\1* ', l)
+   # use real URLs
+   l = re.sub('<*([fh]t?tp://[-./\w?=~;&]+)>*', '[\\1](\\1)', l)
 m = mdwn_list_line.match(l)
 if not inlist and m and curpara:
 # RULE 2: handle list item *not* at paragraph beginning


to enable working with currently used bullet symbols '.' and 'o' as well
as it was suggested above in the thread.  Moreover we should probably use
properly formated links if an URL is given.  Please not that my suggested
patch does not work in the examples I tried but I'm currently not able
to verify this.

You can view my implementation at [1] which leads to the examples
with several comments at [2].  I'd suggest to compare the result
of your implementation with the output on [2].


Library OCaml which provide a set of needed and useful macros for developing.
Modules and functionality are the follows :
.
 - Configuration_files: Allow to get information from configuration files
 - Environments: Environments are useful for maintaining the state, intendend
as a set of bindings, of a user interaction with a GUI
 - FilenameExtra: Additional features for the standard module Filename


That's definitely broken and should be fixed anyway.


PS mail like this one of mine should be better stored in the log of a
  bug report against the policy, to keep track of the
  status.
  Andreas: do we have one already?


Not yet because I was not able to draw a final conclusion out of all
this discussion and I would also like to give reST a try (according
to two hints here on this list and the fact that there are some
problematic issues with markdown adn I have no clue why).  A better
documented library would be interesting - but I a hint how to use
reST would be helpful.  I tried to format a single paragraph according
to some URL I found but thie does not really work without a header[3].
Any "competing" implementation in reST to compare where we have less
problematic issues - or even if the issues are more in terms of
the number of broken formatting but if the reasons for these
breakages are clear would be OK.


  If not, can you please
  submit it with references to the thread? ... or else shout and
  I'll do that.


Please go for it - as I said my spare time might be restricted.
I'm not on vac but time consuming issues are not the first thing
I would touch the next couple of days.

Kind regards

   Andreas.

[1] 
http://svn.debian.org/viewsvn/blends/blends/trunk/webtools/blendstasktools.py?content-type=text%2Fplain
--->  search for "def PrepareMarkdownInput(lines):"

[2] http://blends.debian.net/debug/tasks/
[3] http://code.activestate.com/recipes/193890/
--
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

[Jakub Wilk]

* Andreas Tille , 2009-04-26, 22:55:
I tried to format a single paragraph according to some URL I found but 
thie does not really work without a header[3].

[...]

[3] http://code.activestate.com/recipes/193890/

That's quite overcomplicated. The following code should do the thing:

from docutils.core import publish_parts

def reSTify(string):
return publish_parts(string, writer_name='html')['body']

--
Jakub Wilk


--
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

[Andreas Tille]

On Sun, 26 Apr 2009, Stefano Zacchiroli wrote:


Library OCaml which provide a set of needed and useful macros for developing.
Modules and functionality are the follows :
.
 - Configuration_files: Allow to get information from configuration files
 - Environments: Environments are useful for maintaining the state, intendend
as a set of bindings, of a user interaction with a GUI
 - FilenameExtra: Additional features for the standard module Filename


BTW, even if my implementation works for libocamlbricks-ocaml-dev [1]
I'd regard this rather as a bug than a feature, becuase it just should
not work - it should be formatted as separate lists.  When seeing cases
like this I teand to come back more and more to my initial suggestion:
Fix pure ASCII formatting first independently from the library which
might be used later.

Kind regards

Andreas.

[1] http://blends.debian.net/debug/tasks/debug#libocamlbricks-ocaml-dev

--
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

[Stefano Zacchiroli]

On Sun, Apr 26, 2009 at 10:55:31PM +0200, Andreas Tille wrote:
> At short look I have the following diff:

[ FWIW, if you want to try it out please use the live version [1],
  I've just fixed a stupid bug which caused ignoring the last
  paragraph of a description ]

[1] 
http://git.debian.org/?p=pkg-python-debian/python-debian.git;a=blob_plain;f=examples/deb822/render-dctrl;hb=HEAD

> +   # accept also '.' and 'o' as bullets
> +   l = re.sub('^(\s*)[.o]\s+', '\\1* ', l)
> +   # use real URLs
> +   l = re.sub('<*([fh]t?tp://[-./\w?=~;&]+)>*', '[\\1](\\1)', l)

> to enable working with currently used bullet symbols '.' and 'o' as
> well as it was suggested above in the thread.

Well, it depends on the goal. Mine was on the line of what I perceived
it was "consensus" (totally subjective perception), that of trying to
use a standard language: either Markdown or RST. My implementation is
for the former, and I tried to avoid supporting anything in
addition. The only exception I made is to split in place lists.

But if we have tons of '.' or 'o' lists, for sure we will need to
break that rule and support them. Do you have numbers about how many
such lists we have? If they are just a few they can easily be fixed,
if they are half the archive (which I doubt, having seen them rarely)
it would be a different story ...

>  Moreover we should probably use properly formated links if an URL
> is given.

I don't understand what you mean with this.

> You can view my implementation at [1] which leads to the examples
> with several comments at [2].  I'd suggest to compare the result of
> your implementation with the output on [2].

Fair enough, I'll try to made available on line a full rendering of
unstable using my implementation, updated routinely. It can then be
used as a more handy basis for comparison.

>>>  - Configuration_files: Allow to get information from configuration files
>>>  - Environments: Environments are useful for maintaining the state, 
>>> intendend
>>> as a set of bindings, of a user interaction with a GUI
>>>  - FilenameExtra: Additional features for the standard module Filename
>
> That's definitely broken and should be fixed anyway.

Full ACK, so not a blocking problem.

>>   If not, can you please submit it with references to the thread?
>>   ... or else shout and I'll do that.
> Please go for it - as I said my spare time might be restricted.
> I'm not on vac but time consuming issues are not the first thing
> I would touch the next couple of days.

If nobody from -policy objects, I'll submit it tomorrow.

Thanks for the comments!
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

[Stefano Zacchiroli]

On Sun, Apr 26, 2009 at 11:25:32PM +0200, Andreas Tille wrote:
> BTW, even if my implementation works for libocamlbricks-ocaml-dev
> [1] I'd regard this rather as a bug than a feature, becuase it just
> should not work

Agreed.

> - it should be formatted as separate lists.  When seeing cases like
> this I teand to come back more and more to my initial suggestion:
> Fix pure ASCII formatting first independently from the library which
> might be used later.

... but non sequitur on this.

Given that we agree that that example is just plainly broken no matter
what, why do you consider it as a valid motivation for throwing all
away? We cannot always enable a few packages (honestly assuming that
such formatting is uncommon) to block distro-wide improvements.  It
seems that having markup-formattable, yet readable, long descriptions
is just behind the corner ... just believe in it a few bits more :-)

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

[Manoj Srivastava]

On Sun, Apr 26 2009, Stefano Zacchiroli wrote:


> Well, it depends on the goal. Mine was on the line of what I perceived
> it was "consensus" (totally subjective perception), that of trying to
> use a standard language: either Markdown or RST.

This is what I as trying to push towards, and I too thought we
 had a rough consensus on it.

> My implementation is for the former, and I tried to avoid supporting
> anything in addition. The only exception I made is to split in place
> lists.


> But if we have tons of '.' or 'o' lists, for sure we will need to
> break that rule and support them. Do you have numbers about how many
> such lists we have? If they are just a few they can easily be fixed,
> if they are half the archive (which I doubt, having seen them rarely)
> it would be a different story ...

 ,-- count-bullet-chars.sh --
 #!/bin/sh
 lists=/var/lib/apt/lists/*_sid_main_*_Packages
 total=`grep "^ *[-+\*o] " $lists | wc -l`
 for tag in "\*" "-" "+" "o"; do
   items=`grep "^ *$tag " $lists | wc -l`
   percent=`echo "scale=4; $items / $total * 100" | bc`
   echo "Tag $tag was used $items times ($percent%)"
 done
 `--

 Tag \* was used 9277 times (68.0900%)
 Tag - was used 3837 times (28.1600%)
 Tag + was used 120 times (.8800%)
 Tag o was used 390 times (2.8600%)


> If nobody from -policy objects, I'll submit it tomorrow.

Sounds good.

manoj

-- 
E = MC ** 2 +- 3db
Manoj Srivastava    
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


-- 
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

[Russ Allbery]

Manoj Srivastava  writes:

>> But if we have tons of '.' or 'o' lists, for sure we will need to
>> break that rule and support them. Do you have numbers about how many
>> such lists we have? If they are just a few they can easily be fixed,
>> if they are half the archive (which I doubt, having seen them rarely)
>> it would be a different story ...

> ,-- count-bullet-chars.sh --
> #!/bin/sh
> lists=/var/lib/apt/lists/*_sid_main_*_Packages
> total=`grep "^ *[-+\*o] " $lists | wc -l`
> for tag in "\*" "-" "+" "o"; do
>   items=`grep "^ *$tag " $lists | wc -l`
>   percent=`echo "scale=4; $items / $total * 100" | bc`
>   echo "Tag $tag was used $items times ($percent%)"
> done
> `--
>
> Tag \* was used 9277 times (68.0900%)
> Tag - was used 3837 times (28.1600%)
> Tag + was used 120 times (.8800%)
> Tag o was used 390 times (2.8600%)

And for completeness:

Tag \. was used 17 times (.1200%)

-- 
Russ Allbery (r...@debian.org)   


-- 
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

[Andreas Tille]

On Mon, 27 Apr 2009, Stefano Zacchiroli wrote:


Given that we agree that that example is just plainly broken no matter
what, why do you consider it as a valid motivation for throwing all
away?


That's not what I intended.  My intention is to give guidelines which
might be independent from a library because they can be understood by
developers without any knowledge of markdown, reST or other libs. If
the guideline says:  Make sure that your long description is formated
with the following rules to enable postprocessing using Markdown, reST
or others a developer has to read only one document and does not need
to understand a markup language (which is not hard - but subsumming
the features we need in one paragraph is easier and might increase
acceptance).


We cannot always enable a few packages (honestly assuming that
such formatting is uncommon) to block distro-wide improvements.  It
seems that having markup-formattable, yet readable, long descriptions
is just behind the corner ... just believe in it a few bits more :-)


Full agreement here.  But as I said I'm convinced that if you give
easy guidelines you can even smoothen the edge of the corner.  Moreover
this enables in several cases easier lintian checks which are a killer
feature to get rid of broken descriptions.

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

[Andreas Tille]

On Mon, 27 Apr 2009, Stefano Zacchiroli wrote:


[ FWIW, if you want to try it out please use the live version [1],
 I've just fixed a stupid bug which caused ignoring the last
 paragraph of a description ]

[1] 
http://git.debian.org/?p=pkg-python-debian/python-debian.git;a=blob_plain;f=examples/deb822/render-dctrl;hb=HEAD


+   # accept also '.' and 'o' as bullets
+   l = re.sub('^(\s*)[.o]\s+', '\\1* ', l)
+   # use real URLs
+   l = re.sub('<*([fh]t?tp://[-./\w?=~;&]+)>*', '[\\1](\\1)', l)



to enable working with currently used bullet symbols '.' and 'o' as
well as it was suggested above in the thread.


Well, it depends on the goal. Mine was on the line of what I perceived
it was "consensus" (totally subjective perception), that of trying to
use a standard language: either Markdown or RST. My implementation is
for the former, and I tried to avoid supporting anything in
addition.



BTW, that's fine.  Just forget the URL thingy.  But I've thougt supporting
'.' and 'o' for a transitional period sound like a reasonable move to
speed up the change (even if the use of these bullets should be warned about
by lintian).

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

[Stefano Zacchiroli]

On Sun, Apr 26, 2009 at 11:34:57PM -0500, Manoj Srivastava wrote:
> > If nobody from -policy objects, I'll submit it tomorrow.
> Sounds good.

Done: #525843. Discussion can continue in that bug log now, I guess.

Also, a live archive of all long descriptions (from unstable/amd64)
rendered as Markdown using render-dctrl is now available at
http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is weekly
re-generated. Anybody who spots "absurd" long descriptions there,
please shout.

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

[Daniel Burrows]

On Sat, Apr 25, 2009 at 10:12:45PM +0200, Andreas Tille  was 
heard to say:
> On Sat, 25 Apr 2009, Daniel Burrows wrote:
>
>>  I would prefer Restructured Text, for the simple reason that it has an
>> actual specification with a fairly complete description of its syntax
>> and semantics.
>
> I do not have practical experience with both and so I do not have
> any preference.  The only thing I'f fear is that we might loose track
> in finally solving the problem in discussing which library to use.
> So do you think I should try to switch from markdown to reST in the
> debug output project?

  I hesitate to tell you what to do, since I'm not the one doing the
work.  But I think it would be worthwhile to at least prototype both
options and see how they stack up.  I also should say that I only have
practical experience with Markdown (except that I've edited Wikis
occasionally and some of them use RST); the alternative looks better
to me, but it's easy to say that when I haven't actually used it. :-)

> For those who are interested: At
>
>   http://blends.debian.net/debug/tasks/

  Wow, that's a lot of work!  I certainly won't ask you to do it all
over again.

  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

[Andreas Tille]

On Mon, 27 Apr 2009, Daniel Burrows wrote:


 Wow, that's a lot of work!  I certainly won't ask you to do it all
over again.


No, not really.  I might replace just the markdown by the reST
call.  That's probabyl quite cheap and I might try this in the
next couple of days even while beeing under some time preasure
currently.

The grunt work is done here - but that's just solved:

   http://svn.debian.org/viewsvn/blends/projects/debug/tasks


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

[Bill Allombert]

On Mon, Apr 27, 2009 at 03:19:23PM +0200, Stefano Zacchiroli wrote:
> On Sun, Apr 26, 2009 at 11:34:57PM -0500, Manoj Srivastava wrote:
> > > If nobody from -policy objects, I'll submit it tomorrow.
> > Sounds good.
> 
> Done: #525843. Discussion can continue in that bug log now, I guess.
> 
> Also, a live archive of all long descriptions (from unstable/amd64)
> rendered as Markdown using render-dctrl is now available at
> http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is weekly
> re-generated. Anybody who spots "absurd" long descriptions there,
> please shout.

alsa-firmware-loaders does not look nice.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 


-- 
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

[Stefano Zacchiroli]

On Mon, Apr 27, 2009 at 08:05:11PM +0200, Bill Allombert wrote:
> > Also, a live archive of all long descriptions (from
> > unstable/amd64) rendered as Markdown using render-dctrl is now
> > available at http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is
> > weekly re-generated. Anybody who spots "absurd" long descriptions
> > there, please shout.
> 
> alsa-firmware-loaders does not look nice.

Nice catch!

Verbatim text not used for lists, as supported by current policy, was
not properly (read: at all) handled. It is fixed now, and
alsa-firmware-loaders does indeed look better.

Thanks,
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

[Bill Allombert]

On Mon, Apr 27, 2009 at 09:36:59PM +0200, Stefano Zacchiroli wrote:
> On Mon, Apr 27, 2009 at 08:05:11PM +0200, Bill Allombert wrote:
> > > Also, a live archive of all long descriptions (from
> > > unstable/amd64) rendered as Markdown using render-dctrl is now
> > > available at http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is
> > > weekly re-generated. Anybody who spots "absurd" long descriptions
> > > there, please shout.
> > 
> > alsa-firmware-loaders does not look nice.
> 
> Nice catch!
> 
> Verbatim text not used for lists, as supported by current policy, was
> not properly (read: at all) handled. It is fixed now, and
> alsa-firmware-loaders does indeed look better.

Please have a look at garlic-doc. It does not look right.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 


-- 
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

[James Vega]

On Mon, Apr 27, 2009 at 10:19:54PM +0200, Bill Allombert wrote:
> On Mon, Apr 27, 2009 at 09:36:59PM +0200, Stefano Zacchiroli wrote:
> > On Mon, Apr 27, 2009 at 08:05:11PM +0200, Bill Allombert wrote:
> > > > Also, a live archive of all long descriptions (from
> > > > unstable/amd64) rendered as Markdown using render-dctrl is now
> > > > available at http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is
> > > > weekly re-generated. Anybody who spots "absurd" long descriptions
> > > > there, please shout.
> > > 
> > > alsa-firmware-loaders does not look nice.
> > 
> > Nice catch!
> > 
> > Verbatim text not used for lists, as supported by current policy, was
> > not properly (read: at all) handled. It is fixed now, and
> > alsa-firmware-loaders does indeed look better.
> 
> Please have a look at garlic-doc. It does not look right.

It's using `o' as the bullet character which is not supported by
Markdown/rST.  This has already been identified as a case that will need
to be fixed by the individual packages (or pre-processed into some other
character).

-- 
James
GPG Key: 1024D/61326D40 2003-09-02 James Vega 


signature.asc
Description: Digital signature

Re: Consistent formating long descriptions as input data

[Stefano Zacchiroli]

On Mon, Apr 27, 2009 at 04:53:11PM -0400, James Vega wrote:
> > Please have a look at garlic-doc. It does not look right.
> It's using `o' as the bullet character which is not supported by
> Markdown/rST.  This has already been identified as a case that will need
> to be fixed by the individual packages (or pre-processed into some other
> character).

Full ACK.

FWIW, note that with the fix induced by the first of Bill reports, I
consider garlic-doc looking right. As it is not a Markdown list, it is
rendered as ordinary verbatim text.

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)

[Stefano Zacchiroli]

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)

[Andreas Tille]

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)

[Don Armstrong]

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)

[Vincent Danjean]

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)

[Lars Wirzenius]

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)

[Stefano Zacchiroli]

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)

[Lars Wirzenius]

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)

[Don Armstrong]

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)

[Andreas Tille]

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)

[Andreas Tille]

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)

[Andreas Tille]

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
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$


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)

[Stefano Zacchiroli]

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)

[Lars Wirzenius]

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
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$ 



-- 
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)

[Andreas Tille]

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)

[Holger Levsen]

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)

[Vincent Danjean]

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)

[Michael Banck]

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)

[Andreas Tille]

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

Re: Consistent formating long descriptions as input data (Was: RFC: Better formatting for long descriptions)

[Stefano Zacchiroli]

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)

[Michael Banck]

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)

[Andreas Tille]

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)

[Daniel Burrows]

On Tue, Apr 21, 2009 at 09:31:31AM +0200, Andreas Tille  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)

[Andreas Tille]

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