From dbaccd7fa7bd5e543dd2d158d7ecab14e0401479 Mon Sep 17 00:00:00 2001 From: doomuch <80600884+doomuch@users.noreply.github.com> Date: Tue, 18 Jun 2024 14:25:31 +0200 Subject: [PATCH 1/2] Update README.md --- README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 84 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2bddc6b..0d0c048 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,96 @@ More documentation coming soon! Things are changing too quickly right now. -For development, run `go run cmd/server/main.go` to start the server, which by default listens on `127.0.0.1:5080`. Check out the [example configuration file](https://github.com/readium/go-toolkit/blob/master/cmd/server/configs/config.local.toml.example) for configuration options. +## Running the server + +Run `go run cmd/server/main.go` to start the server, which by default listens on `127.0.0.1:5080`. + +The server exposes the following HTTP endpoints: + +- `/list.json` - Returns a list of available publications +- `/{filename}/manifest.json` - Returns the Web Publication Manifest for the specified publication +- `/{filename}/{asset}` - Returns a publication asset (e.g. chapters, images, etc.) + +### Accessing a publication + +1. Get the list of publications: + +``` +GET http://127.0.0.1:5080/list.json +``` + +This returns a JSON array of available publications: + +```json +[ + {"filename":"publication1", "path":"cHVibGljYXRpb24x"}, + {"filename":"publication2", "path":"cHVibGljYXRpb24y"} +] +``` + +2. Access the manifest for a publication: + +``` +GET http://127.0.0.1:5080/{path}/manifest.json +``` + +Where `{path}` is the base64 URL encoded filename of the publication. + +3. Access assets for the publication: + +``` +GET http://127.0.0.1:5080/{path}/{asset} +``` + +Where `{asset}` is the path of the asset within the publication. These paths can be discovered from the manifest. + +### Configuration + +Check out the [example configuration file](https://github.com/readium/go-toolkit/blob/master/cmd/server/configs/config.local.toml.example) for configuration options: + +```toml +# Example of a local env config file, useful for development +env-name = "local" +sentry-dsn = "https://deadbeef@sentry.tld" +cache-dsn = "local://not-yet-determined-scheme" +origins = ["example.com", "localhost", "127.0.0.1"] +log-level = "debug" +bind-address = "localhost" +bind-port = "15080" +publication-path = "./publications" +static-path = "./public" +``` + +- `bind-address` - The network interface to bind the server to +- `bind-port` - The port number to run the server on +- `origins` - Allowed CORS origins +- `publication-path` - Directory containing publication files to serve +- `static-path` - Directory containing static assets for the server +- `sentry-dsn` - Sentry error reporting DSN +- `cache-dsn` - Connection string for caching (not yet implemented) ## Command line utility -The `rwp` command provides utilities to parse and generate Web Publications. +The `rwp` command provides utilities to parse and generate Web Publications. To install `rwp` in `~/go/bin`, run `make install`. Use `make build` to build the binary in the current directory. ### Generating a Readium Web Publication Manifest -The `rwp manifest` command will parse a publication file (such as EPUB, PDF, audiobook, etc.) and build a Readium Web Publication Manifest for it. The JSON manifest is -printed to stdout. +The `rwp manifest` command will parse a publication file (such as EPUB, PDF, audiobook, etc.) and build a Readium Web Publication Manifest for it. The JSON manifest is printed to stdout. Examples: * Print out a compact JSON RWPM. ```sh - rwp manifest publication.epub + rwp manifest publication.epub ``` + * Pretty-print a JSON RWPM using two-space indent. ```sh rwp manifest --indent " " publication.epub ``` + * Extract the publication title with `jq`. ```sh rwp manifest publication.epub | jq -r .metadata.title @@ -36,7 +103,7 @@ Examples: | Option | Description | |------------------|--------------------------------------------------------------------------------------------------------| -| `no` (*default*) | No accessibility metadata will be inferred. | +| `no` (_default_) | No accessibility metadata will be inferred. | | `merged` | Accessibility metadata will be inferred and merged with the authored ones in `metadata.accessibility`. | | `split` | Accessibility metadata will be inferred but stored separately in `metadata.inferredAccessibility`. | @@ -46,18 +113,18 @@ rwp manifest --infer-a11y=merged publication.epub | jq .metadata ##### Inferred metadata -| Key | Value | Inferred? | -|-----|-------|-----------| -| `accessMode` | `auditory` | If the publication contains a reference to an audio or video resource (inspect `resources` and `readingOrder` in RWPM) | -| `accessMode` | `visual` | If the publications contains a reference to an image or a video resource (inspect `resources` and `readingOrder` in RWPM) | -| `accessModeSufficient` | `textual` | If the publication is partially or fully accessible (WCAG A or above)
Or if the publication does not contain any image, audio or video resource (inspect "resources" and "readingOrder" in RWPM)
Or if the only image available can be identified as a cover | -| `feature` | `displayTransformability` | If the publication is fully accessible (WCAG AA or above)
:warning: This property should only be inferred for reflowable EPUB files as it doesn't apply to other formats (FXL, PDF, audiobooks, CBZ/CBR). | -| `feature` | `printPageNumbers` | If the publications contains a page list (check for the presence of a `pageList` collection in RWPM) | -| `feature` | `tableOfContents` | If the publications contains a table of contents (check for the presence of a `toc` collection in RWPM) | -| `feature` | `MathML` | If the publication contains any resource with MathML (check for the presence of the `contains` property where the value is `mathml` in `readingOrder` or `resources` in RWPM) | -| `feature` | `synchronizedAudioText` | If the publication contains any reference to Media Overlays (TBD in RWPM) | +| Key | Value | Inferred? | +|------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `accessMode` | `auditory` | If the publication contains a reference to an audio or video resource (inspect `resources` and `readingOrder` in RWPM) | +| `accessMode` | `visual` | If the publications contains a reference to an image or a video resource (inspect `resources` and `readingOrder` in RWPM) | +| `accessModeSufficient` | `textual` | If the publication is partially or fully accessible (WCAG A or above)
Or if the publication does not contain any image, audio or video resource (inspect "resources" and "readingOrder" in RWPM)
Or if the only image available can be identified as a cover | +| `feature` | `displayTransformability` | If the publication is fully accessible (WCAG AA or above)
:warning: This property should only be inferred for reflowable EPUB files as it doesn't apply to other formats (FXL, PDF, audiobooks, CBZ/CBR). | +| `feature` | `printPageNumbers` | If the publications contains a page list (check for the presence of a `pageList` collection in RWPM) | +| `feature` | `tableOfContents` | If the publications contains a table of contents (check for the presence of a `toc` collection in RWPM) | +| `feature` | `MathML` | If the publication contains any resource with MathML (check for the presence of the `contains` property where the value is `mathml` in `readingOrder` or `resources` in RWPM) | +| `feature` | `synchronizedAudioText` | If the publication contains any reference to Media Overlays (TBD in RWPM) | ### HTTP streaming of local publications `rwp serve` starts an HTTP server that serves EPUB, CBZ and other compatible formats from a given directory. -A log is printed to stdout. \ No newline at end of file +A log is printed to stdout. See the above section on "Running the server" for details on the HTTP API. From 5e6512c4f1efca881e3a06c839c59a861609f159 Mon Sep 17 00:00:00 2001 From: doomuch <80600884+doomuch@users.noreply.github.com> Date: Tue, 18 Jun 2024 14:33:56 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 0d0c048..38d52fb 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,12 @@ More documentation coming soon! Things are changing too quickly right now. Run `go run cmd/server/main.go` to start the server, which by default listens on `127.0.0.1:5080`. +Note: The example configuration file specifies `./publications` as the `publication-path`, but the actual test publications are located in the `test` directory in the project repository. To run the server, you will need to either create a `publications` directory and place your own publication files there, or update the `publication-path` setting in the config file to point to the `test` directory. + The server exposes the following HTTP endpoints: - `/list.json` - Returns a list of available publications -- `/{filename}/manifest.json` - Returns the Web Publication Manifest for the specified publication +- `/{filename}/manifest.json` - Returns the Web Publication Manifest for the specified publication - `/{filename}/{asset}` - Returns a publication asset (e.g. chapters, images, etc.) ### Accessing a publication @@ -17,14 +19,14 @@ The server exposes the following HTTP endpoints: 1. Get the list of publications: ``` -GET http://127.0.0.1:5080/list.json +GET http://127.0.0.1:5080/list.json ``` This returns a JSON array of available publications: ```json [ - {"filename":"publication1", "path":"cHVibGljYXRpb24x"}, + {"filename":"publication1", "path":"cHVibGljYXRpb24x"}, {"filename":"publication2", "path":"cHVibGljYXRpb24y"} ] ``` @@ -32,7 +34,7 @@ This returns a JSON array of available publications: 2. Access the manifest for a publication: ``` -GET http://127.0.0.1:5080/{path}/manifest.json +GET http://127.0.0.1:5080/{path}/manifest.json ``` Where `{path}` is the base64 URL encoded filename of the publication. @@ -41,34 +43,35 @@ Where `{path}` is the base64 URL encoded filename of the publication. ``` GET http://127.0.0.1:5080/{path}/{asset} -``` +``` Where `{asset}` is the path of the asset within the publication. These paths can be discovered from the manifest. -### Configuration +### Configuration Check out the [example configuration file](https://github.com/readium/go-toolkit/blob/master/cmd/server/configs/config.local.toml.example) for configuration options: ```toml # Example of a local env config file, useful for development env-name = "local" -sentry-dsn = "https://deadbeef@sentry.tld" -cache-dsn = "local://not-yet-determined-scheme" -origins = ["example.com", "localhost", "127.0.0.1"] +sentry-dsn = "https://deadbeef@sentry.tld" +cache-dsn = "local://not-yet-determined-scheme" +origins = ["example.com", "localhost", "127.0.0.1"] log-level = "debug" -bind-address = "localhost" +bind-address = "localhost" bind-port = "15080" -publication-path = "./publications" +publication-path = "./publications" # Update this to "./test" to use the test publications static-path = "./public" ``` -- `bind-address` - The network interface to bind the server to -- `bind-port` - The port number to run the server on -- `origins` - Allowed CORS origins -- `publication-path` - Directory containing publication files to serve +- `bind-address` - The network interface to bind the server to +- `bind-port` - The port number to run the server on +- `origins` - Allowed CORS origins +- `publication-path` - Directory containing publication files to serve - `static-path` - Directory containing static assets for the server - `sentry-dsn` - Sentry error reporting DSN -- `cache-dsn` - Connection string for caching (not yet implemented) +- `cache-dsn` - Connection string for caching (not yet implemented) + ## Command line utility