From 7335afeff2b70945e21f65ba0684e957f24e4ba9 Mon Sep 17 00:00:00 2001 From: caribaud Date: Fri, 19 May 2023 18:03:14 +0200 Subject: [PATCH] Update 'README.md' --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 440da13..da23242 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,86 @@ -# melpomene +# Melpomene -Melpomene is a minimalist webcomic reading utility consisting of a simple, single-file javascript. \ No newline at end of file +![](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +Melpomene is a a simple, easy to integrate webcomic reading utility . + +It allows people to look through your webcomic like they would in real life : panel by panel. It displays your pages through a series of zooms you defines beforehand. + +Melpomene uses SVGs as input to defines the zooms. It allows you to use any SVG editor as a "What You See Is What You Get" editor. + +This repository host a small demo you can open in your browser : the [episode 35 of pepper and carrot](https://www.peppercarrot.com/en/webcomic/ep35_The-Reflection.html) (see Credits). You can open `demos/pepper_and_carrot_e35_lowres.html` and `demos/pepper_and_carrot_e35_highres.html` to see Mepomene in action! + + +# How Melpomene works + +In truth, Melpomene is a bit more complicated than a single-file javascript. You must now how to create web pages using HTML, CSS and Javascript. + +It works with : ++ HTML, CSS and Javascript snipets you can put in your web page to add the webcomic reader ++ A Javascript file describing the various informations required by the reader ++ A Python script, used to generate the above Javascript configuration file + +```mermaid +flowchart TB + page([Your comic pages]) -- use in --> svgedit[SVG editor
e.g. Inkscape, etc...] + svgedit -- export --> svg([SVGs with
zooms defined]) + svg -- use in --> confgen[Melpomene
config generator] + confgen --> conf([json
config]) + conf & html([HTML snipet]) & js([JS snipet]) & css([CSS snipet]) -- use / import into --> webpage([Your web page]) +``` + +# How to setup Melpomene ? + +## Defining the zooms + +All the zooms must be manually defined by you. +To do so, you can use your favorite SVG editor. If you don't have one, [Inkscape](https://inkscape.org/) is a good one. + +To create the zooms for a comic page, what you need to do is : + +1. Open your comic page in your editor (make sure to keep the image's original size when importing!) + * If your software ask, there is no need to actually import the image, you only need to link it. +2. Create a simple rectangle over each zoom you want, in the order you want them to show up + * You can set the rectangle's color to be translucent so you can still see the page underneath them! + * If you want to change the zoom order, you can change their order in the layer view of your SVG tool if they support it +3. Once you are done, save the SGV + + +## Generating the configuration files + +Once the SVG for your pages are done, put them in one folder. Then, you can run the zoom generator. + +You need to open a terminal and then run : ++ `python zooms_generator.py zooms_data.json` on windows ++ `python3 zooms_generator.py zooms_data.json` on linux + +The pages need to be in alphabetical order! It assumes the first page is page 1, the next one is page 2, etc.. + +The script will then generate the file `zooms_data.json`. + +You are now ready to integrate Melpomene in your website! + + +## Integrating Melpomene + +Let's assume your site is `https://my.website/`. + +You now need : +1. Host the Melpomene Javascript and CSS files in your website, e.g. at `https://my.website/melptomene.js` and `https://my.website/melptomene.css` +2. Host the zooms data on your website, e.g. at `https://my.website/zooms_data.js` +2. Include the various parts of the HTML snipets : + 1. `melpomene_head.html` goes in the `head` tag of your page + * You may need to change the `href` values to where you uploaded the CSS file. + 2. `melpomene_reader.html` goes where you want somewhere within the `body` tag of your page + * Change `https://link.to.my/comic/page.jpg` to the actual URL of your comic pages and duplicate the `img` + tag for each of them + 3. `melpomene_js.html` goes right after the `body` tag of your page. + * You may need to change the `href` values to where you uploaded the JS files. + +You can now open your page and should see the results. + +If you are having troubles, you can open the demo files to see how it was done. + +# Credits + +Most examples and the documentation of Melpomene uses illustrations from David "Deevad" Revoy's "Pepper & Carrot" webcomic, which is published under CC-BY 4.0. Full licence [here](https://www.peppercarrot.com/en/license/index.html). \ No newline at end of file