From 8b6bacb14e721b2d9f938a6cb6121ac56fdcdb0b Mon Sep 17 00:00:00 2001 From: Talon Poole Date: Tue, 16 Feb 2021 22:16:11 +0000 Subject: [PATCH] documentation --- README.md | 67 +++++++++++++++++++++++++++++++++-------------- cli.js | 6 ++--- gmi-web.1.scd | 2 +- gmi.css | 7 +++-- html.js | 2 +- package-lock.json | 2 +- package.json | 2 +- 7 files changed, 57 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 0cdc712..6988012 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ These may also be nice to have: + ``` # gmi-web(1) @@ -78,28 +79,30 @@ Inline Media: CSS: --body-width [default: "48rem"] - --mono [default: "Consolas, monaco, monospace"] --serif [default: "georgia, times, serif"] - --sans-serif [default: "ubuntu, roboto, noto, sans-serif"] + --sans-serif [default: "avenir, helvetica, arial, sans-serif"] + --mono [default: "consolas, monaco, monospace"] --foreground [default: "black"] --background [default: "white"] - --p-size [default: "1.25rem"] - --p-indent [default: "0rem"] - --p-line-height [default: "1.5"] - --a-size [default: "1.25rem"] - --a-weight [default: "normal"] --a-decoration [default: "none"] + --a-style [default: "normal"] --a-prefix [default: ""⇒""] + --ul-bullet [default: ""*""] + --p-indent [default: "0rem"] + --quote-style [default: "italic"] + --p-size [default: "1.25rem"] + --a-size [default: "var(--p-size)"] --pre-size [default: "1rem"] - --pre-line-height [default: "1"] --h1-size [default: "3rem"] --h2-size [default: "2.25rem"] --h3-size [default: "1.5rem"] + --ul-size [default: "var(--p-size)"] + --quote-size [default: "var(--p-size)"] + --p-line-height [default: "1.5"] + --a-line-height [default: "1.5"] + --pre-line-height [default: "1"] --h-line-height [default: "1.25"] - --ul-size [default: "1.25rem"] --ul-line-height [default: "1.25"] - --ul-bullet [default: ""*""] - --quote-size [default: "1.25rem"] --quote-line-height [default: "1.25"] Options: @@ -113,24 +116,48 @@ Examples: gmi-web --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi gmi-web --image jpg --audio mp3 --image png --body < doc.gmi -See the gmi-web(1) man page for more information +See the gmi-web(1) man page for more information. ``` +A JSON file can be passed to `--config` for conveniently applying any option without using the command-line flag. [(yargs: .config)](https://github.com/yargs/yargs/blob/master/docs/api.md#configobject). For example a `web.json` file with the following contents... + +```json +{ + "html": "en", + "descriptions": 200, + "foreground": "#137752", + "background": "#F4F4F4", + "a-decoration": "underline", + "a-prefix": "none" +} +``` + +...can be used like so: + +```sh +gmi-web --config web.json $(find ~/gmi/dst -name '*.gmi') +``` + # gmi.css -Optimized for readability, predictability and mobile-friendliness. Ships with a handful of customizable variables. - -The `--foreground` and `--background` variables will be inverted when -`prefers-color-scheme` is "dark" which is a system-level preference on -devices. - -Any of the variables can be customized by adding a style to the `` element. +The CSS variables exposed by gmi-web(1) are derived from [gmi.css](./gmi.css), which could be used on its own. The default values are optimized for readability and mobile-friendliness and may be customized by adding a style property to ``. ```html - + + + + + + + + + ``` +The `--foreground` and `--background` variables will be inverted when +[prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) is "dark". + # License gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file. diff --git a/cli.js b/cli.js index de7cd40..91147e3 100755 --- a/cli.js +++ b/cli.js @@ -19,7 +19,7 @@ const cli = yargs(process.argv.slice(2)) "$0 --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi" ) .example("$0 --image jpg --audio mp3 --image png --body < doc.gmi") - .epilog("See the gmi-web(1) man page for more information") + .epilog("See the gmi-web(1) man page for more information.") ) .options({ body: { @@ -65,14 +65,14 @@ const cli = yargs(process.argv.slice(2)) default: "utf-8", requiresArg: true, }, - modes: { + schemes: { type: "boolean", hidden: true, default: false, }, }) .group(["html", "body"], "Core:") - .group(["author", "descriptions", "css", "modes", "dir"], "HTML:") + .group(["author", "descriptions", "css", "schemes", "dir"], "HTML:") .group(["image", "audio", "video"], "Inline Media:"); const CSS_VARS = CSS.rootVariables(CSS.FULL); diff --git a/gmi-web.1.scd b/gmi-web.1.scd index 7844d6e..7094b8f 100644 --- a/gmi-web.1.scd +++ b/gmi-web.1.scd @@ -1,4 +1,4 @@ -gmi-web(1) "1.0.8-rc.2" +gmi-web(1) "1.0.10-rc.2" # NAME diff --git a/gmi.css b/gmi.css index 3dfa3ab..a1d8be7 100644 --- a/gmi.css +++ b/gmi.css @@ -1,8 +1,8 @@ :root { --body-width: 48rem; - --serif: Times, Times New Roman, Georgia, serif; - --sans-serif: Verdana, Arial, Helvetica, sans-serif; - --mono: Lucida Console, Courier, monospace; + --serif: georgia, times, serif; + --sans-serif: avenir, helvetica, arial, sans-serif; + --mono: consolas, monaco, monospace; --foreground: black; --background: white; @@ -158,7 +158,6 @@ a:hover { background-color: var(--foreground); } -/* when system preference is "dark" invert foreground and background colors */ @media (prefers-color-scheme: dark) { html, body, diff --git a/html.js b/html.js index 6ac0246..4306447 100644 --- a/html.js +++ b/html.js @@ -59,7 +59,7 @@ export function head(options) { ${ - options.modes || options.css === "full" + options.schemes || options.css === "full" ? `\n` : "" }${style(options.css)} diff --git a/package-lock.json b/package-lock.json index f467293..cc9b396 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "gmi-web-cli", - "version": "1.0.7-rc.2", + "version": "1.0.8-rc.2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 98b23f5..dc77eb0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gmi-web-cli", - "version": "1.0.8-rc.2", + "version": "1.0.10-rc.2", "description": "A bridge between HTML and Gemini", "main": "html.js", "type": "module",