diff --git a/README.md b/README.md index 61c286c..9764479 100644 --- a/README.md +++ b/README.md @@ -32,18 +32,42 @@ Matrix. ## Usage -From the repository root: +There are two main import patterns: + +- One-off archival import: For when you have a large set of messages to import + for a service that you don't use very much anymore. +- Recurring import: For when you are still using the service, and want to + import on a recurring basis. + +This program will be default not overwrite existing files, as the user might +have modified it. + +Special consideration must be taking for recurring imports if you expect to be +modifying the resulting files, for example if you are inserting links +using Obsidian's unlinked mentions feature. You might want to use the +`--skip-this-period` flag to avoid importing the current period until it has +become the last period. That way you won't accidentally modify the log, because +it has been finalized. + +### One-off + +This is the recommended command for the one-off case: ```bash python -m libpurple_to_markdown LOG_DIRECTORY --output OUTPUT_FOLDER ``` -It was made specifically for import into Obsidian, so it might not suite your -purposes, but it shouldn't be too difficult to adjust the formatting code. +### Recurring + +This is the recommended command for the recurring import case: + +```bash +python -m libpurple_to_markdown LOG_DIRECTORY --output OUTPUT_FOLDER --skip-this-period --period month +``` ## TODO -- [ ] Decode MMS parts and reconstruct image attachments. +- [ ] SyncTech: Decode MMS parts and reconstruct image attachments. ## Dependencies diff --git a/setup.py b/setup.py index 5bb2bf5..9503ed3 100644 --- a/setup.py +++ b/setup.py @@ -39,18 +39,42 @@ Matrix. ## Usage -From the repository root: +There are two main import patterns: + +- One-off archival import: For when you have a large set of messages to import + for a service that you don't use very much anymore. +- Recurring import: For when you are still using the service, and want to + import on a recurring basis. + +This program will be default not overwrite existing files, as the user might +have modified it. + +Special consideration must be taking for recurring imports if you expect to be +modifying the resulting files, for example if you are inserting links +using Obsidian's unlinked mentions feature. You might want to use the +`--skip-this-period` flag to avoid importing the current period until it has +become the last period. That way you won't accidentally modify the log, because +it has been finalized. + +### One-off + +This is the recommended command for the one-off case: ```bash python -m libpurple_to_markdown LOG_DIRECTORY --output OUTPUT_FOLDER ``` -It was made specifically for import into Obsidian, so it might not suite your -purposes, but it shouldn't be too difficult to adjust the formatting code. +### Recurring + +This is the recommended command for the recurring import case: + +```bash +python -m libpurple_to_markdown LOG_DIRECTORY --output OUTPUT_FOLDER --skip-this-period --period month +``` ## TODO -- [ ] Decode MMS parts and reconstruct image attachments. +- [ ] SyncTech: Decode MMS parts and reconstruct image attachments. """.strip() PACKAGE_DESCRIPTION_SHORT = """