Re: RFC: Better formatting for long descriptions
- To: debian-devel@lists.debian.org
- Cc: debian-policy@lists.debian.org
- Subject: Re: RFC: Better formatting for long descriptions
- From: Manoj Srivastava <srivasta@debian.org>
- Date: Thu, 16 Apr 2009 12:50:12 -0500
- Message-id: <[🔎] 87d4bca3or.fsf@anzu.internal.golden-gryphon.com>
- Mail-followup-to: debian-devel@lists.debian.org, debian-policy@lists.debian.org
- In-reply-to: <871vrsbo1f.fsf@anzu.internal.golden-gryphon.com> (Manoj Srivastava's message of "Thu, 16 Apr 2009 10:45:16 -0500")
- References: <20090323000750.GK20778@nighthawk.chemicalconnection.dyndns.org> <20090323062445.GW5004@mykerinos.kheops.frmug.org> <20090323100417.GB20778@nighthawk.chemicalconnection.dyndns.org> <alpine.DEB.2.00.0903231313470.12350@wr-linux02> <20090416035346.GA13462@gluon.hadrons.org> <873ac9cd60.fsf@anzu.internal.golden-gryphon.com> <alpine.DEB.2.00.0904160915130.25147@wr-linux02> <87tz4paw6b.fsf@anzu.internal.golden-gryphon.com> <alpine.DEB.2.00.0904160959010.25147@wr-linux02> <87iql5as67.fsf@anzu.internal.golden-gryphon.com> <20090416094455.GH5853@pear.tzafrir.org.il> <871vrsbo1f.fsf@anzu.internal.golden-gryphon.com>
Hi,
I think we need to enumerate some goals for this proposed
change. Here is a start:
- Minimal disruption for current packages. The impact should be
measured by numbers of packages impacted
+ Any specification of which of *, +, - to use as th first level item
will impact more packages than not specifying it, by several
hundred
+ The same is true for specifying the mark used for second level list
items
+ Specifying exact number of spaces will also hit current packages,
and will be a source of errors in the future.
- Ability to recognize and render the following logical entities, in
decreasing order of importance:
+ unordered lists
+ ordered lists
+ emphasis
+ strong emphasis
+ definition lists
+ hypertext links
+ underlines, and strike throughs
- Readability for people looking at non-enhanced renditions, i.e.,
using less on the Packages file. Sticking to widely known
conventions, using the same conventions that peple are used to using
in email, and Wikis, is a plus.
- Ease of use for description writers.
Again, sticking with standards that people already know and use is
better than making our own, more restrictive standards
- Not adding hugely to bloat for the Packages file
This kinda excludes verbose markup like XML (which would have failed
the readability test too)
At this point, I would say that Markdown/Resstructued text meets
most of the goals above, as long as we restrict the markup to the list
above:
* unordered lists
* ordered lists
* emphasis
* strong emphasis
* definition lists
* hypertext links
* underlines, and strike throughs
manoj
--
"If we can't fix it -- we'll fix it so nobody can." Gibbons
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: