निरंजन
I am writing a package which consists of smaller modules. I want tips for the organization and maintenance of such a project. For the time being let's call it the bundle `foo` and assume that it has two sub-modules called `bar` and `baz`. My idea is if someone uses `\usepackage{foo}`, both `foo-bar` and `foo-baz` should be loaded, but if in case someone wants to use only `foo-baz`, `\usepackage{foo-baz}` should also be a valid command. All of these will have a combined documentation. I have thought of having a `foo.dtx`, `foo.ins` `foo-bar.dtx` and `foo-baz.dtx`. I was thinking to have the code for `foo-bar` and `foo-baz` in their respective dtx-es and simply have `\usepackage{foo-bar,foo-baz}` as the code of `foo`. Is there a better way to achieve this? Where should the documentation of all of these go?
Top Answer
Skillmon
I think it all boils down to taste.
A few examples:
- My `MRTbundle` doesn't use any dtxes (and hence doesn't have the (very small) performance gain by removing unnecessary comments). Another example for this is Ti*k*Z/`pgf` a really big project, a really big and exhaustive manual, no dtx in sight.
- You can create a project that builds single files from multiple dtxes (code modules that still belong to the same package; the LaTeX format is for instance build from multiple dtxes).
- You can create a project that builds multiple files from a single dtx (`ducksay` does this).
- You can build a project that has the documented source code in dtxes, but the user documentation in another file (`expkv-bundle` or `siunitx`).
It all comes down to what you find maintaining the easiest, and most suitable for your project. Since I have experience in almost all of these variants I can safely say: For me none of these has a clear edge over the others. In some projects I find the one-file approach favourable, in others I like the approach with a split out documentation. I think the bigger and diverse the project is, the more I favour the separate files for narrow purposes approach. I even considered splitting up `expkv.dtx` in separated files for the different parts of it (but have since abandoned this idea for the easier to script package-dtx-correspondance).
So things you should consider in the decision (from my personal point of view):
- how much scripting do you want to do in which language? (this affects file structure quite a lot, I think)
- how big do you estimate the project to become and how diverse are the modules?
- how exhaustive do you intend to build the documentation? (the more examples, the more documentation-specific auxiliary macro packages, the better a split up approach, imho)
**But overall: Do what you find easiest to maintain for yourself!** And if a project today is split up into single files with no dtx, and in a project tomorrow you decide to pack as much as possible into a single dtx, then that's a fascinating journey worth experiencing. None of us did everything as efficiently as possible from the very beginning. You have to find out what works for yourself, especially in decisions in which there is no objective right or wrong!