Convert the specs to Markdown?

[auduchinok]

It would be much easier to contribute to the spec and review changes if it had a more collaboration-friendly format.

[voronoipotato]

I agree. Is there any objection from the board for making the specs in a more accessible format? If we want to keep the existing specs in Word perhaps we could use a tool like pandoc to generate markdown?

@ReedCopsey

[ReedCopsey]

This is a question for @dsyme - I think the only objection in the past was the rather large/tedious chore of verifying that the conversion is clean. Somebody would need to very carefully check the results and hand edit/correct it to make sure it's very correct.

[voronoipotato]

Sounds like a good rainy sunday project.

[dsyme]

I would be very happy to see this done. I think it would take 3-4 sundays

My main concern is about subscripts, italics, index, glossary etc.

[voronoipotato]

https://gist.github.com/voronoipotato/e423697fb159a4d28daeaad5ef392bfd

Things mostly look okay. I used this naive command to convert to GitHub flavored markdown.

pandoc .\FSharpSpec-4.1-latest.docx -f docx -t gfm -s -o FSharpSpec-4.1-latest-github.md

Features	✔️ / ❌ / ❓
Tables	✔️
Subscripts	✔️
Coloring for code	❌
Whitespace in code	❌
Bold	❓
Italics	✔️
Glossary	✔️
Index	❓
Table of Contents	✔️

Tables came out nicely. The coloring is completely lost in my current brains not included approach in a way that causes some problems. You'll notice there will be a smattering of ** ** around the document that isn't in the original. I think this is caused by the way bold is done so there may need to be a tweak or two to this command. Sub-scripting appears to be working fine, and uses <sub>. Index is technically there but isn't pretty. I put a ✔️ here if it appears at a glance to be working, a ❌ if it appears not to be working, and a ❓ if it looks like it may not take much work to get it working.

[voronoipotato]

https://gist.github.com/voronoipotato/402dc3015efeeef0512d950aacd89f39

Using

pandoc .\FSharpSpec-4.1-latest.docx -f docx+styles -t gfm -s -o FSharpSpec-4.1-latest-styled.md

This allows us to encode the styles in the md for later styling as "custom styles". This appears to fix most but not all of the bolding issues and opens the door for using css to style our code samples. It does not yet fix the whitespace issues which appear to be partially the culprit for the ** **, and I do suspect that may be fixed with yet another flag.

[voronoipotato]

I think an important prerequisite issue is fixing the style rot. There are for example, at least 3 different spellings of normal :) . These things happen with large files but it's going to make parsing it harder if we don't.

[bbatsov]

I'm a bit late to the party and I'm wondering if this conversion effort is worth it, if there are no language spec documents being prepared (generated?). I guessing these days it's quite unlikely that anyone will be in need of the F# 4.0 language specification.

[dsyme]

There's actually a WIP repo for this here : https://github.com/fsharp/fslang-spec/

The 4.0 spec itself has been converted and some RFCs started

I think the work is good and can be continued

[bbatsov]

@dsyme No argument from me! I wasn't aware of the new repository, so let me suggest to following:

• Make it easier to find it by mentioning it on fsharp.org (e.g. https://fsharp.org/specs/language-spec/) I'd probably mention it at several places, just because I think something like it is quite important and should be very easy to find. (that would also drive more potential contributors in that direction)
• Moving all language-spec issues there (GitHub allows moving tickets between repos in the same org)