|
1 | | -This repo contains basic examples of Ximera constructs that can be used as |
2 | | -* demo |
3 | | -* tests |
| 1 | +This Repo contains the master testbed for Ximera development. |
| 2 | +It also contains minimal examples and syntax for the Ximera commands, environments, etc. |
| 3 | +However, for a much in-depth treatment of Ximera commands, environments, etc you should |
| 4 | +refer to the Ximera manual, which explains things in more detail and in a more user friendly way. |
| 5 | + |
| 6 | +# General Structure and Intent of this Repo |
| 7 | + |
| 8 | +* **This Repo (will eventually be) structured as follows...** |
| 9 | + |
| 10 | +- depreciated (for content that is being removed in a future release, see README in folder) |
| 11 | + - (DTXFileName)Test.tex files (e.g. problemTest.tex) |
| 12 | +- testFiles |
| 13 | + -compositeTestFiles (for tests of interactions between different dtx file contents, see README in folder.) |
| 14 | + -subfolder named to explain composite testing case. |
| 15 | + -dtxTestFiles (for individual dtx file testbeds, see README in folder.) |
| 16 | + - (Command/Env) folder; a folder for each testable command/enviroment/etc. (e.g. ''problem'' folder) |
| 17 | + - base.tex file (basic usage implementation/info) |
| 18 | + - (Additional Testing Feature).tex (e.g. nesting.tex or numbering.tex in the problem folder) |
| 19 | +- testXourses (xourse files to lode relevant test files, see README in folder) |
| 20 | + - compositeTestXourses (xourses for testing interactions between different dtx files) |
| 21 | + - dtxTestXourses (xourses for testing individual dtx file contents) |
| 22 | + - (dtxFileName)Test.tex is the xourse that tests (dtxFileName) dtx file. |
| 23 | + - Includes hard coded non-tested content so it is easy to verify all non-depreciated dtx has been parsed. |
| 24 | + |
| 25 | +* **testFiles Folder at a glance** |
| 26 | +The testFiles folder is the folder that contains all the actual test ximera document class files |
| 27 | +that are loaded and used for demo/testing. There are two subfolders in this folder. |
| 28 | +1) The dtxTestFiles are the files that test individual dtx files to verify the integrity of all |
| 29 | +the elements within that specific dtx file. |
| 30 | +2) The compositeTestFiles subfolder is for files that test the integrity of elements that span |
| 31 | +and/or interact between different dtx files. |
| 32 | + |
| 33 | +* **testXourses Folder at a glance** |
| 34 | +The testXourses is the location of all the xourse files. There are two subfolders; |
| 35 | +1) The first subfolder is the dtxTestXourses subfolder. It is a subfolder for xourses that are |
| 36 | +tests for each of the dtx files, these xourses should load all the relevant test files to verify |
| 37 | +the functionality of all the elements that are touched by that dtx file. |
| 38 | +2) The other subfolder is the compositeTestXourses folder, which are xourses that load all the relevant |
| 39 | +tests to verify the integrity of how elements in different dtx files interact with each other. These |
| 40 | +should load each of the relevant test files in the corresponding compositeTestFiles subfolder |
| 41 | +of the testFiles folder. |
| 42 | + |
| 43 | +<!-- |
| 44 | +* **testGroupings Folder at a glance** |
| 45 | +Finally, the testGroupings folder should contain a list of folders that represent ''types'' of |
| 46 | +content that may need to be verified or tested - e.g. ''environments'', ''answerables'' or ''authorship tools''. |
| 47 | +More folders may be added here as we determine elements that are commonly needed to test together/in tandem. |
| 48 | +Note that the intent here, is that the same test file may be referenced in multiple (many!) of these subfolders... |
| 49 | +since something like the ``\answer`` command is likely to show up under a lot of different categories of areas |
| 50 | +that might need testing (e.g. ''student interactions'', ''page credit generating elements'', and |
| 51 | +''javascript elements'' would all have the ``\answer`` command as a relevant test). |
| 52 | +
|
| 53 | +* **Important Note About Test Groupings** |
| 54 | +To ensure all tests stay up to date in the relevant testGroupings (and to avoid version mismatch and general confusion) |
| 55 | +the files inside the testGroups should only be xourses that load the test files from the testFiles folder, not new |
| 56 | +test files. To submit a new test file, see the section on ``Creating a New Test File``. --> |
| 57 | + |
| 58 | + |
| 59 | +# Naming Schemes |
| 60 | + |
| 61 | +* **Each test xourse in the testXourses/dtxTestXourses is named after a dtx file.** |
| 62 | +Since all development work must be implemented via dtx file (as per CTAN standards) and most development work |
| 63 | +tends to involve only a few dtx files (usually just one or two), it is often easiest to test the new code by testing |
| 64 | +everything that is implemented by the newly changed dtx code. This testing bed makes that easy to accomplish by merely |
| 65 | +pulling up the relevant dtxTestXourse(s) and loading thetest bed xourse(s) that correspond to your changed dtx file. |
| 66 | +These in turn load all the relevant testFiles that correspond to the individual elements implemented by that dtx file |
| 67 | +i.e. each command/environment (or reasonably obvious groupings, like all ``\newtheorem`` generated environments are |
| 68 | +in the same place) has its own testing tile, making it relatively easy to investigate updated content, even inside a given dtx. |
| 69 | +Thus **Each dtxTestXourse should be named (dtxFileName)Test.tex** e.g. ''abstractTest.tex'' for the ''abstract.dtx'' file. |
| 70 | + |
| 71 | +* **Each tested command/env/etc has a file in the relevant (subfolder) of the dtxTestFiles Folder** |
| 72 | +Each command/environment/etc (referred to as ``element``) that is implemented in a dtx should have its own testFile |
| 73 | +in that dtxTestFiles subfolder, named after the relevant element. This should demo/test the most basic form of the |
| 74 | +element. |
| 75 | +However, often there are a number of options, or other elements for whatever is being tested that also need a demo/test. |
| 76 | +We don't want to have a single test file that contains all the various complexities of these things, |
| 77 | +as it becomes difficult to see what aspect ended up generating issues (if there are issues from testing). |
| 78 | +Thus test files should have the ''base.tex'' file that is the minimal implementation of the tested item, and then various |
| 79 | +other files that demo/test the other relevant aspects, each named after whatever it tests (e.g. ''numbering'' or ''nesting'' |
| 80 | +for demo/testing the numbering scheme and nesting behavior inside the problem subfolder in the testFiles folder.). |
| 81 | + |
| 82 | +* **When Preambles are Necessary** |
| 83 | +Some specific test files/xourses need to load specific options or alternative files as part of their |
| 84 | +testing (e.g. the graphics testing file needs to input graphics, and set graphics paths in the preamble). When this is |
| 85 | +necessary, **do note use the xmpreamble** for the test repo - instead you should make a preamble with the relevant test |
| 86 | +file (or xourse as appropriate) name, appended with ''preamble'' - e.g. ''imagePreamble.tex'' is the preamble file |
| 87 | +for the image.tex test file. |
| 88 | +Similarly, some specific elements have (intended) different behavior depending on server source (e.g. UF, OSU, KL, etc). |
| 89 | +In this case, you should add another test file with the intended behavior specific to the server source, and append the |
| 90 | +server name/code to the test file. For example, if OSU has intended behavior that differs from ximera base for hints, |
| 91 | +then there should be a ''hintsOSU'' or possibly a ''hintsBaseOSU'' as appropriate. |
| 92 | + |
| 93 | +* **Example of Intended Naming Scheme:** |
| 94 | +To demonstrate the intended naming scheme, consider the problem-like environments. The thing being tested is the ''problem'' |
| 95 | +environment, so all tests go into a ''problem'' folder inside the testFiles folder. We need the base case that |
| 96 | +demo/tests the very bare implementation of the problem like environments - but it also requires a test for how problem |
| 97 | +numbering is handled, and a test for how nesting problems is handled. Thus there should be three test files inside the problem |
| 98 | +subfolder of the testFiles folder; problemBase.tex, problemNesting.tex, and problemNumbering.tex. |
| 99 | +each is a ximera documentclass that is demoing/testing the basic implementation, nesting behavior, |
| 100 | +and numbering scheme respectivvely. These are in turn loaded by the |
| 101 | +''problemTest.tex'' file, which is the xourse documentclass that loads the content generated in the problem.dtx file. |
| 102 | +So just the ''problem'' related files would be in the structure as follows: |
| 103 | +- testXourses |
| 104 | + - problemTest.tex |
| 105 | +- testFiles |
| 106 | + - problem |
| 107 | + - base.tex file (basic usage implementation/info) |
| 108 | + - nesting.tex (demo/test for nesting behavior) |
| 109 | + - numbering.tex (demo/test for numbering scheme) |
| 110 | + |
| 111 | +# Creating a New Test File |
| 112 | +If you have determined a meaningful test case that has no appropriate test file, you can do the following; |
| 113 | +1) You should post the issue on the github issues tab of the example repo (**NOT** the ximeraLatex repo!) with |
| 114 | +a detailed explanation of what you need to test - make sure to highlight exactly the things that need to be |
| 115 | +tested that are not currently testable using the existing test files. In other words, make sure to include: |
| 116 | + - What is currently not able to be tested using existing test files. |
| 117 | + - What specifically you are trying to test overall (in the case that the part that is `untestable` is |
| 118 | + only a piece of what you are trying to test overall). |
| 119 | + - Why you are trying to test and/or what you are trying to change about Ximera that needs testing. |
| 120 | +2) Next - if you are able, you should make a branch of the main examples repo, and write your new test file. |
| 121 | +Once you have the new test file written (and tested) and think it is ready to be merged, submit a pull request |
| 122 | +with an explanation of what and how you are going about testing the thing you are submitting a new file for, |
| 123 | +along with a reference to the github issue in the examples repo that you submitted from part 1. This will |
| 124 | +allow another developer to quickly and easily review the file for submission and then merge it. |
| 125 | + - As a general rule, a different developer (than the author of the new file) should review/merge |
| 126 | + a new test file for safety. |
| 127 | + - New test files should be verified to make sure they are necessary, suitably succinct in their testing, |
| 128 | + and conform to the various naming and design requirements listed in this readme. |
| 129 | + - Once the merge has been completed, whomever reviewed the test file and merged the new test file into |
| 130 | + the master test repo *must* be the one to close the github issue. This will help with quickly referencing |
| 131 | + who did what if there are any issues later on or if someone needs to verify something (helps minimize |
| 132 | + digging through the commit history). |
| 133 | + |
| 134 | +# Non-Testable dtx Files Explained |
| 135 | + |
| 136 | +Each dtx file should have its own test xourse that loads the relevant test files. However, pending a reorganization |
| 137 | +of dtx files and their content, there are currently many dtx files that do not contain any testable commands or environments |
| 138 | +(for example, the banner.dtx file is just the ascii definition of the banner that displays in the console on page load). |
| 139 | +Nonetheless it is important to know that a given dtx file has been parsed and any necessary content have relevant test files. |
| 140 | +So we still make test files for non-testable dtx files (e.g. BannerTest.tex) but place that file in a special top-level folder |
| 141 | +called ''untestedDTX'' which contains two different types of non-tested files. There are depreciated dtx files - those dtx |
| 142 | +files whose contents will be removed in an upcoming ximera version and so tests aren't needed (these are separated into |
| 143 | +a 'depreciated' folder inside the untestedDTX folder) as well as the dtx files that do not contain anything that can/need |
| 144 | +be tested (like the banner.dtx) - test files for these are put in the ''hardCoded'' subfolder of the untestedDTX folder. |
| 145 | + |
| 146 | + |
| 147 | +# Public Publishing Locations |
| 148 | + |
| 149 | +Content from this repo is published publically for others to see, and link to. This is mostly as a quick-ref demo resource |
| 150 | +for authors, but can be used by anyone - it is publically available after all. You can find these servers here: |
4 | 151 |
|
5 | | -The main branch is published |
6 | 152 | * at [KU Leuven](https://set-p-dsb-zomercursus-latest.cloud-ext.icts.kuleuven.be/ximeraexamples/coreXimeraFeatures/environments/theoremEnvironments). |
7 | 153 | * at [OSU](https://ximera.osu.edu/ximeraexamples). |
8 | 154 |
|
9 | 155 | Note you can always get the TeX-code by appending .tex to the URL of an activity. |
10 | 156 |
|
11 | 157 |
|
12 | | -A more detailed description of how to use this repo for testing is in the [README_testing](README_testing.md) |
| 158 | +<!-- A more detailed description of how to use this repo for testing is in the [README_testing](README_testing.md) --> |
| 159 | + |
| 160 | +# Notes from talking with Wim |
| 161 | + |
| 162 | +1) Make a ``global testing files`` type subfolder in the testFiles folder for test files that are designed |
| 163 | +to test more global interactions - not things that are contianed within a single dtx file. |
| 164 | +For example, the label/ref interactions with certain environments like theorems or problems; or |
| 165 | +complicated ToC implementation with nesting sections/subsections and chapterstyle/sectionstyle commands. |
| 166 | + |
| 167 | + |
| 168 | + |
13 | 169 |
|
0 commit comments