Proposed command line interface design for v1.0.0

[JinIgarashi]

I am thinking how charites can provide better experience of style making to users.

Thus, I thought some idea of new command line interface design.
Currently, there are a lot of options for each commands, I don't think it is user friendly, especially for Mapbox style beginners. I was trying to simplify command line interface by introducing configuration files instead of adding many optional parameters.

I just put them on this issue to discuss for better command line interface design.

@ubukawa @hfu @miya0001 @naogify What do you think about this draft design?

---

• Initializing a project

cd <project_dir>
charites init style.yaml --tilejson-urls <tilejson-urls> --metadatajson-urls <metadatajson-urls>

First, charites init command will create a charites project under <project_dir> as follows.

|_ layers - style.yml for layers
|_ icons - original SVG icons folder for sprite
|_ sprite - final sprite files from SVG
config.yml - configuration file to manage all folder paths and necessary settings for producing style.json
style.yml - root style file

config.yml can have following settings.

version: version of charites used
style:
  yaml-path: ./style.yml
  json-path: ./style.json
sprite:
  icons-folder: ./icons
  sprite-folder: ./sprite
  sprite-url: http://unvt.github.io/charites/sprite # this URL can be used final style.json file for production

• build style.json file from project's config.yaml

You can move to project directory and just run charites build or charites build config.yaml to convert yaml to style.json and sprite files.

cd <project_dir>
charites build

When charites build sprite files, it will create them which are used in style.yaml files.

• realtime style editing

After entering project directory, just run charites serve, it will automatically launch server with http://localhost:8080.

cd <project_dir>
charites serve

• convert existing style.json to style.yaml

If you run command like below with project folder path, it will create style.yaml and config.yaml in specified project folder. All of settings can be stored under a folder.

charites convert style.json <project folder>

• create sprite file from all icons under a folder

Current sprite generate is to make sprite files from all icons under a specific folder. This function can be moved to independent command like below.

charites sprite <icons_folder> <sprite folder>

This command is useful if all style including icons was already configured. However, user have to edit sprite file path in config.yml after making sprite by this command

• build glyph file from font file

In the future, we may create a command to build glyph from font file.

charites font <font_file> <glyph folder>

[hfu]

Thanks! I also would review this and get back to you.

[naogify]

@JinIgarashi
Thank you! I will write a comment this afternoon about the sub-subcommand design we discussed. Sorry for the delay.

[naogify]

Based on the idea of @JinIgarashi , I write a sub-sub command design. What do you think about it?

Overview

Overview of command design.

$ charites help
Commands:
  init
  import
  serve
  style <command>
  sprite <command>
  glyphs  <command>

---

charites init

Create charites project files for create map style. (config.yml , style.yml and directories that @JinIgarashi said in the previous comment).

Options

• --tilejson-urls <tilejson_urls> an URL for TileJSON.
• --metadatajson-urls <metadatajson_urls> an URL for metadata.json.
• --composite-layers a single YAML will be generated with multiple layers.
• --header add http header for the tile authenticated by origin. (ex. --header "Origin: http://localhost:8080")

• Initializing a project

cd <project_dir>
charites init style.yaml --tilejson-urls <tilejson-urls> --metadatajson-urls <metadatajson-urls>

First, charites init command will create a charites project under <project_dir> as follows.

|_ layers - style.yml for layers
|_ icons - original SVG icons folder for sprite
|_ sprite - final sprite files from SVG
config.yml - configuration file to manage all folder paths and necessary settings for producing style.json
style.yml - root style file

config.yml can have following settings.

version: version of charites used
style:
  yaml-path: ./style.yml
  json-path: ./style.json
sprite:
  icons-folder: ./icons
  sprite-folder: ./sprite
  sprite-url: http://unvt.github.io/charites/sprite # this URL can be used final style.json file for production

charites import

create charites project files from exist style.json

Options

• --composite-layers a single YAML will be generated with multiple layers.

charites import style.json

Then we will get the same result of charites init (ex, style.yml, config.yml, layers/).

charites serve

Options

• --port <custom port> number of custom port

• realtime style editing

After entering project directory, just run charites serve, it will automatically launch server with http://localhost:8080.

cd <project_dir>
charites serve

• It should build sprite and glyphs in realtime.
• the sprite and glyphs url in style.json is replace to the url start with http://localhost:8080/.

charites style <command>

charites style build

build style.yml to style.json.

Options

• --compact-output minify output JSON file.

We can just run charites style build which use settings in config.yml or charites style build <source> [destination] like the sample below. The default [destination] value is build/.

charites style build style.yml style.json

charites sprite <command>

charites sprite build

build icon sprite files (ex, icons.png, icons.json) from svg files.

Options

• --name <sprite file name> sprite file name. (ex icons)

We can just run charites sprite build which use settings in config.yml or charites sprite build <source> [destination] like the sample below. The default [destination] value is build/.

charites sprite build asset/ public/ --name icons

charities glyphs <command>

charites glyphs build

build glyph files from font files.

We can just run charites glyphs build which use settings in config.yml or charites glyphs build <source> [destination] like the sample below. The default [destination] value is build/.

charites glyphs build font/ glyphs/

[naogify]

in addition to command design in previous comment, I propose the <project_dir> and config.yml below.

@ubukawa @hfu @JinIgarashi @miya0001 What do you think about this draft design?

project-directory/
├── style.yml - root style file
├── config.yml - configuration file to manage all folder paths and necessary settings for producing style.json
├── layers/ - style.yml for layers
├── icons/  - original SVG icons folder for sprite
├── fonts/ - original font files folder for glyphs.
└── build/ - folder for the files that ready to deploy.
    ├── style.json
    ├── icons.json
    ├── icons.png
    ├── icons@2x.json
    ├── icons@2x.png
    └── glyphs files(.pbf?) - sorry I need research what type of file used for glyphs.

config.yml can have following settings.

version: version of charites used
serve:
  port: 8080
style:
  build:
    yaml-path: ./style.yml
    json-path: ./build/style.json
    compact-output: false
sprite:
  build:
    icons-folder: ./icons
    sprite-folder: ./build
    name: icons
glyphs:
  build:
    fonts-folder: ./fonts
    glyphs-folder: ./build

[JinIgarashi]

@naogify I think it is a good idea to have <project_dir> option in init command instead of moving current directory.

glyphs require to create glyphs.json under a folder.
https://github.com/watergis/font-glyphs/blob/gh-pages/glyphs.json

I suggest to use different folder name (eg., dist or public) for final outputs instead of build folder. Furthermore, it is better to have sprite folder and glyphs folder under a project.

So, config.yaml can be like below.

version: version of charites used
serve:
  port: 8080
style:
  build:
    yaml-path: ./style.yml
-    json-path: ./build/style.json
+   json-path: ./public/style.json
    compact-output: false
sprite:
  build:
    icons-folder: ./icons
-    sprite-folder: ./build
+   sprite-folder: ./public/sprite
    name: icons
glyphs:
  build:
    fonts-folder: ./fonts
-    glyphs-folder: ./build
+   glyphs-folder: ./public/glyphs

However, I don't think all users require to build their own glyphs. So it is worth to have another option like --glyphs-url in init command instead. As default, we can use geolonia's glyphs URL.

[JinIgarashi]

For creating sprite, it might be useful if multiple icons folders (eg., /maki folder and customized-icons folder) can be specified.

charites also can have a command to download all maki icons to local folder. It can be helpful.

[hfu]

Thank you, @JinIgarashi and @naogify for great ideas. LGTM.

Regarding sprites, are we using file names of the .svg files as the name of the sprite?

We might want to think about sprite.yml file which assign sprite name to each sprite graphics. sprite.yml might look like:

airport: https://example.com/somewhere/airport.svg
branch: ./icons/gsi-icon.svg

I think sprite.yml will be helpful because it would always be good to optimize the size of sprite file. By introducing sprite.yml we can promote nicely customized sprites.

[ubukawa]

Thank you @JinIgarashi and @naogify for your great efforts!

I have one question.
Even if we use "import" instead of "convert," can we specify the target location/file name as before?
I want to specify the location of the yml as a sub-directory because I some times convert more than one json files into the separated sets of layer files.

charites convert style-001.json style01/style.yml

charites import style-001.json style01/style.yml

Or, you would recommend that I should work at the different project directories for different styles.

Thank you for your advice and great effort!!

[ubukawa]

If I may, can I ask one more thing?

I also wonder if it is possible to add "charites --version" command?
Or, as you said, the version will be flexibly configured at the config file?

It would be nice to know the version given that the command line interface design may change.
Thank you for your kind attention.

P.S.
I am sorry to my late response. Recently, I found that notifications from Github came to my previous email address.

[naogify]

@JinIgarashi
Thank you for telling me about glyphs.json.

I think it's good to use public as a folder name, and have sprite and glyphs folders.

So it is worth to have another option like --glyphs-url in init command instead. As default, we can use geolonia's glyphs URL.

Also, this idea is looks good me.

[JinIgarashi]

@hfu

Regarding sprites, are we using file names of the .svg files as the name of the sprite?
We might want to think about sprite.yml file which assign sprite name to each sprite graphics.

I think charites can use svg file name as icon name in style.yml as default because that can be simpler. But it might be good idea to give different icon name from original. I think UNVT is implementing this feature in naru by using hocon.

@ubukawa
I think we can have an option to specify charites project directory in charites import command.

If there is no target directory like below, charites import and create new project under current directory.

charites import style-001.json

If project directory is specified as below, charites will import and generate new project under targeted directory.

charites import style-001.json style01

can it work for you?

In addition, adding --version and -v option to check installed version of charites is good idea, I think. We can implement this option.

[JinIgarashi]

@naogify Could you sort out above ideas from @hfu and @ubukawa to update CLI design? Thank you.

[naogify]

@JinIgarashi
Sure! I will add it to the CLI design draft and crate issue for each command.

[ubukawa]

Dear @JinIgarashi and @naogify , thank you for your great advice and contribution!
I really appreciate your continued contribution!! Thank you!

[naogify]

@JinIgarashi
Sorry for the delay. I created the issues!

https://github.com/unvt/charites/issues

[JinIgarashi]

@naogify @miya0001 @ubukawa @hfu Let us continue discussing new CLI interface for v1.0.0 here.

[JinIgarashi]

@naogify @miya0001 charites v1.0.0に向けて、developブランチを作成しました。
その第一弾として、initコマンド実行時に指定したプロジェクトフォルダ下にstyle.ymlとconfig.ymlを作成するように修正したPR(#82) を作りました。