Talk:reStructuredText

Original stub

The original stub for "ReStructured Text" (note the space) was as follows:

reStructuredText (abbreviated reST) is a lightweight markup language capable of being read in its plaintext form. The standard Python module Docutils uses reST.

-- Korpios 20:09, 16 June 2004 (UTC)

Initial changes

I'm trying to turn it into a full-blown article, as I use RST all the time. I made a new article for "ReStructuredText" (the proper name), set up a redirect from "ReStructured Text" to "ReStructuredText", made some changes, removed the awkward formatting (as it's purely aesthetic), and added the article to Wikipedia:List of pages whose correct title is not allowed by MediaWiki (because of the leading lowercase "r").

-- Korpios 20:14, 16 June 2004 (UTC)

Er, the proper name is “reStruturedText” (I find it a bit ugly since I loathe stupidly capitalized names but it is named so). You can read a capitalized inital “r” where title case is used or at the beginning of a sentence. Regarding the abbreviations, I’ve noticed the it is abbreviated “reST” in human talk and “rst” in code. Best, fr:User:Leafcat —Preceding unsigned comment added by 90.21.186.39 (talk) 16:54, 29 March 2008 (UTC)

Markdown

What's the relation of RST to Markdown? I notice that all the syntax (except the hyperlinks) seems to be the same. --Gwern (contribs) 18:59 17 January 2009 (GMT)

ReStructuredText and Markdown are two different Lightweight markup languages. --24.252.38.194 (talk) 11:40, 22 October 2012 (UTC)

tool support

The removal of the large "Tool Support" section (19:36, 19 April 2010 Thumperward) IMHO, is a *bad* thing. This information is extremely useful. Let me argue that without tool support, a markup language is merely a thought experiment.

This kind of compilation can't be found anywhere else. Insisting on form over substance diminishes the availability of knowledge, and I can't fathom how this serves the mission statement of Wikipedia.

If, however, after the proper debate this section would be scheduled for removal, please indicate this change before making it, and allow this information to be archived elsewhere (http://article.gmane.org/gmane.text.docutils.user/5713). - Chenlevy (talk) 13:45, 25 April 2010 (UTC)

There's nothing stopping people from retrieving the list from the page history, although it should never have been added in the first place. I would suggest that, having canvassed for this off-wiki, the onus is now on you to locate a suitable host. Wikipedia is not a resource portal for this kind of thing, and the presence of a huge collection of external links was to the detriment of this article in that it hid the article's deficiencies. I'll be removing the inappropriate content again on the next pass. Chris Cunningham (not at work) - talk 10:24, 26 April 2010 (UTC)

Is it appropriate to put this link at the external links section? Also regarding Copyrights and attribution, although I am the original author of most of that text, some other people contributed fixes, so my question is do I need to put some boiler plate text above the answer linked to? Does it matter if this text is removed from Wikipedia? I believe that the stackoverflow.com content is licensed under Creative Commons Attribution-Share Alike 2.5 Generic. Chenlevy (talk) 06:20, 2 May 2010 (UTC)

WP:EL discourages linking to user-generated content like this precisely because it is open-ended and there can be no guarantee as to its quality at a given time. For what it's worth, if you're going to copy the text (which you are permitted to do by the license) then I believe that you still need proper attribution, such as the URL of the page revision that the material was taken from. Chris Cunningham (not at work) - talk 10:13, 4 May 2010 (UTC)

Maybe in this case an exception would be appropriate. this list is unique on the web, useful on the topic, and not likely to be changed in a quality-decreasing way. – Flying sheep (talk) 22:15, 25 February 2011 (UTC)

Notability

reStructuredText is a syntax, not a web page or web service, thus "web notability" rules are inapplicable. Each of the many independent tools supporting the syntax demonstrate the notability of the syntax. Perhaps the list of tools supporting the syntax might be translated into citations rather than appearing in the body of the article, although it is valuable that the character of the tools (editors, translators, web services, etc.) is noted.

Thyrsus (talk) 18:17, 27 April 2010 (UTC)

Notability is established through the inclusion of reliable secondary sources. Of the "many independent tools" included here, nor one currently cites a secondary source which establishes its importance. The existence of a tool to do something on the Web is irrelevant if it is not noticed, much like the proverbial tree falling in the forest. Chris Cunningham (not at work) - talk 21:04, 27 April 2010 (UTC)

The Sphinx tool generates much of the documentation at python.org. The python language is important; the maintainers of the python language are important; the documentation of the python language is important. Each of the reStructuredText tools is a reliable secondary source to the topic at hand, which is reStructuredText, in distinction to a primary source such as reStructuredText reference pages. Thyrsus (talk) 21:51, 28 April 2010 (UTC)

Notability is not inherited. A secondary source is one which reports, analyses or interprets a primary source; the "references" added were just links to project home pages, which are simply primary sources for the software they represent. And this is hardly the first time this has been discussed on Wikipedia: our articles are not resource portals for people to go and find handy software on a given subject. Treating them as such is to the detriment of the project's value as a neutral tertiary source of descriptive information. Chris Cunningham (not at work) - talk 14:05, 29 April 2010 (UTC)

It was claimed that the software cited was subject to a "tree falls in the forest" argument; evidence is provided that this case refers to a Tunguska event rather than an anonymous sappling.

Each of the tools cited is a secondary source, because each either parses (analyses) or generates (inteprets) the syntax of reStructuredText. That holds not just for the artifact of the software, but for each of the software authors as well. The specific analyses are available at the links provided, generally in formal technical language, a.k.a. source code. The analysis and interpretation necessary to create software is more disciplined and exhaustive than analyses or interpretations in nearly any other field save mathematics. This establishes each project as a secondary source for reStructuredText. Such a large, thorough and diverse set of secondary sources establishes the notability of reStructuredText.

For any article, the collection of citations supporting the article is a "resource portal". The article must also provide the descriptive information (tertiary material) supported by those citations, which this article does.

Thyrsus (talk) 22:45, 3 May 2010 (UTC)

I'm afraid that these arguments either misinterpret or ignore both the present wording of WP:RS and WP:EL and the spirit behind said wording. This article's subject is in no way unique as regards how it is covered by secondary sources; if we can find references for TeX or XML which do not need an original interpretation of WP policy to be acceptable then there is no reason we cannot do so here. For the time being, these pseudo-references lower the quality of this article and impede its improvement. I have removed them again; I would advise you to examine other high-quality articles on similar subjects to check the prevailing style, paying particular attention to the treatment given to open-ended lists of external resources. Chris Cunningham (not at work) - talk 10:09, 4 May 2010 (UTC)

I would note that the recently-added IBM DeveloperWorks link does a rather excellent job of providing the context and design details that this article currently lacks. It would be great to have that type of content cited from there. Chris Cunningham (not at work) - talk 08:26, 8 May 2010 (UTC)

I can't believe that it's even being questioned that rst is notable - it's used in the Python documentation for crying out loud - see http://docs.python.org/documenting/index.html. According to the Wikipedia guidelines for notability, "Wikipedia should avoid articles about web sites that could be interpreted as advertising. For material published on the web to have its own article in Wikipedia, it should be notable and of historical significance." Obviously this page is not being used for advertising, and rst is of importance since Python is important. I'm going to remove the flag for deletion - it's been up there since April 2010 and it's now Jan 2011. ffangs (talk) 23:02, 21 January 2011 (UTC)

A few reflections:

1. well, yes it is notable enough: it is used not only for Python doc, it was not, AFAIK, originally intended for Python only – this quest for some WYSIWYGoid plain-text format is an undercurrent among rich-text mongers like me who alternate between plain-text, TeX and HTML ... but that's in my (humble?) opinion ...
2. ReStructuredText is not a format – formats have some standardization level, be it just by a free reference manual – it is one or more toolkits defacto-conforming to a common conversion functionality (also IM(H?)O).

Rursus dixit. (^mbork³!) 09:38, 30 November 2011 (UTC)

Extensibility

It would be good to mention reStructuredText's extensibility in this article. This sets it apart from many of the other lightweight markup syntaxes.

References:

• http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
• http://docutils.sourceforge.net/docs/howto/rst-directives.html — Preceding unsigned comment added by Bmachiel (talk • contribs) 13:56, 26 August 2015 (UTC)