use desc-tex

[abmantz]

I suggest that the Note style files and the global bibliography (at least) should logically exist independently of start_paper. They can easily be included and kept up to date in git-versioned projects (including this one) using git submodule, which is less arcane than the make approach.

[drphilmarshall]

I like the idea of the DESC style file and bibliography existing outside ofstart_paper - @kadrlica and I talked about this when we were getting started, and ended up doing things this way because it was the simplest way to get someone started writing a paper. As well as stripping out the style and bib files from start_paper, we'd also need to provide instructions for how to run this alternative two-step process (cookiecutter followed by some advanced gittery, it sounds like). An alternative approach could be to find a better way to get people started than cookiecutter, that enabled a one-step start-up as well as a more transparent and dynamic way of providing style files and templates.

[abmantz]

The git submodule command to checkout these things could be handled by the Makefile, I think. E.g., if the bibliography repo is called desc_bib, the Makefile would say

desc_bib:
    git submodule add git@github.com:LSSTDESCdesc_bib.git

(or it could check whether cwd is a git repository, and git clone instead if not). This would make it a 1-step process, or pretty close. There seems to be some sophisticated functionality for automstically syncing submodules, but the beautiful thing is that it isn't necessary. In this example, if you just cd desc_bib, then for all intents and purposes you are in a desc_bib clone and can pull/branch/whatever as normal.

To your second point, fwiw, I'm not a fan of cookiecutter, or any procedure whose first instruction is pip install somethingyouhaveneverusedbeforeandwillneveruseagain. Maybe I'm just old.

[drphilmarshall]

And getting older all the time! :-) It sounds like the necessary style and class files should live in their own LSSTDESC/texmf repo, then, and that any paper/project repo and start_paper should grab them from there, via git submodule. Maybe you could demo this approach in some repo somewhere, putting the setup instructions in a README? We can then follow suit here.

[abmantz]

I think we can reasonably demo the use case in the DESC Style_Guide repo.

Any thoughts on how granular to make this? The start_paper texmf folder includes three logically distinct things, to my mind

1. journal-supporting classes, bibstys, etc
2. DESC Note style and graphics (logos)
3. DESC macros

The first two we can expect to be updated rarely, while the third we want people to feel comfortable suggesting additions to. Keeping it in a separate repo would lower the bar (if only because it would be the only file, not buried 2 directories deep).

To these, we can add the apocryphal DESC bibliography, which is a good idea and something that the Pub Board should probably take responsibility for, unless you have a better idea.

[kadrlica]

Should probably also think about adding DESC standard acknowledgments.

[abmantz]

Interesting point. I'm tempted to suggest distributing them alongside the macros, but it depends where the ultimate home of the standard acknowledgements is. We wouldn't want acknowledgements distributed in one of these repos going out of date because an update to the official version didn't get copied over. (If the official home is our repo, then great, but it's also been suggested that they be posted on a public website.)

[drphilmarshall]

Thanks for laying out the logical distinction, Adam. I am a fan of one-stop shops, so what if we hid the style and class files in a folder called texmf, but kept the bib file and acknowledgments in the top level? The whole lot could then be kept in a single repo, named so that everyone's "paper" folder looked sensible. "desctex"? That would lead to latex commands like:

\references{desctex/lsstdesc,my_references}

which would call desctex/lsstdesc.bib and so on.

I think the desctex repo should be public, and I don't think it matters if it contains bib and ackn files as well as sty and cls, but PubMan @sethdigel should confirm. It'd be nice if "posting on a public website" could just be providing the link to the desctex repo.

[abmantz]

I see your point. I was worried about our non-git-savvy colleagues being intimidated by the apparent complexity of the repo they need to clone to get the DESC macros, but that's perhaps silly. In any case, we can provide direct links to the current macro and bib files for those who want nothing to do with GitHub.

So, in your scheme, desctex would consist of the current start_paper/texmf material, plus the bib file. I would also like to hear from @sethdigel, but assuming he approves then any one of us could in principle copy the contents of texmf over into a new desctex repo.

[kadrlica]

Do we care about retaining the revision history of the files when we do the copy. It would be nice to have if it isn't too complicated to do.

[abmantz]

As far as I know​, the only way to keep the history would be to create desctex as a fork of start_paper, and then delete everything we don't want to keep. Which is a fine solution, I suppose, as long as you're ok with the history of all those deleted files hanging around also.

[drphilmarshall]

That's an easy route, and fine by me. I would do the fork manually, though, so as not to show the link between the repos on GitHub (that could lead to unwanted giant merges). Better to make a fresh clone of start_paper locally, rename it and clean out everything we don't want, then push to an empty desctex repo on GitHub.

On Wed, Jun 14, 2017 at 9:36 PM, Adam Mantz notifications@github.com wrote:

As far as I know​, the only way to keep the history would be to create desctex as a fork of start_paper, and then delete everything we don't want to keep. Which is a fine solution, I suppose, as long as you're ok with the history of all those deleted files hanging around also.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/LSSTDESC/start_paper/issues/58#issuecomment-308626359, or mute the thread https://github.com/notifications/unsubscribe-auth/AArY9whIo2M4xgW2FWz90QhGoLe1qI3Iks5sELTggaJpZM4Nn6js .

[abmantz]

I'll have to take your word for it that the history is retained in that case.

[kadrlica]

Some instructions here: https://help.github.com/articles/duplicating-a-repository/

[abmantz]

Awesomesauce.

[sethdigel]

Sorry to have been slow on the uptake here.

I think the desctex repo should be public, and I don't think it matters if it contains bib and ackn files as well as sty and cls, but PubMan @sethdigel should confirm. It'd be nice if "posting on a public website" could just be providing the link to the desctex repo.

This seems fine to me. The 'posting on a public Web site' idea is that the DESC Web site should contain some kind of acknowledgment to the agencies and institutions supporting DESC. Someone suggested that could be a copy of the acknowledgments that we use for papers. I'm happy to factor that entirely out of this discussion about start_paper. For DESC people it is fine with me if we keep the standard acknowledgments in a GitHub repository.

The draft DESC Standard Acknowledgments are themselves kind of a template, following the prescription in the Publication Policy about the various things that need to be acknowledged. I'd like to make it as easy as possible for people to get it right the first time, but I am not sure what the best way would be, in a desctex sense. We also have slightly different versions for Standard and Key papers; e.g., the Key papers will not have contribution statements or acknowledgements to individual grants. And at least notionally, we have a short form of the standard acknowledgments, for use in Letters. This is something that we needed in Fermi LAT, where the word count in the acknowledgments counts against the total, but may be hard to make foolproof in a start_paper sense.

Regarding the concept of a DESC bibtex file; yes, I think we should have one maintained by the Pub Board. I suspect that at least for DESC papers we can write a script to generate one from ADS. I don't have any good ideas about how to add in non-DESC papers. Maybe we shouldn't try.

[abmantz]

Ok, I've done the fancy mirror/clone of the repository. The new home of the contents of texmf/ and lsstdesc.bib is https://github.com/LSSTDESC/desc-tex . Let's continue any relevant discussion in the issues there.

[abmantz]

The desctex branch of the DESC Style Guide now demos the use of submodule. The desc-tex submodule is already checked in here, as I assume would be the case in start_paper. What that means is that git knows that this external repo is part of the project, but new clones of the project (Style_Guide or start_paper) wouldn't have a full-blown clone of desc-tex included, just an empty directory. (Unless clone is called with --recursive, but that's complicated.)

My suggestion to get around this is to make desc-tex/.git one of the default targets of the Makefile, as in Style_Guide, or a prerequisite for compiling tex (smarter). The rule for making this target is the appropriate git command, git submodule update --init. (Note that this pulls the last version of the submodule that was checked into the superproject, not necessarily the current version. To actually update it, I think you would just want to cd desc-tex && git pull. It would make sense for start_paper to do this when initializing the submodule.)

[kadrlica]

We also have make update if we want to be explicit about updating the submodule. I think this is better than changing it out from under people when they compile.

[abmantz]

Yes, indeed. I meant that it could automatically update when it's cloned the first time.

[drphilmarshall]

Thanks, Adam! Alex, might you have some time to try this out in a branch? You can have cookiecutter use that branch just by modifying the command.

[kadrlica]

Is everything already implemented in the Makefile, or is there development to do in addition to testing?

[drphilmarshall]

I think we need to remove the texmf folder from start_paper, and switch to using desctex. Not sure how best to import desctex, I guess the Makefile could do it? The README etc will need updating too.

[abmantz]

I'm slightly confused about which Makefile you guys are referring to. If you mean the implementation in Style_Guide, I have tested it. (Note that this is not in the master branch yet...) I think you just need to

1. git rm lsstdesc.bib texmf/
2. git submodule add git@github.com:LSSTDESC/desc-tex.git
3. Change some paths in your other code (texmf becomes desc-tex and the bib file is no longer in ./, but otherwise I don't think anything has moved).

Btw, @kadrlica, can you see the Style Guide? I'm not sure whether these things are readable by DESC members or whether I need to add "Members" as a collaborating team.

Reiterating some of the above, new clones of start_paper won't have desc-tex by default (unless cloned with --recursive, which is a pain to remember), but they will have an empty desc-tex/ folder. So you'd want your Makefile to include something like

default: desc-tex/.git <other things>
desc-tex/.git:
    git submodule update --init

This way, the very first thing make will do is clone desc-tex. Your update target would just need to cd desc-tex && git pull.

And, as Phil points out, the documentation for both start_paper and desc-tex need to be updated. If you can help with the latter, I'd appreciate it (even if just a description of what's there).

Make sense? I can find time to help with the start_paper conversion if forced to.

[drphilmarshall]

Thanks Adam - this is indeed what I meant by the Makefile doing the desc-tex import.

[kadrlica]

Now it's my turn to be confused. Because of the cookiecutter setup, I don't think we actually clone the start_paper repo (at least not in the conventional way). I just followed the instructions and ran:

cookiecutter https://github.com/DarkEnergyScienceCollaboration/start_paper.git

and then went into the resulting desc-0000-projectname-paper_title directory, but there is no .git directory there. This is born out in how we do make update which is by directly downloading for the github url (see here).

@drphilmarshall you are probably our cookiecutter expert (and main proponent). Any ideas about how to implement @abmantz's suggestion?

@abmantz I cannot access the Style Guide.

[abmantz]

I've just added you to Style-Guide as a collaborator.

I'd forgotten that cookiecutter doesn't leave you with a working git repository. That makes things a little more complex. For one thing, you'd really want the user to set up a new git repo immediately after cookiecutting, if they plan on doing so at all. Then, the Makefile could run the right command to get desc-tex based on whether or not ./.git exists. If it does, then the submodule command above is the right thing to do. If not, you'd have it clone desc-tex in the standard way.

Alternatively, if you aren't married to cookiecutter, the mirror/clone procedure we used to create desc-tex from start_paper can be automated easily enough. We'd need another (make-based?) way of collecting/using the metadata that cookiecutter gets.

[kadrlica]

I'm not a strong proponent of cookiecutter, but @drphilmarshall should comment. Maybe he can also say whether cookiecutter can implement the --recursive option during the initial clone.

[abmantz]

The README now has instructions on how to get/add desc-tex in various circumstances, in case anything above isn't clear.

[drphilmarshall]

Thanks, Adam. Cookiecutter just makes a folder, its up to you to check it in wherever you want it. For this reason, we should add desc-tex to the .gitignore that cookiecutter makes for you, and then I guess having the Makefile clone desc-tex makes the most sense (in case you are not ready to check in your paper/Note folder yet).

[abmantz]

Actually, it looks like I was wrong above - turning a start_paper project into a git repository after desc-tex has been cloned inside it wouldn't necessarily cause any problems. (git submodule add is smart enough to recognize that the submodule is already present, and just registers it.) Your solution is appealingly simple in terms of what goes in the Makefile, though. It seems like a good place to start, although I'd be inclined to use make to achieve maximum elegance in the long term.

[abmantz]

Thanks for assigning me! Could I have write access then?

[kadrlica]

@drphilmarshall drives this ship. Maybe he can add you (though I bet he'll tell you to fork and submit a PR...).

[drphilmarshall]

I think Write access in exchange for being willing to be assigned issues is a fair deal :-) @abmantz is now on the @LSSTDESC/paper_starters team! Thanks, Adam :-)

[kadrlica]

I'm not sure how I want to respond to that... if I am not granted write access does that mean that I won't be assigned any more issues?

[drphilmarshall]

I believe one can only be assigned issues in a repo if one has Write access to it... so until now, Adam could not receive any assignments. We've been using the assign button to suggest who does what on this project: if we're all happy to re-assign as needed, we could carry on like this. An alternative would be to only ever self-assign issues, while making suggestions about who could best do what in the comments. Which approach do you each prefer?

[kadrlica]

It doesn't matter to me. My previous comment was definitely intended to be tongue-in-cheek.

[drphilmarshall]

:-) I thought it might be, but I wasn't sure!