Split BR.md into sections

[jsha]

BR.md seems to be large enough that GitHub's rich diff generator takes close to 5 seconds, which is their internal timeout per discussions with GitHub Support. That means viewing the rich diff sometimes produces a timeout, for example at https://github.com/cabforum/documents/pull/24/files.

It sounds like GitHub won't change the timeout, and the code is not open source so we don't have the option of optimizing it.

I'd like to split up BR.md into multiple files, one per section, and recombine them at build time. That will probably make the rich diff generator finish safely below the timeout.

Any objections? @pzb?

[pzb]

Sounds good to me. However we need to figure out how to handle in-progress ballots; several branches will need re-doing.

[sleevi]

My experiences in W3C and IETF suggest that, while understandably well-motivated, such actions generally make the document significantly harder to manage and keep consistent @jsha . Further, I think that's the sort of change that might be better discussed in the Forum at large as part of workflow.

It seems like you're making more work for people who want to contribute. Is there a way to avoid that?

[jsha]

Good point about making it harder to contribute: People would need to find the correct section to edit. I'm definitely interested in finding alternate approaches that make it possible to continue to read rich diffs (which many Forum members find useful) while also using a single doc. If there's a third-party tool to generate rich diffs, we could run it automatically from Travis and link to it from pull requests.

Will cross-post on cabfpub, thanks for the reminder.

[sleevi]

@jsha Wanting to circle back on this, now that some of the infrastructure is landing / has landed.

Where we currently stand is:

• Some of the documents rely on Pandoc-flavored-markdown / Pandoc extensions to get a good universal format, that don't render well in GitHub-Flavored Markdown
  • There is a Pandoc -> GFM converter, but haven't run our docs through this
• We've tentatively got redline support (once I land Add support for generating redline diffs build-guidelines-action#1 and get integrated), which offers a rich PDF redline, at least.
  • I'm sad this is not HTML like the GitHub diff is, but I do hope perhaps over the holidays some progress will be made on an HTML render
• The tooling right now doesn't use Pandoc's multi-markdown input (where it concats files together before converting), so this would require some tooling updates
  • However, it does support validating cross-references

I'm curious how you feel about continuing this? I'm mixed, and can see pros and cons, but curious to get the current thinking.

[jsha]

It sounds like the redline support in cabforum/build-guidelines-action#1 is a good alternate. I'm happy to go with that and drop the idea of splitting into sections.

[ryancdickson]

@barrini - Seems like this issue can be closed.