Re: RFC: Better formatting for long descriptions
On Sat, 18 Apr 2009, Manoj Srivastava wrote:
Frankly, I have no idea where this trade is going.
IMHO the problem is that you assume our suggestions are in contrast to
each other - but they are not. I wanted to iron out suggestions how
to format the input in a standardised way. What will be done afterwards
is the choice of people who are working with this input. I don't care
whether they choose markdown, restructured text or just take your
perl code and use <ul> / </ul> instead of the additional blank lines
and wrapp the lines in lists in <li> / </li> tags if they need HTML
output. But this is NOT to be discussed HERE (even if it does not
harm. The point is that our input should ENABLE this which needs
a better standardisation of long descriptions.
You are one step after this - and your input is welcome - but there
is no contradiction.
With a 6 line pre-processor, you can feed the grep-dctrl
provided Description fields to Markdown.
BTW, your pre-processor will need some additional lines if it comes to
second level lists (and yes, I'm sure this can easily be done - but
this is, and never was the point)
So, seems like we have come
somewhere -- we have had one investigation that leads one to believe
that there are a small fraction of packages using "o" as a bullet that
need to be changed, and apart fro that there are less than 50 packages
are affected
Great - let's iron out the advise how to format long descriptions
in our docs to enable us to write lintian checks and file bug reports.
Manoj, we really reached a point here!
(if we want to specify markdown as the markup language for
descriptions -- and these are the one where we have some unwanted
emphasis, a non-fatal result).
Please let's draw this to a different discussion. People who are
responsible for packages.debian.org might be interested and adopt
your idea.
There is a mechanism to pre-process the description for
markdown (Perl implementation below). What more is needed for you to
think this is leading somewhere?
Did I gave the impression that I wanted more? Honestly, I'd be
interested from what part of my mails you are drawing the conclusion
to enhance my communication skills.
All I am doing with the code is inserting a line before the
lists. I am not generating html. I am not also handling the _other_
markup that markdown handles, that I presented as something that will
make the description more readable too. The markdown librarys does all
the heavy lifting fro the html generation. If you think my little perl
snippet is the equivalent for what markdown does, you have not looked
at markdown.
In the whole discussion I was talking about structuring the input
to ENABLE turning it to html (or whatever structured output you need).
You were discussing steps to actually *do* the step I just wanted to
provide the precondition for. I just was saying if you need a
preprocessor for a library while you could reach a similar result
by tweaking the preprocessor a little bit. I just do not want to
force any programmer to use markdown (even if it has advantages
admittedly as I also agreed to). This was a *sidenote* because this
whole processing of the input is just not my point.
I am not re-inventing the wheel when it comes to markup
languages.
Same for me - or am I writing in delirium???
And your divergence of the original topic just blurs the issue -
would you mind rereading my initial mail. [1] Do you agree that
long descriptions need enhancement or not?
We know we needed _some_ pre-processing because we have the
paragraphs separated by ' .', but the code is pretty minimal.
--8<---------------cut here---------------start------------->8---
my $in=0;
while(<>) {
chomp; s/^ //g; s/^\.\s*$//;
if(/^\s+[\*\+\-]\s+/) { print "\n" unless $in++;}
else { $in=0; }
print "$_\n"
}
--8<---------------cut here---------------end--------------->8---
manoj
ps: This can easily become a shell function.
Again: Please asume for the rest of this thread that I'm not stupid
and know how scripts can be used.
__> grep-aptavail -s Description -P airport-utils | perl -e '
my $in=0;
while(<>) {
chomp; s/^ //g; s/^\.\s*$//;
if(/^\s+[\*\+\-]\s+/) { print "\n" unless $in++;}
else { $in=0; }
print "$_\n"
}' | markdown
<p>Description: configuration and management utilities for Apple AirPort base stations
This package contains various utilities to manage the Apple AirPort base
stations.</p>
<p>Be aware that Apple released several versions of the AirPort base station;
the original AirPort ("Graphite") was a rebranded Lucent RG-1000 base
station, doing 802.11a/b. The AirPort Extreme ("Snow") is an Apple-built
802.11a/b/g base station.</p>
<p>For the original Apple AirPort and the Lucent RG-1000 base stations only:</p>
<ul>
<li>airport-config: base station configurator</li>
<li>airport-linkmon: wireless link monitor, gives information on the wireless
link quality between the base station and the associated hosts</li>
</ul>
<p>For the Apple AirPort Extreme base stations only:</p>
<ul>
<li>airport2-config: base station configurator</li>
<li>airport2-portinspector: port maps monitor</li>
<li>airport2-ipinspector: WAN interface monitoring utility</li>
</ul>
<p>For all:</p>
<ul>
<li><p>airport-modem: modem control utility, displays modem state, starts/stops
modem connections, displays the approximate connection time (Extreme only)</p>
<ul>
<li>airport-hostmon: wireless hosts monitor, lists wireless hosts connected
to the base station (see airport2-portinspector for the Snow)</li>
</ul></li>
</ul>
I wonder why you are insisting in providing broken examples. The last
list is formatted wrong - the original description did not contained a
second order list but your result does. The only thing you are doing
is proving my point that we need to enhance the input first - but this
can be done more elegantly and simpler than you are doing.
I would regard it as really helpfull if you would concentrate on
the help I asked for with the words "This suggestion is far from
complete and should be enhanced." in [1]. Once the input data is
well structured we could start another discussion what might be the
best way to process this data.
Kind regards
Andreas.
[1] http://lists.debian.org/debian-devel/2009/03/msg01165.html
--
http://fam-tille.de
Reply to: