Define and document the directory structure

[dmj]

The naming convention should follow current TEI practice, which is that major directories get capitalized and minor ones are all lowercase.

I can see the following major directories:

Documentation

Contains all of the program's documentation.

Stylesheets

Contains the transformation stylesheets and function libraries.

Schemas

Contains all of the schema files.

Tests

Contains XSpec tests (subdirectory xspec) and test cases (subdirectory resources).

[martindholmes]

I think I'd prefer XSLT to Stylesheets, to avoid confusion with any CSS that we might end up having. But otherwise I think it's right.

[sydb]

We will also need a Source/ directory to hold p5.xml (or p5subset.xml) and perhaps 1 or 2 other soure ODDs defining non-TEI languages. (I am presuming test ODD customizations go in atop/Tests/resources/.)

And I mildly prefer XSLT/ to Stylesheets/, more to avoid confusion with Stylesheets-the-repo than to avoid confusion with CSS, because I doubt we will have much CSS.

But that said, where does the ant driver go? (If it goes in the XSLT/ directory maybe it should be named something else? Or are we OK having 1 our 2 build.xml kinda files in there?)

[martindholmes]

I'm inclined to put the ant driver in the root, then it never has to climb the tree to find resources.

[sydb]

I thought ants were really good at climbing trees … 🤣 Seriously, root level is fine with me, so long as we don’t end up with a lot of different build files and other stuff in there.

[dmj]

And I mildly prefer XSLT/ to Stylesheets/, more to avoid confusion with Stylesheets-the-repo than to avoid confusion with CSS, because I doubt we will have much CSS.

Fine by me.

We will also need a Source/ directory to hold p5.xml (or p5subset.xml) and perhaps 1 or 2 other soure ODDs defining non-TEI languages.

Why would we need a p5subset.xml in a local directory? If we put a copy of a current p5subset into the Source/ directory, then we need to worry about keeping it up-to-date.

[sydb]

Why would we need a p5subset.xml in a local directory? If we put a copy of a current p5subset into the Source/ directory, then we need to worry about keeping it up-to-date.

True enough. But if we do not have a local copy, then we need to a) agree on which version to take, and b) either have a local copy of that version in the expected place, or require a (good) net connection to run atop so the agreed upon version can be retrieved from the web.

[martindholmes]

Re p5subset: the situation we've ended up with in the current Stylesheets repo is messy, but it's the only workable one given the existing tests in that repo. If we are clever enough in creating our tests, we should be able to avoid the situation where changes to p5subset (due to changes in the TEI repo) suddenly cause our tests to fail. But I would suggest that we leave aside the issue of p5subset for now, and get our initial processed-odd-to-RNG transformation working; then we can focus on the earlier processing, and we'll have some solid experience of how to write robust tests when we come to look at it.

[sydb]

Indeed. I was not expecting that we would have to fill the Source/ (or whatever) directory yet.

[martindholmes]

Git won't track an empty directory anyway, so this is moot until we decide what to put in it. :-)

[sydb]

Oh, good point. Completely forgot that, even though it bit me on the arse earlier today! Sigh.

[dmj]

Updated the PR #2.

But I would suggest that we leave aside the issue of p5subset for now, and get our initial processed-odd-to-RNG transformation working; then we can focus on the earlier processing, and we'll have some solid experience of how to write robust tests when we come to look at it.

+1