search

LSSTDESC / start_paper

Make a folder containing everything you need to start writing an LSST DESC paper or Note
BSD 3-Clause "New" or "Revised" License
11 stars 4 forks source link

Support use of Overleaf #60

Closed drphilmarshall closed 7 years ago

drphilmarshall commented 7 years ago

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.

kadrlica commented 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.

drphilmarshall commented 7 years ago

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

abmantz commented 7 years ago

We should also clarify a few technical details.

  1. 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.

  2. 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?

kadrlica commented 7 years ago

I think those were the main "hack" items.

drphilmarshall commented 7 years ago

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?

kadrlica commented 7 years ago

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.

abmantz commented 7 years ago

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

  1. Clone the Overleaf repo, use make to get desc-tex, push this back up, write paper, pull finished paper down and run make update and mkauthlist, push back up (presumably).
  2. Manually add desc-tex files and mkauthlist output to the Overleaf repo, updating as necessary.

Both kind of a pain, but easy enough to document?

kadrlica commented 7 years ago

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.

abmantz commented 7 years ago

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.

drphilmarshall commented 7 years ago

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?

abmantz commented 7 years ago

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 ?

kadrlica commented 7 years ago

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:

  1. A DESC note tex template (DONE)
  2. A set of standard acknowledgements
  3. A tool to parse long author lists (DONE)
  4. A set of guidelines for collaborative paper writing

With these independent "tools" and associated documentation, someone should be able to write a paper without needing a wrapper like start_paper.

abmantz commented 7 years ago

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.

drphilmarshall commented 7 years ago

Agreed. See my review of #61 for some more overleaf experience!