From 31cff7dbcaf7d8087fb2c8eef2b949820fd5767c Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Sat, 20 Apr 2019 10:57:31 +0300 Subject: [PATCH] Document the pleroma.emoji task --- docs/config/custom_emoji.md | 20 ++++++++++++---- lib/mix/tasks/pleroma/emoji.ex | 44 +++++++++++++++++++++++++++++++++- 2 files changed, 58 insertions(+), 6 deletions(-) diff --git a/docs/config/custom_emoji.md b/docs/config/custom_emoji.md index 5ce9865a2..ac28635d0 100644 --- a/docs/config/custom_emoji.md +++ b/docs/config/custom_emoji.md @@ -1,15 +1,25 @@ # Custom Emoji +Before you add your own custom emoji, check if they are available in an existing pack. +See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs. + To add custom emoji: -* Add the image file(s) to `priv/static/emoji/custom` -* In case of conflicts: add the desired shortcode with the path to `config/custom_emoji.txt`, comma-separated and one per line -* Force recompilation (``mix clean && mix compile``) +* Create the `STATIC-DIR/emoji/` directory if it doesn't exist + (`STATIC-DIR` is configurable, `instance/static/` by default) +* Create a directory with whatever name you want (custom is a good name to show the purpose of it). + This will create a local emoji pack. +* Put your `.png` emoji files in that directory. In case of conflicts, you can create an `emoji.txt` + file in that directory and specify a custom shortcode using the following format: + `shortcode, file-path, tag1, tag2, etc`. One emoji per line. Note that if you do so, + you'll have to list all other emojis in the pack too. +* Either restart pleroma or connect to the iex session pleroma's running and + run `Pleroma.Emoji.reload/0` in it. Example: -image files (in `/priv/static/emoji/custom`): `happy.png` and `sad.png` +image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png` -content of `config/custom_emoji.txt`: +content of `emoji.txt`: ``` happy, /emoji/custom/happy.png, Tag1,Tag2 sad, /emoji/custom/sad.png, Tag1 diff --git a/lib/mix/tasks/pleroma/emoji.ex b/lib/mix/tasks/pleroma/emoji.ex index f4da183ad..0a1bf24e2 100644 --- a/lib/mix/tasks/pleroma/emoji.ex +++ b/lib/mix/tasks/pleroma/emoji.ex @@ -5,8 +5,50 @@ defmodule Mix.Tasks.Pleroma.Emoji do use Mix.Task - @shortdoc "Manages Pleroma instance" + @shortdoc "Manages emoji packs" @moduledoc """ + Manages emoji packs + + ## ls-packs + + mix pleroma.emoji ls-packs [OPTION...] + + Lists the emoji packs and metadata specified in the manifest. + + ### Options + + - `-m, --manifest PATH/URL` - path to a custom manifest, it can either be an URL + starting with `http`, in that case the manifest will be fetched from that address, + or a local path + + ## get-packs + + mix pleroma.emoji get-packs [OPTION...] PACKS + + Fetches, verifies and installs the specified PACKS from the manifest into + the `STATIC-DIR/emoji/PACK-NAME + + ### Options + + - `-m, --manifest PATH/URL` - same as ls-packs + + ## gen-pack + + mix pleroma.emoji gen-pack PACK-URL + + Creates a new manifest entry and a file list from the specified remote pack file. + Currently, only .zip archives are recognized as remote pack files and packs are therefore + assumed to be zip archives. This command is intended to run interactively and + will first ask you some basic questions about the pack, then download the remote + file and generate an MD5 signature for it, then generate an emoji file list for you. + + The manifest entry will either be written to a newly created `index.json` file or appended to the existing one, + *replacing* the old pack with the same name if it was in the file previously. + + The file list will be written to the file specified previously, *replacing* that file. + You _should_ check that the file list doesn't contain anything you don't need in the pack, that is, + anything that is not an emoji (the whole pack is downloaded, but only emoji files are extracted). + """ @default_manifest Pleroma.Config.get!([:emoji, :default_manifest])