Split out sections into separate TeX files for better editing

[davidlmobley]

Since the community is welcome to edit/propose changes to the paper, I perhaps should split out the major sections into separate TeX files to make it easier to deal with multiple changes at once without editing clashes.

On the other hand, maybe this will make it harder since people will have to figure out which file they need to edit.

[slochower]

I came across another repository with some really good tooling that uses CI to automatically build an HTML and PDF copy of their manuscript on each commit (https://github.com/greenelab/deep-review). There's a lot there, but I forked their scripts and made some modifications that I have running on one of my projects. I think this could be useful for something like this repository and manuscript.

I know you're at Beyond Kds now, so I won't go into the details, but if you're interested when you get back, feel free to ping me.

[davidlmobley]

I actually saw that on Twitter and was thinking, "boy, I should really do that here too"; I'm glad you posted the link though because I only thought of it after I lost the link. Ha.

A the same time this could also ensure no one makes it so the TeX won't compile.

I'm still of mixed feelings about the issue you commented on here (splitting into separate tex files). Any thoughts?

A couple of people in your lab are going to get involved with adding some stuff here -- specifically @GHeinzelmann and @nhenriksen so they may be interested in weighing in.

[slochower]

A the same time this could also ensure no one makes it so the TeX won't compile.

I think that's probably a good idea if you want to expand to the point that people who you don't know or are less familiar with TeX will be contributing. The deep-review respository have a system setup so a PR that won't compile won't get merged into master. However, they have made the choice to write in Markdown and go straight to HTML from PDF from there. I don't think it would be too much more difficult to use TeX/LaTeX as a starting point, although I think Markdown is probably more accessible to a wider audience.

I'm still of mixed feelings about the issue you commented on here (splitting into separate tex files). Any thoughts?

I also think this is probably a good idea out of simplicity. Ideally, this could be done painlessly by using \input{} or \include{}. For deep-review, they number their sections (e.g., 01-intro.md or whatever) and the compilation just concatenates the files with increasing number order.

[mabraham]

Splitting into different files doesn't really help with merge conflicts, except that you break the merging work into logical chunks. Two people making heavy edits to a methods section are going to clash, whether it's in a separate file or not.

So split it into files if it will help people find what they want to read or write, but I think it's not about merging

[slochower]

Two people making heavy edits to a methods section are going to clash, whether it's in a separate file or not.

I agree, unless there are separate methods sections for different sections, in which case, you reduce the probability of merge conflicts as the number of files increases, right? In the limit that each little bit has its own file, merge conflicts should go down because the chance that multiple people are working on the same little bit is small, I think.

However, I have no idea if merge conflicts are actually a big deal in this repository.

[mabraham]

For GROMACS, we use a CMake package https://cmake.org/Wiki/CMakeUserUseLATEX so that users and CI can build our PDF reference manual to whatever format is wanted. (But the docs are slowly moving to Sphinx anyway.) But not helpful unless there's existing CMake brain share!

[slochower]

For GROMACS, we use a CMake package https://cmake.org/Wiki/CMakeUserUseLATEX so that users and CI can build our PDF reference manual to whatever format is wanted. (But the docs are slowly moving to Sphinx anyway.) But not helpful unless there's existing CMake brain share!

Neat! I personally don't have any knowledge of CMake.

[mabraham]

I agree, unless there are separate methods sections for different sections, in which case, you reduce the probability of merge conflicts as the number of files increases, right? In the limit that each little bit has its own file, merge conflicts should go down because the chance that multiple people are working on the same little bit is small, I think.

Either the edits are on the same or adjacent line, or they aren't. What file they are in doesn't make much of a difference, excepting in chunking the merge effort.

[davidlmobley]

Either the edits are on the same or adjacent line, or they aren't. What file they are in doesn't make much of a difference, excepting in chunking the merge effort.

Thanks for this point. I wasn't super up on how git handles these edits when I wrote this issue originally and now I have a clearer picture. What I find is that GitHub's edit tracking can get messed up even if edits are NOT on the same or adjacent lines, but this seems not to apply to git itself. So, I think there really should be no reason to split into separate files.

I think it actually will be easier for people to find what to edit (at least at this point) if it's all just one file since they can then just search for what they want to edit. Eventually, if it grows enough, I could see splitting it into chapters or something similar.

[mabraham]

Sounds fair. I don't have much experience of what GitHub does with such things.