Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/w3c/epub-structural-tests


https://github.com/w3c/epub-structural-tests

digital-publishing epub epub-wg publishing

Last synced: 23 days ago
JSON representation

Awesome Lists containing this project

README 

        
# Harvest epubcheck for the EPUB 3.3. CR report



Tool to combine the information extracted from the test feature files of epubcheck with the EPUB 3.3 specification, and to produce a test report that lists the available tests and their relationships to the specification. The tool itself is a script written in TypeScript, based on a standard node.js environment.



## Workflow



The tool does two things for each HTML files of the EPUB 3.3 specifications (i.e., the core `index.html` file as well as the vocabulary specification files):



- It produces a separate file in the `docs/fragments` directory. The final report itself (in `docs/index.html`) combines these fragment files to produce a comprehensive set of tables on the tests. [T.B.D.: whether this file should be moved to another repository, or whether it can be directly picked up by the final reports.]

- It modifies the specification file by adding the references to the tests in the relevant sections. This is done by adding the `data-tests` attributes (or expanding an existing one, if applicable) with the references to the test suite (see the [respec documentation](https://respec.org/docs/) for the details).



    The modified HTML files are stored in the `epub33/core`, resp. `epub33/core/vocab`, directory. _These files must be manually moved back into the specification repository by, e.g., copying them in a local clone and the defining a Pull Request. The tool does **not** do that automatically._



The input data for the tool is `epubcheck_data/tests.json`, which contains the test descriptions as extracted from the epubcheck test suite.



### Installing and running the tool



The repository must be cloned to a local machine and the standard `npm install` should be run. To execute the script run



```

ts-node src/main.ts

```



from the top directory or, alternatively, run



```

npm run generate

```



anywhere in the repository.



By default, the tool reads the content of the specifications' HTML files by accessing them directly on github. The tool can also be run with two more options:



- `-d` or `--download`: the original (i.e., unchanged) specification files are _also_ stored locally in the `epub33-orig` directory. 

- `-l` or `--local`: instead of accessing github, the tool uses the specification files in the `epub33-orig` directory.



## Directory content



- `epub33/core`: the generated specification files, with all the modifications done/updated.

- `epub33-orig/core`: a copy of the original specification files.

- `epub-33/common`: is a copy of the original files in the EPUB repository (necessary to visualize the files). In particular, it also contains (a modified version of) `epub33/common/js/data-test-displays.js` that makes some necessary modifications on the files generated by respec to show the test references correctly.

- `epubcheck-data`: files, and necessary scripts, containing the descriptions of the epubcheck tests suite entries.

- `docs`: the final report

- `src`: the TypeScript code itself



The rest of the files (`package.json`, `LICENSE`, etc, are self-evident).



@iherman