[SR-7454] .rst files are extremely developer-unfriendly

[davedelong]

Previous ID	SR-7454
Radar	None
Original Reporter	@davedelong
Type	Bug

Additional Detail from JIRA

Votes	1
Component/s	Compiler
Labels	Bug, Documentation
Assignee	@MaxDesiatov
Priority	Medium

md5: 42c38599a264a7abead082e305ce5b36

Issue Description:

For someone who's wanting to learn about Swift, they might consider going to the docs folder to learn more, and especially the "Lexicon" file.

However, they're greeted by a wall of .rst files, and macOS has no clue what .rst files are. Quicklooking on them just greets you with a blank file icon and no idea what the contents are. An intrepid person might think about popping a file open in their text-editor-of-choice, but it's not hard to imagine that someone might assume they'd need some crazy special tool in order to use these files and give up to go look somewhere else.

Please use a sane and common file format for the docs.

[belkadan]

We had a project to convert them to Markdown but it stalled because it would lose semantic information. At this point someone should probably just pick that up again and do the best job they can.

[davedelong]

Agreed; I heard about that from CodaFi (JIRA User), and went and found it: #11053

[al45tair]

Personally I don't think we should be "fixing" this. ReStructuredText isn't an uncommon file format (it's used for 99% of Python documentation, and also for various other things outside of the Python ecosystem). It has significant advantages over Markdown for long-format technical documentation, since that's what it was designed for (whereas Markdown was designed for writing simple blog posts). Even with a decent set of (fairly) standardised extensions there are things that are not so good in Markdown.

As for the Quicklook preview not working, it actually won't work for Markdown by default either — you need a program installed that declares the UTI for it to work (it so happens Xcode declares the UTI for Markdown).

We should probably file bug reports against Core Services asking for the UTIs for both Markdown and ReStructuredText to be declared in the Core Types bundle that lives in /System/Library/CoreServices. That would additionally help to fix the issue with people declaring random UTIs for Markdown (there are a number of different ones in common use, perhaps the most obnoxious being public.markdown, which is someone other than Apple declaring a type with a name starting with public), and would make it so that users without Xcode (or any programmer's editor) installed would be able to Quicklook a .md file.

In an ideal world, we'd have a Quicklook plugin that could render Markdown and ReStructuredText as well.

We should probably also look at supporting ReStructuredText input for DocC, if that's the stated motivation for rewriting these files. It seems to me that it'd be better spending time adding a feature to DocC rather than spending it rewriting existing documentation.

[MaxDesiatov]

It seems to me that it'd be better spending time adding a feature to DocC rather than spending it rewriting existing documentation.

This feels like an exaggeration to me. There's no rewriting going on, as files are converted automatically with Pandoc, with just a few minutes spent per file to review the conversion results. With a dozen or two files left, it will take orders of magnitude less time to convert them than to implement RST support and keep maintaining it in all of the related tools, including DocC.

[al45tair]

There's no rewriting going on, as files are converted automatically with Pandoc, with just a few minutes spent per file to review the conversion results.

Ah, it hadn't occurred to me that you were using Pandoc, though that does make sense. However I'm still of the opinion that it'd be a much better idea for DocC to support RST in addition to Markdown.

[AnthonyLatsis]

@MaxDesiatov The PR that closed this issue states "Partially resolves ...". Did you really mean to close it, or perhaps forgot to use reverse word order?