Closed drphilmarshall closed 7 years ago
What I did was a hack. I think what we need to do is decide what we are actually willing to support.
Yes. One thing about overleaf is that it breaks the model of a Project having a GitHub repo that then hosts multiple Notes and papers - Overleaf requires one git repo per Note/paper. You can use submodule, but I don't think that captures the source code into the project repo, so things stay scattered. Development on overleaf also means that the GitHub PR code review function can't be used to help with WG review. Neither of these may be a problem: the Pub policy/board puts more stock in the capture of PDFs than latex source, and other ways of collecting review comments can be used
We should also clarify a few technical details.
Does Overleaf use the Makefile? I assume not, and that it instead uses the latexmkrc file, which isn't in the usual start_paper repo. We could add it, of course. But this also means that (unsurprisingly), Overleaf won't/can't do things like getting and running mkauthlist, or updating desc-tex.
Is there any way to take advantage of having git under the hood, other than cloning the repository? That provides a way to deal with mkauthlist and desc-tex (the usual way), but seems like it defeats the purpose by making the job of the paper maintainer that much more complex.
@kadrlica , in what sense is your paper a hack, apart from what's noted above?
I think those were the main "hack" items.
I was thinking that some notes on how to get a DESC paper into overleaf, and then how to edit it once there (including git workflow, using mkauthlist outside of overleaf, etc), might suffice. Does it make sense to have start_paper provide the latexmkrc file?
I don't think there is any (obvious) harm in adding latexmkrc
to start_paper
(I just ran out of time during my hack). One option to integrate with Overleaf would be to have the Makefile
run latexmk
in the same way that Overleaf does using the latexmkrc
.
I agree. latexmk
will automatically use this file if it's there, and after a little hacking, it's possible to have it use a docswitch flag specified by the Makefile when called that way, and a default (changed by editing latekmkrc
) otherwise. I'll push this to reduced_fat
.
@drphilmarshall , the minimal overhead for using Overleaf would end up being either
desc-tex
, push this back up, write paper, pull finished paper down and run make update
and mkauthlist
, push back up (presumably).desc-tex
files and mkauthlist
output to the Overleaf repo, updating as necessary.Both kind of a pain, but easy enough to document?
Overleaf could be used as an automated, up-to-date pdf viewer. I remember that the github paper flow had the problem that you needed to either check in the PDF or build it automatically with travis, etc.
Just realized that part my workflow above doesn't make sense, given that people will need to get start_paper
before they can import those files in Overleaf. So we need the instructions to include running make desc-tex
before uploading everything to Overleaf, but there needn't be an additional clone+push associated with this.
Right: I think the advice is to get set up locally with start_paper first, then go make an empty Overleaf project that you can push to. When you start an overleaf project it gives you a main.tex file - what's the cleanest way to replace this with the start_paper one, along with everything else?
Outrageously, it looks like Overleaf won't upload whole folders at a time, let alone recursively. The best option might be to clone an empty Overleaf project, extract start_paper
over it (which will probably fail with the current deployment script...) and push back up. Do you know a smarter way, @kadrlica ?
I wasn't aware of any constraints on uploading folders, but I have always just pushed things with git. (I do know that Overleaf doesn't support git tags in the normal way). Overleaf has it's own documentation for importing existing projects: https://www.overleaf.com/help/230-how-do-i-push-a-new-project-to-overleaf-via-git#.WXaoxtPyvOQ
To play devil's advocate for a moment, are we sure that we aren't over-designing things here? I don't know what discussions have taken place inside the PubBoard, but at the end of the day, I think that all we really need to provide is:
With these independent "tools" and associated documentation, someone should be able to write a paper without needing a wrapper like start_paper
.
I agree, but I also think that we now have a perfectly functional start_paper
, apart from documentation. We don't necessarily need to figure out how to do everything with Overleaf ourselves, but we should distill what we know currently.
Agreed. See my review of #61 for some more overleaf experience!
Alex @kadrlica got a DESC Note up and compiled in Overleaf at the Stony Brook Hack Day, so now we just need to document that in the README and/or the start_paper Note.