search

rpgtex / DND-5e-LaTeX-Template

LaTeX package to typeset material for the fifth edition of the "world's greatest roleplaying game".
MIT License
1.45k stars 312 forks source link

Publish package to CTAN #283

Open porlk opened 4 years ago

porlk commented 4 years ago

Would you consider publishing these package and class to CTAN? It would greatly simplify installation and widen the audience.

ravenclaw900 commented 4 years ago

Personally, I like the idea, and I don't see any negatives. We could publish it and update it every time a new release comes out (like 0.8.0 just did). I'll get to work on the .dtx (probably using example.pdf as a base) and .ins files, but @BrianCriswell should be the one that makes the final decision.

EDIT: On issue https://github.com/rpgtex/DND-5e-LaTeX-Template/issues/116#issuecomment-516907757, it is suggested that we wait until 0.9 or 1.0. I'm still going to do the files just in case, but we might have to wait another 1 or 2 releases.

BrianCriswell commented 4 years ago

Yeah, I just don't think we are quite there yet with 0.8, but it might work with .9. I would want to make sure everything is very robust and the interface is finalized before publishing to CTAN.

My understanding is that converting over to .dtx is going to require a fairly substantial rewrite of the internals (which could introduce bugs).

ravenclaw900 commented 4 years ago

I'm already working on the .dtx files, if there are bugs I'll catch them in 0.8 for future reference. However, I don't think there will be, as dtx is just (basically) all the files combined into 1 (with various tags showing which is which.

BrianCriswell commented 4 years ago

Okay, I have made a dtx feature branch for you to do the development against. https://github.com/rpgtex/DND-5e-LaTeX-Template/tree/dtx

ravenclaw900 commented 4 years ago

Oh, great! Right now I was doing it in a separate repository (you can look at what I have already there). Do you mind if I remove the unnecessary files from the branch (e.g. only keeping the code files, image files, and the license)?

BrianCriswell commented 4 years ago

Depends on what you want to remove. What is unnecessary?

You may want to look at this package as a starting point. https://ctan.org/pkg/sty2dtx?lang=en

ravenclaw900 commented 4 years ago

In my opinion, since the dtx file will probably just be used for installing, the CODE-OF-CONDUCT, (if you like, we could keep this, but it wouldn't be included in the file), CONTRIBUTING (same as CODE-OF-CONDUCT) img/Makefile, img/README, img/src/, Makefile, scrot.jpg, and maybe (but possibly not), all the CI files (obviously, those wouldn't be included either). Also, move all the "needed" files (dnd.sty, dndbook.cls, dndcore.def, dndoptions.clo, example.tex, /lib, /img) into a src folder, maybe.

BrianCriswell commented 4 years ago

Maybe I am conflating what would be available in CTAN with what would be on GitHub.

My understanding is that the .dtx files only includes what is needed to use the package. In that case, aside from maybe the LICENSE and README, the only other stuff that would be included would be what is needed to use the package. Everything else would not be included but would still be available on GitHub.

Are we saying the same thing?

ravenclaw900 commented 4 years ago

Yes, we would keep some of the files just on GitHub. The installer would be a .zip file containing a .dtx, an .ins, a LICENSE, a README, an empty /lib and /lib/languages directory, and an /img directory containing paper.jpg paper-low-res.jpg, and footerscroll.pdf.

ravenclaw900 commented 4 years ago

I've opened a PR to show what I'd keep and delete.

BrianCriswell commented 4 years ago

So, looking at #284, I am fine with moving the source code to a /src folder. There are a few things that still need to work.

These kinds of things need to be maintained in the PR while it is being developed or have a really good reason to change how we work with the project going forward.

ravenclaw900 commented 4 years ago

Are we talking about only the dtx branch, or master as well?

ravenclaw900 commented 4 years ago

I was thinking, specifically for the dtx branch,

I can't think of anything else for the dtx branch.

BrianCriswell commented 4 years ago

Every PR has to be fully working. After a feature branch like dtx is "finished", it is merged into another branch (such as develop). This is why they must have the minimum of changes needed to accomplish their goal, because any changes made are brought into the "main" branch. Removing the "unnecessary" files would have caused those files to be deleted when the dtx branch was merged into develop.

Some development environments (such as VS Code with the LaTeX Workshop extension) automatically build the PDF when you save a file. To preserve this working when doing development on the class files, so I am wondering if maybe example.tex should be moved to the /src folder as well. Following how The LaTeX Project organizes things might not be a bad idea. https://github.com/latex3/latex3

I think the following needs to happen at minimum for a conversion to .dtx to be successful.

  1. Easy for someone to still use the class with a minimum of effort. If they download it from this site, how do they use it?
  2. Easy for a developer to test changes to the class. Someone should be able to make a change, build, and test it without having to go through a bunch of manual steps.
  3. CI still has to work.

It is possible that some sort of scripting might be necessary to ease 1 and 2, and the test script likely needs to change for 3 to work. For scripting to be viable, it needs to work for Windows, Linux, Mac, Overleaf, etc. If that is not really an option, the installation task needs to be simple and repeatable for 2 to work.

This might also be a good time to switch from CircleCI to Github Actions. https://help.github.com/en/actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions

All of this does not have to be done in one PR. We can make multiple PRs against dtx with each PR doing one thing. Let's get one thing right at a time. Once everything is done, I will initiate a PR from dtx to develop.

ravenclaw900 commented 4 years ago

In response to 2 on your list, I've created a GitHub Actions script to convert all files in a /src directory into a dtx file (without documentation). https://gist.github.com/ravenclaw900/256b1037a1f2d872165fdbea18aa0d97. What do you think? I'll try to upgrade that so it makes an ins file as well, though that could probably be done by hand.

EDIT: Yes, I was planning to move example.pdf to a /src directory. It would probably be included in the dtx file too, as a semi-documentation to show the class.

ravenclaw900 commented 4 years ago

In response to 1 on your list, docstrip has a directories feature that auto-installs into the directory of your choosing. I'll see if I can get it to install into TEXMFHOME.

SirSoi commented 2 years ago

@ravenclaw900 @BrianCriswell Any news?

BrianCriswell commented 2 years ago

No, CTAN is a relatively low priority compared to some fixes the package needs. There have been some pressing concerns over the last two years that have limited the time I wanted to devote to this.