Splitting spec.md into more modular files

[debs-sifive]

Since spec.md is nearing 3k lines, are there any thoughts on splitting it into different files (based on sections or something)?

I think it's kind of difficult to do in Markdown... Has there also been any consideration to moving to AsciiDoc? Or whatever else is popular these days for docs.

I think splitting up spec.md would be beneficial for organizational purposes and ease of writing!

Moving to a different format (like AsciiDoc) might also allow for easier parsing (e.g. people can read directly off the GitHub without needing to build a PDF).

[seldridge]

I'm not terribly against splitting this up, though I actually prefer it as one file for the purposes of easier searching when editing locally. If we want to do this, pandoc does support multiple markdown file inputs as well as we can always just cat a bunch of files together.

I'm not in favor of moving off of Markdown + pandoc unless there's a pretty compelling use case that provides good differentiation over the current workflow.

AsciiDoc was suggested as an alternative when I was working on the split. However, a goal was to continue to support PDF output and I was initially attempting to keep things as close to the original spec format. Pandoc has benefits in that you can do a lot of customization of the output LaTeX (there is some of this here: https://github.com/chipsalliance/firrtl-spec/blob/main/include/spec-template.tex).

Note: I think the GitHub reading is actually pretty okay right now other than the images? (See: https://github.com/chipsalliance/firrtl-spec/blob/main/spec.md) This is usually almost always the case so long as we don't start doing inline LaTeX (which basically breaks any potential ability to convert to other formats and is a bad idea).

[debs-sifive]

Gotcha. I think GitHub also doesn't handle the jump-to-section links, but those can be searched by the reader.