fsharp
Convert the specs to Markdown?
It would be much easier to contribute to the spec and review changes if it had a more collaboration-friendly format.
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
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.
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.
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.
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.
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.