Publish package to CTAN

[porlk]

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

[ravenclaw900]

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 #116 (comment), 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]

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]

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]

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]

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]

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]

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]

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]

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]

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

[BrianCriswell]

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.

• CI needs to still be able to build the project successfully.
• A user needs to be able to download the master branch and start developing without having to jump through a lot of hoops.
• Testing changes needs to be simple. Right now I pull PRs and build the example.tex file to test them.
• Maybe some other use cases I can't think of off the top of my head. . .

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]

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

[ravenclaw900]

I was thinking, specifically for the dtx branch,

• Move (copy?) the needed (and needed for the dtx only) code to a src folder

• If we move, edit the path of example.tex in Makefile (or maybe just change the command in config.yml to pdflatex example.tex) (again, only in the dtx branch).

• Add my previous files from ravenclaw900/DND-LaTeX-Template-DTX into the dtx branch.

• Also, edit README in the master branch to show the dtx file as an installation option and package it with the releases.

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

[BrianCriswell]

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]

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]

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]

@ravenclaw900 @BrianCriswell Any news?

[BrianCriswell]

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.