Re: Consistent formating long descriptions as input data
On Fri, Apr 24, 2009 at 08:37:22AM +0200, Andreas Tille <tillea@rki.de> 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 <Daniel Burrows Daniel_Burrows@alumni.brown.edu>
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,
- <q>`--show-summary`</q>, to the <q>`why`</q>
- 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 <q>summary mode</q>:
-
- - `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
- option does not wrap lines intelligently yet, so the
- output can become messy if you have long dependency
- chains and narrow terminals.
-
- [[!img aptitude-0.5.2-why-show-summary.png size="400x400"]]
+ <q>`--show-summary`</q>, to the <q>`why`</q> 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
+ <q>summary mode</q>:
+
+ 1. `no-summary`: don't show a summary.
+
+ 2. `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.
+
+ 3. `last-package-and-type`: display the last package in each
+ chain, along with an indication of the strength of the chain.
+
+ 4. `all-packages`: briefly display each chain of packages in its
+ entirety.
+
+ 5. `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 option does
+ not wrap lines intelligently yet, so the output can become messy
+ if you have long dependency chains and narrow terminals.
+
+ [[!img aptitude-0.5.2-why-show-summary.png size="400x400"]]
+ **\[gtk]** When the user clicks on a package in the dashboard's list of
upgrades, the changelog display automatically scrolls to
Reply to: