specter/gmi-web
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

update docs

Browse source
This commit is contained in:
Talon Poole 2021-02-12 20:41:43 +00:00
parent 8eef926f7f
commit 6a11b71497
7 changed files with 105 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -2,9 +2,9 @@
This repo is home to: This repo is home to:
* [a gmi-to-html specification](#gmi-to-html) - [a gmi-to-html specification](#gmi-to-html)
* [the gmi-web(1) command-line tool](#gmi-web-1) - [the gmi-web(1) command-line tool](#gmi-web-1)
* [a gmi.css stylesheet](#gmi-css) - [a gmi.css stylesheet](#gmi-css)
# gmi-to-html # gmi-to-html
@ -19,7 +19,7 @@ The converted Gemini document should exist inside the `<body>`. Consider if shar
<blockquote> ↔ > <blockquote> ↔ >
```` ````
List items must be wrapped with a `<ul>` tag. Empty lines should simply be represented as `<p><br></p>`. Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated List items must be wrapped with a `<ul>` tag. Empty lines should be represented as `<p><br></p>`. Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
HTML for these tags. HTML for these tags.
`<a>` tags are considered [inline elements](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow) which has presentational implications—CSS 2.1's _Normal Flow_ renders inline elements vertically. Gemini only deals with horizontally flowing content, this can be addressed by either re-defining `a {display: block;}` at the CSS level or by wrapping `<a>` tags in a "block" level element such as `<p>`. [MDN: Changing Element Levels](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#changing_element_levels) `<a>` tags are considered [inline elements](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow) which has presentational implications—CSS 2.1's _Normal Flow_ renders inline elements vertically. Gemini only deals with horizontally flowing content, this can be addressed by either re-defining `a {display: block;}` at the CSS level or by wrapping `<a>` tags in a "block" level element such as `<p>`. [MDN: Changing Element Levels](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#changing_element_levels)
@ -43,7 +43,7 @@ Additionally a `<head>` tag with at least the following must also be included:
These may also be nice to have: These may also be nice to have:
```html ```html
<meta name="author" content=""> <meta name="author" content="" />
<meta name="description" content="" /> <meta name="description" content="" />
<link rel="canonical" href="gemini://" /> <link rel="canonical" href="gemini://" />
``` ```
@ -56,7 +56,7 @@ Currently approaching a v1 release 🎉 Would you like to help test the RC? _You
npm install --global gmi-web-cli npm install --global gmi-web-cli
``` ```
```sh ```
gmi-web [files..] gmi-web [files..]
Convert text/gemini to text/html. Convert text/gemini to text/html.

4
cli.js
View file

@ -12,7 +12,9 @@ const cli = yargs(process.argv.slice(2))
.command("$0 [files..]", "Convert text/gemini to text/html.", (yargs) => .command("$0 [files..]", "Convert text/gemini to text/html.", (yargs) =>
yargs yargs
.example("$0 --html en $(find ~/my-capsule -name '*.gmi')") .example("$0 --html en $(find ~/my-capsule -name '*.gmi')")
.example("$0 --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi") .example(
"$0 --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi"
)
.example("$0 --body < ~/my-capsule/index.gmi") .example("$0 --body < ~/my-capsule/index.gmi")
.example("$0 --image jpg --audio mp3 --image png --body < 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")

79
gmi-web.1
View file

@ -5,15 +5,17 @@
.nh .nh
.ad l .ad l
.\" Begin generated content: .\" Begin generated content:
.TH "gmi-web" "1" "2021-02-11" "1.0.7-rc.1" .TH "gmi-web" "1" "2021-02-12" "1.0.0-rc.2"
.P .P
.SH NAME .SH NAME
.P .P
gmi-web - A bridge between Gemini and HTML. gmi-web - a bridge between Gemini and HTML
.P .P
.SH SYNOPSIS .SH SYNOPSIS
.P .P
\fBgmi-web\fR [--lang] <\fIOPTIONS\fR> [\fIFILES\fR] \fBgmi-web\fR [--html|--body] <\fIOPTIONS\fR> < [\fIFILE\fR]
.P
\fBgmi-web\fR [--html|--body] <\fIOPTIONS\fR> [\fIFILES\fR]
.P .P
.SH DESCRIPTION .SH DESCRIPTION
.P .P
@ -22,67 +24,52 @@ and mobile-friendly fashion!
.P .P
.SH OPTIONS .SH OPTIONS
.P .P
\fB--lang\fR \fB--html\fR \fILANG\fR
.RS 4 .RS 4
Required for <meta languge=""> Generate a full HTML5 document with the provided \fILANG\fR.
.P
\fBgmi-web\fR --html en < doc.gmi
.P .P
.RE .RE
\fBCSS Variables\fR \fB--body\fR
.RS 4 .RS 4
Any variable documented in \fBgmi.css\fR(5) can be set via \fIOPTIONS\fR of the same Generate only the HTML for the lines of the Gemini document.
name.
.P .P
\fBgmi-web\fR --lang "en" --foreground "#FFFFF" --background "#00000" $(find . -name *.gmi) \fBgmi-web\fR --body < doc.gmi
.P .P
.RE .RE
\fB--images\fR \fB--audio\fR \fB--video\fR \fB--css\fR \fIMODE\fR
.RS 4 .RS 4
Include the respective media inline. By default this will be set to \fBgmi.css\fR. Choosing \fBbase\fR will use just what
is needed to fix issues with CSS 2.1's Normal Flow. Choosing \fBnone\fR will not
include any style information and inline elements will be wrapped in <p>.
.P .P
.RE .RE
\fB--no-css\fR \fBgmi.css\fR
.RS 4 .RS 4
Use only the bare minimum <style> See --help or gmi.css(5) for the complete list of customizable styles.
.P
\fBgmi-web\fR --html en --foreground "#555555" --background "#9EEBCF" < doc.gmi
.P
.RE
\fB[--image|--audio|--video]\fR \fIEXENSIONS\fR
.RS 4
Include the provided \fIEXTENSIONS\fR as inline media according to the flag used.
You can provide multiple extensions per flag or multiple flags per extension.
.P
\fBgmi-web\fR --image jpg png --audio mp3 --html en < doc.gmi
.P
\fBgmi-web\fR --image jpg --image png --audio mp3 --html en < doc.gmi
.P .P
.RE .RE
\fB--config\fR [\fIJSON\fR] \fB--config\fR [\fIJSON\fR]
.RS 4 .RS 4
All the options documented here and by \fB--help\fR may be captured in a .json All the options documented here and by \fB--help\fR may be captured in a .json
file and passed to \fB--config\fR. file and passed to \fB--config\fR instead of as flags on the command-line.
.P
\fBgmi-web\fR --config web.json < doc.gmi
.P .P
.RE .RE
.SH EXAMPLES
.P
Render .html for all the .gmi files in the current directory
.P
.nf
.RS 4
gmi-web --lang en $(find \&. -name "*\&.gmi")
.fi
.RE
.P
To use \fB--config\fR you will need a .json file with the flags you want to be
included.
.P
.nf
.RS 4
{
"language": "en",
"foreground": "#137752",
"background": "#F4F4F4"
}
.fi
.RE
.P
Then give the path to \fBgmi-web\fR --config.
.P
.nf
.RS 4
gmi-web --config /path/to/my\&.json $(find \&. -name "*\&.gmi")
.fi
.RE
.P
.P
.SH SEE ALSO .SH SEE ALSO
.P .P
\fBgmi.css\fR(5) \fBgmi.css\fR(5)

67
gmi-web.1.scd
View file

@ -2,11 +2,13 @@ gmi-web(1) "1.0.0-rc.2"
# NAME # NAME
gmi-web - A bridge between Gemini and HTML. gmi-web - a bridge between Gemini and HTML
# SYNOPSIS # SYNOPSIS
*gmi-web* [--lang] <_OPTIONS_> [_FILES_] *gmi-web* [--html|--body] <_OPTIONS_> < [_FILE_]
*gmi-web* [--html|--body] <_OPTIONS_> [_FILES_]
# DESCRIPTION # DESCRIPTION
@ -15,50 +17,39 @@ and mobile-friendly fashion!
# OPTIONS # OPTIONS
*--lang* *--html* _LANG_
Required for <meta languge=""> Generate a full HTML5 document with the provided _LANG_.
*CSS Variables* *gmi-web* --html en < doc.gmi
Any variable documented in *gmi.css*(5) can be set via _OPTIONS_ of the same
name.
*gmi-web* --lang "en" --foreground "#FFFFF" --background "#00000" $(find . -name \*.gmi) *--body*
Generate only the HTML for the lines of the Gemini document.
*--images* *--audio* *--video* *gmi-web* --body < doc.gmi
Include the respective media inline.
*--no-css* *--css* _MODE_
Use only the bare minimum <style> By default this will be set to *gmi.css*. Choosing *base* will use just what
is needed to fix issues with CSS 2.1's Normal Flow. Choosing *none* will not
include any style information and inline elements will be wrapped in <p>.
*gmi.css*
See --help or gmi.css(5) for the complete list of customizable styles.
*gmi-web* --html en --foreground "#555555" --background "#9EEBCF" < doc.gmi
*[--image|--audio|--video]* _EXENSIONS_
Include the provided _EXTENSIONS_ as inline media according to the flag used.
You can provide multiple extensions per flag or multiple flags per extension.
*gmi-web* --image jpg png --audio mp3 --html en < doc.gmi
*gmi-web* --image jpg --image png --audio mp3 --html en < doc.gmi
*--config* [_JSON_] *--config* [_JSON_]
All the options documented here and by *--help* may be captured in a .json All the options documented here and by *--help* may be captured in a .json
file and passed to *--config*. file and passed to *--config* instead of as flags on the command-line.
# EXAMPLES
Render .html for all the .gmi files in the current directory
```
gmi-web --lang en $(find . -name "\*.gmi")
```
To use *--config* you will need a .json file with the flags you want to be
included.
```
{
"language": "en",
"foreground": "#137752",
"background": "#F4F4F4"
}
```
Then give the path to *gmi-web* --config.
```
gmi-web --config /path/to/my.json $(find . -name "\*.gmi")
```
*gmi-web* --config web.json < doc.gmi
# SEE ALSO # SEE ALSO

27
gmi.css.5
View file

@ -5,17 +5,12 @@
.nh .nh
.ad l .ad l
.\" Begin generated content: .\" Begin generated content:
.TH "gmi.css" "5" "2021-02-11" "1.0.7-rc.1" .TH "gmi.css" "5" "2021-02-12" "1.0.0-rc.2"
.P .P
.SH NAME .SH NAME
.P .P
\fBgmi.css\fR - stylesheet for Gemini generated HTML. \fBgmi.css\fR - stylesheet for Gemini generated HTML.
.P .P
.SH DESCRIPTION
.P
gmi.css is optimized for readability, predictability. and mobile-friendliness.
Ships with a handful of customizable variables.
.P
.SH VARIABLES .SH VARIABLES
.P .P
.nf .nf
@ -45,7 +40,8 @@ Ships with a handful of customizable variables.
.fi .fi
.RE .RE
.P .P
Any of the variables can be customized by adding a style tag to the <html> element. Any of the variables can be customized by adding a style attribute to the
<html> element.
.P .P
.nf .nf
.RS 4 .RS 4
@ -54,8 +50,21 @@ Any of the variables can be customized by adding a style tag to the <html> eleme
.RE .RE
.P .P
The \fB--foreground\fR and \fB--background\fR variables will be inverted when The \fB--foreground\fR and \fB--background\fR variables will be inverted when
\fBprefers-color-scheme\fR is "dark" which is a system-level preference on \fBprefers-color-scheme\fR is "dark".
devices. https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
.P
.SH USAGE
.P
The simplest way to use gmi.css is to include a link to it in the <head> of
your <html> document.
.P
.nf
.RS 4
<link rel="stylesheet" type="text/css" href="gmi\&.css">
.fi
.RE
.P
It could also be minimized and/or included directly in a <style> tag.
.P .P
.SH SEE ALSO .SH SEE ALSO
.P .P

23
gmi.css.5.scd
View file

@ -4,11 +4,6 @@ gmi.css(5) "1.0.0-rc.2"
*gmi.css* - stylesheet for Gemini generated HTML. *gmi.css* - stylesheet for Gemini generated HTML.
# DESCRIPTION
gmi.css is optimized for readability, predictability. and mobile-friendliness.
Ships with a handful of customizable variables.
# VARIABLES # VARIABLES
``` ```
@ -36,15 +31,27 @@ Ships with a handful of customizable variables.
sans-serif; sans-serif;
``` ```
Any of the variables can be customized by adding a style tag to the <html> element. Any of the variables can be customized by adding a style attribute to the
<html> element.
``` ```
<html style="--foreground:#555555; --background:#9EEBCF;"> <html style="--foreground:#555555; --background:#9EEBCF;">
``` ```
The *--foreground* and *--background* variables will be inverted when The *--foreground* and *--background* variables will be inverted when
*prefers-color-scheme* is "dark" which is a system-level preference on *prefers-color-scheme* is "dark".
devices. https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
# USAGE
The simplest way to use gmi.css is to include a link to it in the <head> of
your <html> document.
```
<link rel="stylesheet" type="text/css" href="gmi.css">
```
It could also be minimized and/or included directly in a <style> tag.
# SEE ALSO # SEE ALSO

2
package-lock.json generated
View file

@ -1,6 +1,6 @@
{ {
"name": "gmi-web-cli", "name": "gmi-web-cli",
"version": "1.0.7-rc.1", "version": "1.0.0-rc.2",
"lockfileVersion": 1, "lockfileVersion": 1,
"requires": true, "requires": true,
"dependencies": { "dependencies": {