Bug#525843: support for encoding long descriptions using a standard text-based markup language
On Fri, Sep 11, 2009 at 08:00:41PM -0500, Manoj Srivastava wrote: Hi, There are some differences in how thee systems define lists; and I think markdown is more forgiving with simple lists Consider that continuing lines in markdown lists do not have to be aligned after the white space: Markdown --8---cut here---start-8--- * blah blah blah more blah blah is fine --8---cut here---end---8--- restructured. --8---cut here---start-8--- * blah blah blah more blah blah needs to be precisely aligned --8---cut here---end---8--- I have to say, I find the latter more readable. The former is ambiguous. Numbered list in markdown do not have to be sequential, but in Rst you use #. or you need to have them sequential. On the other hand, rst is way better with definition lists or field lists; I just think that plain lists are more likely to belong in a description field. Block quotes in Rst are just indented paragraphs, and seem closer to the behaviour we currently have (Markdown uses to do block quotes) . Advantage Rst here, I think. So, here is my take on a subset that needs to be supported in policy (I do not think we need titles, don't you agree?) a) Unordered lists use asterisks, pluses, and hyphens — interchangeably — as list markers. b) Ordered lists use numbers followed by periods. 1) The numbers need not be i sequence -- but you should still start the list with the number 1. 2) The numbers need to be in sequence -- but may use #. instead to get auto numbering. Autonumbering seems a nice feature, but for some one reading the plain text version, this probably not so much a good idea. c) List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab. d) A hyperlink reference may directly embed a target URI inline, within angle brackets: http://www.debian.org e) nested lists are created by indenting the nested list 1) by at least 4 spaces, or 2) have a blank line above, and line up with the previous paragraph. f) List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must 1) have its first line indented by at least 4 spaces, or 2) must line up with the paragraph above, relative to the bullet marker g) Emphasis is provided by surrounding the text with '*'. Like *emphasis*. Stronger emphasis is provided by doubling the '*' -- like **strong**. I do not find *emphasis* very readable in plain text. However a case could be made for marking some words as having a special meaning , for example if policy stated that writing *foobar* denotes that foobar is the name of a Debian package, then HTML converted could link foobar to packages.debian.org/foobar automatically. For example the description of xfig could be written as: ... You should also think about installing *xfig-doc*, which contains the documentation and *xfig-libs*, which contains several clip art libraries. ... and converted to HTML as You should also think about installing a href=packages.debian.org/xfig-doc xfig-doc/a, which contains ... (Sorry I am lacking useful English terminology here). Once we decide on which language to use, I can tighten up the spec above. By sticking to these conventions, I think the plain text description is readable, and indeed, conveys the intent. Would you rewrite this spec in both Markdown and restructured text so that we can compare ? (two/third joking of course :)) Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#525843: support for encoding long descriptions using a standard text-based markup language
On Fri, Sep 11, 2009 at 08:00:41PM -0500, Manoj Srivastava wrote: So, here is my take on a subset that needs to be supported in policy (I do not think we need titles, don't you agree?) I agree, we don't want titles. a) Unordered lists use asterisks, pluses, and hyphens — interchangeably — as list markers. b) Ordered lists use numbers followed by periods. 1) The numbers need not be i sequence -- but you should still start the list with the number 1. 2) The numbers need to be in sequence -- but may use #. instead to get auto numbering. c) List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab. d) A hyperlink reference may directly embed a target URI inline, within angle brackets: http://www.debian.org I'm not sure hyperlinks are needed either. e) nested lists are created by indenting the nested list 1) by at least 4 spaces, or 2) have a blank line above, and line up with the previous paragraph. f) List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must 1) have its first line indented by at least 4 spaces, or 2) must line up with the paragraph above, relative to the bullet marker g) Emphasis is provided by surrounding the text with '*'. Like *emphasis*. Stronger emphasis is provided by doubling the '*' -- like **strong**. I definitely don't want to see people starting to abuse package descriptions by using emphasis markup. Package descriptions should stand on their own without pretty fonts. :) -- Steve Langasek Give me a lever long enough and a Free OS Debian Developer to set it on, and I can move the world. Ubuntu Developerhttp://www.debian.org/ slanga...@ubuntu.com vor...@debian.org signature.asc Description: Digital signature
Bug#525843: support for encoding long descriptions using a standard text-based markup language
On Thu, Sep 10, 2009 at 05:43:01PM -0500, Manoj Srivastava wrote: Looking at the bug report, I can agree that there is a rough consensusabout using a standard text-based markup language to interpret package long descriptions. What is unclear, though, which of the two equivalent languages (Markdown or ReStructured Text) are being proposed here -- either one of these would be acceptable, and there are working implementations of either that seem to do a very creditable job. We need to pick one or the other (and at this point, I am agnostic to whatever is picked, since either is a standard that is popular and is not a NIH spec) -- and I do not see anything claer about which one policy should support. We could, as an example, go by pop-con results for the interpreters -- that is one defensible means of selecting the language, I guess. My main concern with this request is that by blessing the use of a text-based markup language for lists, we not end up in a situation where maintainers are using more extensive markup that makes the package descriptions less legible as plain text. As long as the policy language is precise in limiting this to list formatting, I agree that both of the options should do the job fine. And I think even flipping a coin would be a defensible means of selecting, in this case. :) -- Steve Langasek Give me a lever long enough and a Free OS Debian Developer to set it on, and I can move the world. Ubuntu Developerhttp://www.debian.org/ slanga...@ubuntu.com vor...@debian.org signature.asc Description: Digital signature
Bug#525843: support for encoding long descriptions using a standard text-based markup language
On Thu, Sep 10, 2009 at 11:25:50PM -0700, Steve Langasek wrote: On Thu, Sep 10, 2009 at 05:43:01PM -0500, Manoj Srivastava wrote: Looking at the bug report, I can agree that there is a rough consensusabout using a standard text-based markup language to interpret package long descriptions. What is unclear, though, which of the two equivalent languages (Markdown or ReStructured Text) are being proposed here -- either one of these would be acceptable, and there are working implementations of either that seem to do a very creditable job. We need to pick one or the other (and at this point, I am agnostic to whatever is picked, since either is a standard that is popular and is not a NIH spec) -- and I do not see anything claer about which one policy should support. We could, as an example, go by pop-con results for the interpreters -- that is one defensible means of selecting the language, I guess. My main concern with this request is that by blessing the use of a text-based markup language for lists, we not end up in a situation where maintainers are using more extensive markup that makes the package descriptions less legible as plain text. As long as the policy language is precise in limiting this to list formatting, I agree that both of the options should do the job fine. I agree, and I come to think that specifying explicitly in policy a small subset of either Markdown or ReStructured Text (or preferably of the intersection of them) as allowable for package description would be a safer option. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#525843: support for encoding long descriptions using a standard text-based markup language
Hi, There are some differences in how thee systems define lists; and I think markdown is more forgiving with simple lists Consider that continuing lines in markdown lists do not have to be aligned after the white space: Markdown --8---cut here---start-8--- * blah blah blah more blah blah is fine --8---cut here---end---8--- restructured. --8---cut here---start-8--- * blah blah blah more blah blah needs to be precisely aligned --8---cut here---end---8--- Numbered list in markdown do not have to be sequential, but in Rst you use #. or you need to have them sequential. On the other hand, rst is way better with definition lists or field lists; I just think that plain lists are more likely to belong in a description field. Block quotes in Rst are just indented paragraphs, and seem closer to the behaviour we currently have (Markdown uses to do block quotes) . Advantage Rst here, I think. So, here is my take on a subset that needs to be supported in policy (I do not think we need titles, don't you agree?) a) Unordered lists use asterisks, pluses, and hyphens — interchangeably — as list markers. b) Ordered lists use numbers followed by periods. 1) The numbers need not be i sequence -- but you should still start the list with the number 1. 2) The numbers need to be in sequence -- but may use #. instead to get auto numbering. c) List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab. d) A hyperlink reference may directly embed a target URI inline, within angle brackets: http://www.debian.org e) nested lists are created by indenting the nested list 1) by at least 4 spaces, or 2) have a blank line above, and line up with the previous paragraph. f) List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must 1) have its first line indented by at least 4 spaces, or 2) must line up with the paragraph above, relative to the bullet marker g) Emphasis is provided by surrounding the text with '*'. Like *emphasis*. Stronger emphasis is provided by doubling the '*' -- like **strong**. Once we decide on which language to use, I can tighten up the spec above. By sticking to these conventions, I think the plain text description is readable, and indeed, conveys the intent. manoj -- Honesty is for the most part less profitable than dishonesty. Plato Manoj Srivastava sriva...@debian.org http://www.debian.org/~srivasta/ 1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#525843: support for encoding long descriptions using a standard text-based markup language
package debian-policy user debian-pol...@packages.debian.org usertag 525843 = normative discussion thanks Hi, Looking at the bug report, I can agree that there is a rough consensusabout using a standard text-based markup language to interpret package long descriptions. What is unclear, though, which of the two equivalent languages (Markdown or ReStructured Text) are being proposed here -- either one of these would be acceptable, and there are working implementations of either that seem to do a very creditable job. We need to pick one or the other (and at this point, I am agnostic to whatever is picked, since either is a standard that is popular and is not a NIH spec) -- and I do not see anything claer about which one policy should support. We could, as an example, go by pop-con results for the interpreters -- that is one defensible means of selecting the language, I guess. manoj ps: people on the mailing list who are not conversant with this bug are encouraged to follow the links in the initial bug report and the followup before making their minds on this -- Random, n.: As in number, predictable. As in memory access, unpredictable. Manoj Srivastava sriva...@debian.org http://www.debian.org/~srivasta/ 1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#525843: support for encoding long descriptions using a standard text-based markup language
Package: debian-policy Version: 3.8.1.0 Severity: wishlist [ submitting bug report as requested at http://lists.debian.org/debian-policy/2009/04/msg00155.html ] Andreas Tille, has recently (re-)raised the issue of consistent formatting of lists in long descriptions [1,2]. [1] http://lists.debian.org/debian-devel/2009/03/msg01165.html [2] http://lists.debian.org/debian-devel/2009/04/msg00757.html From the discussion, it emerged that there is rough consensus (or at least it seems so to some of the participants, including myself and Manoj) about using a standard text-based markup language to interpret package long descriptions. Technically, the 2 mentioned solutions have been Markdown [3] and ReStructured Text [4]. With both of them, the idea is that *current* long descriptions are already processable as if they were in that format, with very few exceptions. [3] http://daringfireball.net/projects/markdown/ [4] http://docutils.sourceforge.net/rst.html Implementations have been proposed already, in the form of tools that process packages long descriptions and output their corresponding rendered HTML format. In particular, 2 implementations have been presented for Markdown already: one by Andreas [5] and one by me [6]. [5] http://lists.debian.org/debian-policy/2009/04/msg00146.html [6] http://git.debian.org/?p=pkg-python-debian/python-debian.git;a=blob_plain;f=examples/deb822/render-dctrl;hb=HEAD Additionally, a weekly-generated archive of all long descriptions rendered with Markdown is now available at: http://upsilon.cc/~zack/stuff/longdesc-mdwn/ . It is based on [6] above. Cheers. -- System Information: Debian Release: squeeze/sid APT prefers unstable APT policy: (500, 'unstable'), (500, 'testing'), (1, 'experimental') Architecture: amd64 (x86_64) Kernel: Linux 2.6.29-1-amd64 (SMP w/2 CPU cores) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/bash debian-policy depends on no packages. debian-policy recommends no packages. Versions of packages debian-policy suggests: ii doc-base 0.9.1 utilities to manage online documen -- no debconf information -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
