search

fsharp / fslang-spec

F# Language Specification
MIT License
21 stars 1 forks source link

Infrastructure (build script etc) #3

Closed Martin521 closed 5 months ago

Martin521 commented 6 months ago

This PR should be reviewed and merged first. Separate PRs will follow for the chapters of the spec. This PR contains the project infrastructure (build script etc) and the preface page of the spec (spec/front-matter.md).

vzarytovskii commented 6 months ago

Curious why custom scripts and not something like mdBook and/or pandoc? Former can also help in publishing it as versioned interactive "website" with search and all. Latter might help producing custom formats (pdf, djvu, tex, doc(x), you name it).

Martin521 commented 6 months ago

Curious why custom scripts and not something like mdBook and/or pandoc? Former can also help in publishing it as versioned interactive "website" with search and all. Latter might help producing custom formats (pdf, djvu, tex, doc(x), you name it).

The F# spec contains more than 250 cross-references like "see §15.1". The main function of the build script is to keep these cross-references working in both development (where we have a collection of markdown chapters) and in the complete doc (markdown or html derived from it), even if chapters are added or removed. I took the idea and format from the C# spec/standard. For the original F# spec, MS Word handled this. As far as I can tell, neither mdBook nor pandoc provide this functionality. Next to handling the cross-references, the build script also provides the most basic mdBook functionality (namely combining the chapters and providing a ToC).

Going forward I see the following options.

  1. Move to mdBook (or something similar). This probably means we have to cast the chapters and sections in stone and make the cross-references fixed. (It seems the Rust book avoids cross-references. The few I found are fixed, like here.) On the positive side, we would get all the formatting options and other goodies that mdBook provides, including simple web publishing with hot reload.
  2. Keep the build script, limit ourselves in formatting (focus on the content for now), use something like pandoc to create html or pdf in discrete releases.
  3. Possibly use the build script as a preprocessor to handle the cross-references and create mdBook sources (the SUMMARY.md and the pre-processed chapters). We could do that when the need arises.