User Manual
The UI of Poetry MP is designed for PC monitors and tablets, while the UI of Poetry Viewer is designed for PC monitors, tablets and mobile phones.
Startup
Depending on you had installed the app, the access URL could be:
- http://poetryapp.localhost if you had installed the app on local IIS or Apache.
- http://localhost:5300 if you run the app directly through the Powershell script or bash script.
- http://poetryapp.mydomain.com if you had installed the app on a Web server.
Login
Without login, the users can view published poems only.
The default password for user admin after installation is "adminPpp*8" and you should alter the password ASAP, and keep the new password in a safe place.
Managing Users
Since the app is for one poet, generally you just need one user admin. In case you may more than one to manage, you may create extra users.
Add / Edit Poem
If you have been writing blogs with HTML formatting, you should be familiar with the basic operations of composing HTML contents, though composing a poem generally does not require rich formatting.
In addition to basic HTML formatting, Poetry MP provides a few more options specially designed for composing poems with notations and images.
Extra HTML Operations
Insert Sup
This is similar to formatting a piece of text into superscript, however, this operation inserts a numeric superscript incrementally. And the numeric superscripts may be reordered.
Then you click button "Suggest Numbered Annotations" that pops up numeric superscripts which have not been annotated into numbered annotations.
When clicking the numeric button, you can input content for the numbered annotation.
When the readers of your poetry click a numbered annotation, they will see the content, or a Web paged directed by the Reference URL, or both.
From time to time, you may have numeric superscripts scattering around not in sequential order. If you want them to be ordered incrementally, you may "Reorder Superscripts" and the app will match the numbered annotations accordingly.
Upload Image and Insert
This is similar to "Insert Image" of basic HTML formatting, however, "Insert Image" is to load a local image and insert to HTML content as BASE64 chunk, while "Upload Image and Insert" is to store the uploaded image to the database and create a reference to the backend of the app.<syntaxhighlight lang="html"> <img class="local" src="api/files/file/e65bb512-1a9d-4a78-ac9e-83d74fbf9e8c.jpeg" alt="Pallas Athena" loading="lazy" decoding="async"> </syntaxhighlight>BASE64 chunk is generally 37% larger than the source data, thus, it is recommended to upload image and insert.
Pick Images and Insert
Images uploaded into the database can be shared across poems.
You may check to select images in "Local Pictures Management".
Paste as Plain Text
The HTML content that you had copied from the other sources may contain over complex or inconsistent or unsafe HTML tags, while generally the HTML content of a poem does not require rich formatting. Thus it is safer and simpler to page HTML content as plain text.
Replace Double Linebreaks with One
HTML provides a few ways of rendering linebreaks. Sometimes content copied from the other sources may contain more than one linebreak between lines. This command will reduce double linebreaks into one.
Annotations
Phase-based annotations match phases in a poem, and the annotations may be shared across poems containing the same phases.
Through clicking "Suggest Numbered Annotations" the app will scan the poem for matching existing annotations, then you may select matched annotations and associate with the poem.
Albums
If you had defined some albums, you may associate an album or multiple albums with the poem.
Album
An album is to contain a collection of poems. And you may have a description on the top as a preface.
Album functionality is available if "Settings/Edit/Use Albums" is on.
Checked poems will be contained in the album.
To quit, click this button highlighted:
Maintenance
From time to time, you may need to adjust some settings, backup, export data, or manage locally hosted pictures etc. Please check Maintenance for more details.
Export
The export functions could be used to export the poetry collection into JSON files and export all images into a zip file, then you download to a local drive for backup or publishing to a static Website.
Export All
This will result in downloading the poetry collection including settings in a JSON file. And the data in the JSON file can be used as a backup or become the data in a static Website for publishing. If your poetry collection contain locally hosted images, you may also need to "Export All Images".
Export All Published
This command is available when "Settings/Edit/Use Published Date" is on. For deceased poets or poems published decades ago, published date is likely insignificant. If you have poems in draft, you may not want to publish them yet, then this command could be useful.
A poem is published if the date published is defined.
Export All Images
If you had uploaded images into the database, you should export all images into a zip file. The zip file could be used as a backup or become the content of the static Website that you use for publishing.
Backup
This basically download the poetry database which is with Sqlite database engine.
Sqlite Database File
If you install PoetryApp MP as local desktop app, you may close the app and go to app's sub folder "PoetryApp_Data" and copy file poems.db to your backup drive. And it is better to name the backup file as "poemsYYYYMMDD.db" like "poems20211023.db".
JSON File and Optional Images.zip
The exported JSON file and the optional images.zip could be used as backup to be restored into a blank poems.db.
To restore the database, please check Restore.
Settings
Author
PoetryApp is designed for one poet, and you may input the basic poet info here.
Poetry
This section defines some language attributes of the poetry collection. It is optional to define the attributes.
For Chinese poetry, the situation could be more complex. For more details, check Settings for Chinese Poetry.
Edit
When editing a poem, you may apply multiple optional attributes to the poem.
View
The settings affect how the poem viewer displays the attributes of a poem. The settings defined here are stored in Web browser's local storage, not in the DB, thus the settings are effective as per the browser.
Annotations Management
Since phase-based annotations may be shared among poems, this is a center for managing annotations.
The number associated with each chip indicate how many poems are referencing the same annotation.
When you click a chip, you may edit the annotation. Or, if you change the "Click-Chip Action" to "List Poems", clicking a chip results in listing all poems referencing the same annotation.
Local Pictures Management
This is a center for managing locally hosted images which were uploaded and stored in the database.
The number associated with an image is to indicate how many poems are referencing the image, while the poems are listed as chips. Clicking a chip will display the respective poems then you may edit.
Since the poem is loading to HTML img tag like:<syntaxhighlight lang="html"> <img class="local" src="api/files/file/e65bb512-1a9d-4a78-ac9e-83d74fbf9e8c.jpeg" alt="Pallas Athena" loading="lazy" decoding="async"> </syntaxhighlight>However, the references recorded in the database and the references in HTML codes may lost sync from time to time, for example, you had removed respective HTML tags. Then you need to audit.
Audit
The app will scan associated poems to find out if the image is really referenced in each poem.
Audit All
The app will scan all poems to find out if any hosted image is not referenced in any poem.
Audit and Reconcile
Audit all, then remove orphaned images from the database.
External Pictures Management
A poem may contain images from external source, like:<syntaxhighlight lang="html"> <img width="512" alt="René-Antoine Houasse - The Dispute of Minerva and Neptune, 1689" src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/10/Ren%C3%A9-Antoine_Houasse_-_The_Dispute_of_Minerva_and_Neptune%2C_1689.jpg/512px-Ren%C3%A9-Antoine_Houasse_-_The_Dispute_of_Minerva_and_Neptune%2C_1689.jpg"> </syntaxhighlight>This module will scan all poems and list poems referencing external images.
Remote to Local
This will download the external picture and save to the database, and make the respective HTML img tag reference to the locally hosted image. And the description will be come the alt attribute of element img.
Remarks:
It is entirely your responsibility to sort our the copyright issues of the images used in the content.of poetry, through referencing or locally hosting.