Skip to content

Commit 170029e

Browse files
Buried-In-CodeBuried-In-Code
committed
Update README
1 parent abaf66a commit 170029e

1 file changed

Lines changed: 207 additions & 91 deletions

File tree

‎README.md‎

Lines changed: 207 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -13,81 +13,108 @@
1313
[![Testing](https://github.com/Buried-In-Code/Perdoo/actions/workflows/testing.yaml/badge.svg)](https://github.com/Buried-In-Code/Perdoo/actions/workflows/testing.yaml)
1414
[![Publishing](https://github.com/Buried-In-Code/Perdoo/actions/workflows/publishing.yaml/badge.svg)](https://github.com/Buried-In-Code/Perdoo/actions/workflows/publishing.yaml)
1515

16-
Perdoo is designed to assist in sorting and organizing your comic collection by utilizing metadata files stored within comic archives.
17-
Perdoo standardizes all your digital comics into a unified format (cbz).
18-
It adds and/or updates metadata files using supported services.
19-
Unlike other tagging tools, Perdoo employs a manual approach when metadata files are absent, prompting users to enter the necessary Publisher/Series/Issue details for search purposes.
16+
Perdoo helps organize comic collections using metadata stored within comic archives.
17+
18+
It standardizes digital comics into a consistent format (CBZ) and can add or update metadata using supported services.
19+
20+
Unlike fully automated tagging tools, Perdoo takes a manual approach when metadata is unavailable. When necessary, it prompts for Publisher, Series, and Issue details that can be used to search supported metadata services.
2021

2122
## Installation
2223

2324
### Pipx
2425

25-
1. Ensure you have [Pipx](https://pipx.pypa.io/stable/) installed: `pipx --version`
26-
2. Install the project: `pipx install perdoo`
26+
1. Ensure [Pipx](https://pipx.pypa.io/stable/) is installed:
27+
28+
```console
29+
pipx --version
30+
```
31+
32+
2. Install Perdoo:
33+
34+
```console
35+
pipx install perdoo
36+
```
2737

2838
## Usage
2939

30-
<details><summary>perdoo Commands</summary>
40+
<details>
41+
<summary><code>perdoo</code> commands</summary>
3142

3243
![perdoo help](docs/img/perdoo.svg)
3344

34-
</details>
35-
<details><summary>perdoo archive Commands</summary>
45+
<details>
46+
<summary><code>perdoo archive</code> commands</summary>
3647

3748
![perdoo archive help](docs/img/perdoo_archive.svg)
3849

39-
</details>
40-
<details><summary>perdoo archive comic-info</summary>
50+
<details>
51+
<summary><code>perdoo archive comic-info</code></summary>
4152

4253
![perdoo archive comic-info help](docs/img/perdoo_archive_comic-info.svg)
4354

4455
</details>
45-
<details><summary>perdoo archive metron-info</summary>
56+
57+
<details>
58+
<summary><code>perdoo archive metron-info</code></summary>
4659

4760
![perdoo archive metron-info help](docs/img/perdoo_archive_metron-info.svg)
4861

4962
</details>
50-
<details><summary>perdoo clean</summary>
63+
64+
</details>
65+
66+
<details>
67+
<summary><code>perdoo clean</code></summary>
5168

5269
![perdoo clean help](docs/img/perdoo_clean.svg)
5370

5471
</details>
55-
<details><summary>perdoo convert</summary>
72+
73+
<details>
74+
<summary><code>perdoo convert</code></summary>
5675

5776
![perdoo convert help](docs/img/perdoo_convert.svg)
5877

5978
</details>
60-
<details><summary>perdoo rename</summary>
79+
80+
<details>
81+
<summary><code>perdoo rename</code></summary>
6182

6283
![perdoo rename help](docs/img/perdoo_rename.svg)
6384

6485
</details>
65-
<details><summary>perdoo settings</summary>
86+
87+
<details>
88+
<summary><code>perdoo settings</code></summary>
6689

6790
![perdoo settings help](docs/img/perdoo_settings.svg)
6891

6992
</details>
70-
<details><summary>perdoo sync</summary>
93+
94+
<details>
95+
<summary><code>perdoo sync</code></summary>
7196

7297
![perdoo sync help](docs/img/perdoo_sync.svg)
7398

7499
</details>
75100

101+
</details>
102+
76103
## Supported Formats
77104

78105
| Format | Input | Output |
79106
| ------ | :---: | :----: |
80-
| cb7 | ✅ | ✅ |
81-
| cbr | ✅ | ❌ |
82-
| cbt | ✅ | ✅ |
83-
| cbz | ✅ | ✅ |
84-
| pdf | ✅ | ❌ |
107+
| CB7 | ✅ | ✅ |
108+
| CBR | ✅ | ❌ |
109+
| CBT | ✅ | ✅ |
110+
| CBZ | ✅ | ✅ |
111+
| PDF | ✅ | ❌ |
85112

86113
### Metadata Files
87114

88-
Metadata file support comes from [comic-archive](https://codeberg.org/buriedincode/comic-archive), which currently supports:
115+
Metadata file support is provided by [comic-archive](https://codeberg.org/buriedincode/comic-archive), which currently supports:
89116

90-
- ComicInfo v2.0 (Slightly modified to ignore field ordering)
117+
- ComicInfo v2.0 (with field ordering ignored)
91118
- MetronInfo v1.1
92119

93120
## Services
@@ -97,51 +124,90 @@ Metadata file support comes from [comic-archive](https://codeberg.org/buriedinco
97124

98125
## File Renaming and Organization
99126

100-
File naming and organization uses a pattern-based approach, it tries to name based on the MetronInfo data with a fallback to ComicInfo.
127+
Perdoo uses a pattern-based approach for naming and organizing files.
128+
129+
Metadata is taken from MetronInfo when available, with ComicInfo used as a fallback.
101130

102131
The default pattern is:
103-
`{publisher-name}/{series-name}-v{volume}/{format}/{series-name}-v{volume}_#{number:3}`
104132

105-
### Options
133+
```text
134+
{publisher-name}/{series-name}-v{volume}/{format}/{series-name}-v{volume}_#{number:3}
135+
```
106136

107-
- **Padding**: Int and Int-like fields, such as `{number}`, can include optional zero-padding by specifying the length (e.g. `{number:3}` will pad 0's to be atleast 3 digits long, `12` => `012`).
108-
- **Sanitization**: All metadata values are sanitized to remove characters outside the set `0-9a-zA-Z&!-`.
137+
### Pattern Options
138+
139+
#### Padding
140+
141+
Integer and integer-like fields, such as `{number}`, support optional zero-padding by specifying a length.
142+
143+
For example:
144+
145+
```text
146+
{number:3}
147+
```
148+
149+
produces:
150+
151+
```text
152+
012
153+
```
154+
155+
from:
156+
157+
```text
158+
12
159+
```
160+
161+
#### Sanitization
162+
163+
Metadata values are sanitized to remove characters outside:
164+
165+
```text
166+
0-9a-zA-Z&!-
167+
```
109168

110169
Custom characters can still be added directly to patterns.
111170

112-
| Pattern Key | Description |
113-
| -------------------- | ------------------------------------------------------ |
114-
| `{cover-date}` | The issue cover date in `yyyy-mm-dd` format. |
115-
| `{cover-day}` | The day from the issue cover date. |
116-
| `{cover-month}` | The month from the issue cover date. |
117-
| `{cover-year}` | The year from the issue cover date. |
118-
| `{format}` | The full format name of the series. |
119-
| `{id}` | The primary id of the issue. |
120-
| `{imprint}` | The publisher's imprint. |
121-
| `{isbn}` | The issue's ISBN. |
122-
| `{issue-count}` | The total number of issues in the series. |
123-
| `{lang}` | The issue's language. |
124-
| `{number}` | The issue number. |
125-
| `{publisher-id}` | The publisher's unique id. |
126-
| `{publisher-name}` | The full name of the publisher. |
127-
| `{series-id}` | The series' unique id. |
128-
| `{series-name}` | The full name of the series. |
129-
| `{series-sort-name}` | Sort-friendly name (omits leading "The", "A", etc...). |
130-
| `{series-year}` | The year the series started. |
131-
| `{store-date}` | The store date of the issue in `yyyy-mm-dd` format. |
132-
| `{store-day}` | The day from the issue store date. |
133-
| `{store-month}` | The month from the issue store date. |
134-
| `{store-year}` | The year from the issue store date. |
135-
| `{title}` | The issue title. |
136-
| `{upc}` | The issue's UPC. |
137-
| `{volume}` | The volume of the series. |
171+
### Pattern Keys
172+
173+
| Pattern Key | Description |
174+
| -------------------- | ------------------------------------------------------------------------ |
175+
| `{cover-date}` | The issue cover date in `yyyy-mm-dd` format. |
176+
| `{cover-day}` | The day from the issue cover date. |
177+
| `{cover-month}` | The month from the issue cover date. |
178+
| `{cover-year}` | The year from the issue cover date. |
179+
| `{format}` | The full format name of the series. |
180+
| `{id}` | The primary ID of the issue. |
181+
| `{imprint}` | The publisher's imprint. |
182+
| `{isbn}` | The issue's ISBN. |
183+
| `{issue-count}` | The total number of issues in the series. |
184+
| `{lang}` | The issue's language. |
185+
| `{number}` | The issue number. |
186+
| `{publisher-id}` | The publisher's unique ID. |
187+
| `{publisher-name}` | The full name of the publisher. |
188+
| `{series-id}` | The series' unique ID. |
189+
| `{series-name}` | The full name of the series. |
190+
| `{series-sort-name}` | Sort-friendly series name, omitting leading words such as "The" and "A". |
191+
| `{series-year}` | The year the series started. |
192+
| `{store-date}` | The issue store date in `yyyy-mm-dd` format. |
193+
| `{store-day}` | The day from the issue store date. |
194+
| `{store-month}` | The month from the issue store date. |
195+
| `{store-year}` | The year from the issue store date. |
196+
| `{title}` | The issue title. |
197+
| `{upc}` | The issue's UPC. |
198+
| `{volume}` | The volume of the series. |
138199

139200
## Settings
140201

141-
To set Perdoo setting details, update the file: `~/.config/perdoo/settings.toml`.
142-
File will be created on first run.
202+
Perdoo's settings are stored in:
203+
204+
```text
205+
~/.config/perdoo/settings.toml
206+
```
207+
208+
The file is created automatically on first run.
143209

144-
### Example File
210+
### Example
145211

146212
```toml
147213
[output]
@@ -157,7 +223,7 @@ handle-pages = true
157223
create = true
158224

159225
[output.naming]
160-
seperator = "-"
226+
separator = "-"
161227
pattern = "{publisher-name}/{series-name}-v{volume}/{format}/{series-name}-v{volume}_#{number:3}"
162228

163229
[services]
@@ -170,47 +236,97 @@ api-key = "<Comicvine API Key>"
170236
token = "<Metron Token>"
171237
```
172238

173-
### Details
239+
### Output
174240

175-
- `output.folder`
176-
The folder where the output files will be stored.
177-
Defaults to `~/.local/share/perdoo/comics`.
241+
#### `output.folder`
178242

179-
- `output.format`
180-
The output file format for the comic archives.
181-
Defaults to `cbz`.
182-
See table above for options
243+
The folder where output files are stored.
183244

184-
- `output.image-extensions`
185-
The list of extensions perdoo determines to be images as part of the cleanup step.
186-
Defaults to `[".png", ".jpg", ".jpeg", ".webp", ".jxl"]`
245+
Defaults to:
187246

188-
- `output.comic-info.create`
189-
Whether to create a ComicInfo.xml file in the output archive.
190-
Defaults to `true`.
247+
```text
248+
~/.local/share/perdoo/comics
249+
```
250+
251+
#### `output.format`
252+
253+
The output format used for comic archives.
254+
255+
Defaults to `cbz`.
256+
257+
See [Supported Formats](#supported-formats) for available formats.
258+
259+
#### `output.image-extensions`
260+
261+
The file extensions Perdoo considers to be images during the cleanup step.
262+
263+
Defaults to:
264+
265+
```toml
266+
[".png", ".jpg", ".jpeg", ".webp", ".jxl"]
267+
```
268+
269+
### ComicInfo
270+
271+
#### `output.comic-info.create`
272+
273+
Whether to create a `ComicInfo.xml` file in the output archive.
274+
275+
Defaults to `true`.
276+
277+
#### `output.comic-info.handle-pages`
278+
279+
Whether to process page data in `ComicInfo.xml`.
280+
281+
Defaults to `true`.
191282

192-
- `output.comic-info.handle_pages`
193-
Whether to handle page data in the ComicInfo.xml file.
194-
Defaults to `true`.
283+
### MetronInfo
195284

196-
- `output.metron-info.create`
197-
Whether to create a MetronInfo.xml file in the output archive.
198-
Defaults to `true`.
285+
#### `output.metron-info.create`
199286

200-
- `output.naming.seperator`
201-
The word separator used in the output file names.
202-
Defaults to `-`.
203-
Options are `-`, `_`, `.`, or ` ` (space).
287+
Whether to create a `MetronInfo.xml` file in the output archive.
288+
289+
Defaults to `true`.
290+
291+
### Naming
292+
293+
#### `output.naming.separator`
294+
295+
The separator used in generated file names.
296+
297+
Defaults to `-`.
298+
299+
Supported values are:
300+
301+
- `-`
302+
- `_`
303+
- `.`
304+
- ` ` (space)
305+
306+
#### `output.naming.pattern`
307+
308+
The pattern used to generate output file names and directories.
309+
310+
See [File Renaming and Organization](#file-renaming-and-organization) for available pattern fields.
311+
312+
### Services
313+
314+
#### `services.order`
315+
316+
The order in which services are queried for metadata.
317+
318+
Perdoo uses the first service that returns a result. Services can be omitted from this list to disable them.
319+
320+
Defaults to:
321+
322+
```toml
323+
["Metron", "Comicvine"]
324+
```
204325

205-
- `output.naming.pattern`
206-
The pattern supports various metadata fields as described in the above "File Renaming and Organization" section.
326+
Supported services:
207327

208-
- `services.order`
209-
The order in which the services will be used for metadata retrieval.
210-
Metadata will be fetched from the first service that returns a result.
211-
Don't include the service name in the list if you don't want to use it.
212-
Defaults to `["Metron", "Comicvine"]`.
213-
Options are `Metron` or `Comicvine`.
328+
- `Metron`
329+
- `Comicvine`
214330

215331
## Socials
216332

0 commit comments

Comments
 (0)