From 1c12774b021cb7a7b25dfda4eed9d137e23f46f0 Mon Sep 17 00:00:00 2001 From: Lucas Magasweran Date: Tue, 15 Sep 2020 15:23:23 +0200 Subject: [PATCH 1/5] docs: remove unicode zero length character --- README.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 24a44ce..c899350 100644 --- a/README.md +++ b/README.md @@ -8,24 +8,24 @@ upload content to https://gist.github.com/. ## Installation -‌If you have ruby installed: +If you have ruby installed: gem install gist -‌If you're using Bundler: +If you're using Bundler: source :rubygems gem 'gist' -‌For OS X, gist lives in Homebrew +For OS X, gist lives in Homebrew brew install gist -‌For FreeBSD, gist lives in ports +For FreeBSD, gist lives in ports pkg install gist -<200c>For Ubuntu/Debian +For Ubuntu/Debian apt install gist @@ -33,49 +33,49 @@ Note: Debian renames the binary to `gist-paste` to avoid a name conflict. ## Command -‌To upload the contents of `a.rb` just: +To upload the contents of `a.rb` just: gist a.rb -‌Upload multiple files: +Upload multiple files: gist a b c gist *.rb -‌By default it reads from STDIN, and you can set a filename with `-f`. +By default it reads from STDIN, and you can set a filename with `-f`. gist -f test.rb .[.]` (e.g. -`~/.gist.http.github.internal.example.com` for the GITHUB_URL example above) instead of `~/.gist`. +`~/.gist.http.github.internal.example.com` for the `GITHUB_URL` example above) instead of `~/.gist`. If you have multiple servers or use Enterprise and public GitHub often, you can work around this by creating scripts that set the env var and then run `gist`. Keep in mind that to use the public GitHub you must unset the env var. Just @@ -165,7 +165,7 @@ Error: Bad credentials # Library -‌You can also use Gist as a library from inside your ruby code: +You can also use Gist as a library from inside your ruby code: Gist.gist("Look.at(:my => 'awesome').code") @@ -181,11 +181,11 @@ If you need more advanced features you can also pass: NOTE: The access_token must have the `gist` scope and may also require the `user:email` scope. -‌If you want to upload multiple files in the same gist, you can: +If you want to upload multiple files in the same gist, you can: Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar") -‌If you'd rather use gist's builtin access_token, then you can force the user +If you'd rather use gist's builtin access_token, then you can force the user to obtain one by calling: Gist.login! @@ -195,12 +195,12 @@ in `~/.gist`, where it can later be read by `Gist.gist` ## Configuration -‌If you'd like `-o` or `-c` to be the default when you use the gist executable, add an +If you'd like `-o` or `-c` to be the default when you use the gist executable, add an alias to your `~/.bashrc` (or equivalent). For example: alias gist='gist -c' -‌If you'd prefer gist to open a different browser, then you can export the BROWSER +If you'd prefer gist to open a different browser, then you can export the BROWSER environment variable: export BROWSER=google-chrome From 6ec0a68c7c7ab3175f5ecf9fbc933b450f301269 Mon Sep 17 00:00:00 2001 From: Lucas Magasweran Date: Wed, 16 Sep 2020 16:12:13 +0200 Subject: [PATCH 2/5] docs: README: one more unicode char --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c899350..af81326 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ If you'd rather use gist's builtin access_token, then you can force the user Gist.login! -‌This will take them through the process of obtaining an OAuth2 token, and storing it +This will take them through the process of obtaining an OAuth2 token, and storing it in `~/.gist`, where it can later be read by `Gist.gist` ## Configuration From b9cebf966a0e399d3ad59b62775bc72dcb23c4b2 Mon Sep 17 00:00:00 2001 From: Lucas Magasweran Date: Wed, 16 Sep 2020 16:30:47 +0200 Subject: [PATCH 3/5] docs: replace the unicode zero length characters with asterisks to be compatible with man page generated with ronn and make it easier to edit the README.md Removing the unicode makes editing it easier. However, ronn has some issues with Markdown to man page format. For example, adding colons to the end of a bulleted line may disable bullets for the whole section. --- README.md | 50 ++++++++++++++++++++++++-------------------------- Rakefile | 4 +--- 2 files changed, 25 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index af81326..08b7263 100644 --- a/README.md +++ b/README.md @@ -8,84 +8,82 @@ upload content to https://gist.github.com/. ## Installation -If you have ruby installed: +* If you have ruby installed: gem install gist -If you're using Bundler: +* If you're using Bundler: source :rubygems gem 'gist' -For OS X, gist lives in Homebrew +* For OS X, `gist` lives in Homebrew brew install gist -For FreeBSD, gist lives in ports +* For FreeBSD, `gist` lives in ports pkg install gist -For Ubuntu/Debian +* For Ubuntu/Debian, `gist` has been renamed to `gist-paste` to avoid a name conflict apt install gist -Note: Debian renames the binary to `gist-paste` to avoid a name conflict. - ## Command -To upload the contents of `a.rb` just: +* To upload the contents of `a.rb` just: gist a.rb -Upload multiple files: +* Upload multiple files: gist a b c gist *.rb -By default it reads from STDIN, and you can set a filename with `-f`. +* By default it reads from STDIN, and you can set a filename with `-f`. gist -f test.rb 'awesome').code") @@ -181,11 +179,11 @@ If you need more advanced features you can also pass: NOTE: The access_token must have the `gist` scope and may also require the `user:email` scope. -If you want to upload multiple files in the same gist, you can: +* If you want to upload multiple files in the same gist, you can: Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar") -If you'd rather use gist's builtin access_token, then you can force the user +* If you'd rather use gist's builtin access_token, then you can force the user to obtain one by calling: Gist.login! @@ -195,12 +193,12 @@ in `~/.gist`, where it can later be read by `Gist.gist` ## Configuration -If you'd like `-o` or `-c` to be the default when you use the gist executable, add an +* If you'd like `-o` or `-c` to be the default when you use the gist executable, add an alias to your `~/.bashrc` (or equivalent). For example: alias gist='gist -c' -If you'd prefer gist to open a different browser, then you can export the BROWSER +* If you'd prefer gist to open a different browser, then you can export the BROWSER environment variable: export BROWSER=google-chrome diff --git a/Rakefile b/Rakefile index 006f559..cb3e0dd 100644 --- a/Rakefile +++ b/Rakefile @@ -11,9 +11,7 @@ end task :man do mkdir_p "build" - File.write "README.md.ron", File.read("README.md").gsub("\u200c", "* ") - sh 'ronn --roff --manual="Gist manual" README.md.ron' - rm 'README.md.ron' + sh 'ronn --roff --manual="Gist manual" README.md' mv 'README.1', 'build/gist.1' end From 4c5aa4532d72fd2c2641b6da054211059363b49e Mon Sep 17 00:00:00 2001 From: Lucas Magasweran Date: Wed, 16 Sep 2020 16:33:04 +0200 Subject: [PATCH 4/5] docs: man: workaround ronn Markdown bug The triple backtick code block was confusing `ronn` causing the token section to flow into the library section. ``` Token file format If you cannot use passwords, as most Enterprise installations do, you can generate the token via the web interface and then simply save the string in the correct file. Avoid line breaks or you might see: $ gist -l Error: Bad credentials You can also use Gist as a library from inside your ruby code: ``` --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 08b7263..c14e519 100644 --- a/README.md +++ b/README.md @@ -156,10 +156,9 @@ setting it to the public URL will not work. Use `unset GITHUB_URL` If you cannot use passwords, as most Enterprise installations do, you can generate the token via the web interface and then simply save the string in the correct file. Avoid line breaks or you might see: -``` -$ gist -l -Error: Bad credentials -``` + + $ gist -l + Error: Bad credentials # Library From 545d204b92b14933ef7fe7695f365a8b2e96b64b Mon Sep 17 00:00:00 2001 From: Lucas Magasweran Date: Wed, 16 Sep 2020 16:38:43 +0200 Subject: [PATCH 5/5] docs: man: ronn doesn't like h4 Fix the following by not using `####` (h4) in Markdown ``` $ ronn --roff --manual="Gist manual" README.md warn: unrecognized block tag: "h4" ``` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c14e519..ef7c9f4 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ This token is stored in `~/.gist` and used for all future gisting. If you need t you can revoke it from https://github.com/settings/tokens, or just delete the file. -#### Password-less login +### Password-less login If you have a complicated authorization requirement you can manually create a token file by pasting a GitHub token with `gist` scope (and maybe the `user:email`