Use a .cfg file team-specific l3doc settings

[josephwright]

Currently some of l3doc is very much specific to the team. Ideally, that would be split out into a .cfg file. Probably any move in this direction will need two copies of the file

• One in l3kernel, so it can go to CTAN
• One in support, so that it is accessible to l3packages/l3experimental

Alternatively, some way of having the file appear once and be used in several modules will need to be worked out. That may lead to an l3build issue.

[josephwright]

I'm self-assigning as the issue is as much the build set up as the .cfg file. Input on what should go into it is most welcome!

[wspr]

I should have kept #412 open :)

If we put the .cfg file on CTAN it needs to go under doc/ so that it's not picked up by 3rd party users. I'm not sure why we need two copies? Isn't l3kernel a dependency of l3packages/l3experimental? Oh, I see that they are not.

Maybe this is another reason to move l3doc into its own location, so that it can be a dependency on the others!

[FrankMittelbach]

I don't like that idea. In my opinion a config file should ony config something it should not be required to run something. If we put code out of l3doc that we need run ourkernel sources it should not be in the cfg and that in some special directory. that would mean you can only run the doc with either the cfg copied or in a special directory which I think is counterproductive.

[josephwright]

It occurs to me @wspr is right: a stand-alone .cfg in l3kernel would work fine across the board. (The issue before was having a .cfg extracted from the .dtx: that is more tricky to support). @FrankMittelbach I'm not sure if that affects your view.

[FrankMittelbach]

@FrankMittelbach <https://github.com/frankmittelbach> I'm not sure if that affects your view.

let me say it this way: if there is a cfg that is part of the standard distribs like l3doc itself and that is automatically included in a kernel dtx regardless where I process it then that is fine. however if that cfg has a special name and thus is loaded basically via input then this is not much different to distributing the code as a separate package, so that kind of goes away from the idea of a config. but I'm okay with this if you think that prevents others from also using the config when we aren't really ready to support that.

[blefloch]

prevents others from also using the config when we aren't really ready to support that.

This is not about not being ready to support something, it's that we need \newcommand's that are shared across l3kernel modules, and other customizations (the current "kernel" option of l3doc), rather than duplicating the code in every single file. I would prefer simply having a .tex (or .sty but people might start using it) file with these commands. The .tex can probably go in l3kernel, but I'm not sure.

[FrankMittelbach]

Am 06.12.2017 um 15:39 schrieb Bruno Le Floch:

> prevents others from also using > the config when we aren't really ready to support that. This is not about not being ready to support something, it's that we

I probably wasn't clear enough. It is about parts of l3doc that are only for the kernel document and we wouldn't be ready to support the code if used by others (as we may change it etc). Otherwise why not document it and say here it is.

need \newcommand's that are shared across l3kernel modules, and other customizations (the current "kernel" option of l3doc), rather than duplicating the code in every single file.

I understand all that. All I was asking is that this code is not ending up hidden in say /doc because then it only works within l3build but not if I take a dtx elsewhere and try to run it. Also I was saying this extra code for us and the kernel sources is not so much a "config" (which may be useful anyhow for others) but extra code for the kernel documentation.

I would prefer simply having a .tex (or .sty but people might start using it) file with these commands. The .tex can probably go in l3kernel, but I'm not sure.

So yes, I am absolutely fine with a l3kernel-doc-support.tex somewhere where it is automatically installed with the rest of the kernel files in a distribution and have that explicitly loaded via \input in each .dtx file

[wspr]

I'm happy with the idea of a .tex file installed wherever l3doc is. (I guess (?) it shouldn't contain ‘l3kernel’ since we want to use it for l3packages and so on.)

[josephwright]

@wspr l3doc-latex3.tex?

[wspr]

@josephwright I guess so... Or l3doc-latex3-support.tex or l3doc-latex3-preamble.tex to make it a bit more obvious that it's just a preamble thing?

[FrankMittelbach]

Am 06.12.2017 um 21:38 schrieb Joseph Wright:

@wspr <https://github.com/wspr> |l3doc-latex3.tex|?

l3doc-l3team.tex or l3doc-l3teamextras.tex

[FrankMittelbach]

or l3doc-l3team-preamble.tex % like Will's preamble idea