commit 53586a2ec47dc79d2a0711aedb4fe96e80fc852b
parent 07d509cd734c42739aa07ce8653b6220c064f561
Author: Ed van Bruggen <edvb@uw.edu>
Date: Sat, 28 Mar 2020 13:53:20 -0700
Update README, generate man page with markman
Diffstat:
| Makefile | | | 15 | ++++----------- |
| README.md | | | 103 | ++++++++++++++++++++++++++++++++++++++++++++++++------------------------------- |
| config.def.h | | | 8 | ++++---- |
| gs.1 | | | 118 | +++++++++++++++++++++++++++++++++++++++++++++++-------------------------------- |
4 files changed, 141 insertions(+), 103 deletions(-)
diff --git a/Makefile b/Makefile
@@ -43,7 +43,7 @@ install: all
@chmod 755 $(DESTDIR)$(PREFIX)/bin/$(EXE)
@echo installing manual page to $(DESTDIR)$(MANPREFIX)/man1
@mkdir -p $(DESTDIR)$(MANPREFIX)/man1
- @sed "s/VERSION/$(VERSION)/g" < $(EXE).1 > $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
+ @cp -f $(EXE).1 $(DESTDIR)$(MANPREFIX)/man1/
@chmod 644 $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
uninstall:
@@ -52,16 +52,9 @@ uninstall:
@echo -n removing manual page from $(DESTDIR)$(MANPREFIX)/man1
@rm -f $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
-man:
+man: $(EXE)
@echo updating man page $(EXE).1
- @(head -1 README.md | sed "s/$(EXE)/$(EXE) 1 \"`date +%B\ %Y`\" \"$(EXE)\ $(VERSION)\"\n\n##NAME\n\n&/"; \
- echo "\n##SYNOPSIS\n"; \
- ./$(EXE) -h 2>&1 | sed -E 's/(\<[_A-Z][_A-Z]+\>)/\*\1\*/g' | \
- sed -E 's/(-[a-Z]+\>)/\*\*\1\*\*/g' | \
- sed -E 's/(\<$(EXE)\>)/\*\*\1\*\*/g' | \
- sed 's/_/\\_/g' | sed 's/:/:\ /g'| cut -d' ' -f2-; \
- echo "\n##DESCRIPTION"; \
- tail +2 README.md;) | \
- md2roff - | sed "9s/]/]\ /g" | sed "9s/|/|\ /g" > $(EXE).1
+ @markman -nCD -t GS -V "$(EXE) $(VERSION)" -d "`date '+%B %Y'`" \
+ -s "`./$(EXE) -h 2>&1 | cut -d' ' -f2-`" README.md > $(EXE).1
.PHONY: all options clean install uninstall man
diff --git a/README.md b/README.md
@@ -1,45 +1,46 @@
# gs \- painless gist creator
-Easy way to create GitHub Gists through the command line.
+Easy way to create GitHub Gists through the command line. Simply give it the
+files to upload and gs will return the URL to the new gist.
-## OPTIONS
+## Options
-#### -e ID
+#### -e *ID*
-Edit previously created Gist specified with *ID*
+Edit previously created gist specified with *ID*
-#### -d DESCRIPTION
+#### -d *DESCRIPTION*
-Set Gist description
+Set gist description
-#### -D FILE
+#### -D *FILE*
-Delete *FILE* from Gist being edited
+Delete *FILE* from gist being edited
-#### -f FILENAME
+#### -f *FILENAME*
Set file name when reading from `stdin`
-#### -g GITHUB_URL
+#### -g *URL*
-Change the GitHub API URL
+Change the GitHub API URL (default: https://api.github.com/gists)
#### -p
-Make Gist private
+Make gist private
#### -P
-Make Gist public (default)
+Make gist public (default)
-#### -u USER[:PASSWORD]
+#### -u *USER[:PASSWORD]*
-Change the GitHub account the Gist will be posted under. A password can
+Change the GitHub account the gist will be posted under. A password can
given as well with a separating colon, a prompt is provided if not.
#### -U
-Post Gist anonymously (default)
+Post gist anonymously (default)
#### -h
@@ -49,37 +50,37 @@ Print help and exit
Print version info and exit
-## USAGE
+## Usage
-Create a new Gist of file `file.txt`:
+Create a new gist of `file.txt`:
```
$ gs file.txt
https://gist.github.com/<new-id>
```
-There is also support for multiple files in a single Gist:
+There is also support for multiple files in a single gist:
```
$ gs README.md Makefile prog.c
https://gist.github.com/<new-id>
```
-Specify the Gist's description:
+Specify the gist's description:
```
$ gs -d 'a cool shell script' script.sh
https://gist.github.com/<new-id>
```
-The Gist's URL can be piped to other programs, for example to your clipboard to
-be pasted else where:
+The gist's URL can be piped to other programs, for example to your clipboard to
+be pasted elsewhere:
```
$ gs file.txt | xsel -bi
```
-You can also create a new Gist from `stdin`. The file name needs to be supplied
+You can also create a new gist from `stdin`. The file name needs to be supplied
however:
```
@@ -87,14 +88,7 @@ $ cmd-which-errors | gs -f log.txt
https://gist.github.com/<new-id>
```
-New Gists can be private as well:
-
-```
-$ gs -p personal.info
-https://gist.github.com/<new-id>
-```
-
-The new Gist can be posted under a GitHub user, a prompt will ask for your
+The new gist can be posted under a GitHub user, a prompt will ask for your
password:
```
@@ -111,23 +105,52 @@ $ gs -u your-name:password plugin/func.vim doc/func.txt
https://gist.github.com/<new-id>
```
-## CUSTOMIZATION
+New gists can be private when created under a user:
+
+```
+$ gs -p -u name personal.info
+https://gist.github.com/<new-id>
+```
+
+You can also edit a previously created gist under your account, such as adding
+a new file or updating the description:
+
+```
+$ gs -e <id> -u name -d "new description" additional-file.txt
+https://gist.github.com/<id>
+```
+
+It is even possible to delete files, although it should be noted the gist still
+exists even if you delete all the files within it due to the limitations of the
+API:
+
+```
+$ gs -e <id> -u name -D old.py
+https://gist.github.com/<id>
+```
+
+## Installation
+
+The only dependency needed to build gs is cURL. gs be compiled with a simple
+`make` and `sudo make install` will install the executable and man page.
+
+## Customization
-gs is customized by creating a custom `config.h` and (re)compiling the source
-code. This keeps it fast, secure and simple. Most customization can be done
-through the command line interface however, so basic aliases could also be
-utilized.
+gs can be customized by editing the custom `config.h` and (re)compiling the
+source code. This keeps it fast, secure and simple. All customization can be
+done through the command line interface however, so basic aliases could also be
+utilized to change default options.
-## AUTHOR
+## Author
Ed van Bruggen <ed@edryd.org>
-## SEE ALSO
+## See Also
See project page at <https://edryd.org/projects/gs.html>
-View source code at <https://github.com/edvb/gs>
+View source code at <https://git.edryd.org/gs>
-## LICENSE
+## License
zlib License
diff --git a/config.def.h b/config.def.h
@@ -1,7 +1,7 @@
-char *gist = NULL; /* ID of existing Gist to edit */
-char *desc = NULL; /* Gist description */
-char *del = NULL; /* file name to delete from Gist */
-char *fname = NULL; /* Gist filename when reading from stdin */
+char *gist = NULL; /* ID of existing gist to edit */
+char *desc = NULL; /* gist description */
+char *del = NULL; /* file name to delete from gist */
+char *fname = NULL; /* gist filename when reading from stdin */
char *user = NULL; /* GitHub user, password can be given after colon */
char *ghurl = "https://api.github.com/gists"; /* GitHub URL to post gists to */
int pub = 1; /* 0: private need link to view, 1: public anyone can find */
diff --git a/gs.1 b/gs.1
@@ -1,63 +1,63 @@
-.\" x-roff document
-.do mso man.tmac
-.TH gs 1 "August 2017" "gs 0.0.0"
+.TH GS 1 "March 2020" "gs 0.0.0"
.PP
.SH NAME
-gs - painless gist creator
+gs \- painless gist creator
.PP
.SH SYNOPSIS
-\fBgs\fP [\fB-pPhv\fP] [\fB-e\fP \fIID\fP [\fB-D\fP \fIFILE\fP] ] [\fB-d\fP \fIDESCRIPTION\fP] [\fB-f\fP \fIFILENAME\fP] [\fB-g\fP \fIGITHUB_URL\fP] [\fB-u\fP \fIUSER\fP[:\fIPASSWORD\fP] | \fB-U\fP] \fIFILES\fP ...
+gs [-pPhv] [-e ID [-D FILE]] [-d DESCRIPTION] [-f FILENAME] [-g GITHUB_URL] [-u USER[:PASSWORD] | -U] FILES ...
.PP
.SH DESCRIPTION
-Easy way to create GitHub Gists through the command line.
+.PP
+Easy way to create GitHub Gists through the command line. Simply give it the files to upload and gs will return the URL to the new gist.
.PP
.SH OPTIONS
.TP
-\fB-e\fP \fIID\fP
-\fREdit previously created Gist specified with \fIID\fP
+\fB-e \fP\fIID\fP
+Edit previously created Gist specified with \fIID\fP
.PP
.TP
-\fB-d\fP \fIDESCRIPTION\fP
-\fRSet Gist description
+\fB-d \fP\fIDESCRIPTION\fP
+Set Gist description
.PP
.TP
-\fB-D\fP \fIFILE\fP
-\fRDelete \fIFILE\fP from Gist being edited
+\fB-D \fP\fIFILE\fP
+Delete \fIFILE\fP from Gist being edited
.PP
.TP
-\fB-f\fP \fIFILENAME\fP
-\fRSet file name when reading from `\f[CR]stdin\fP'
+\fB-f \fP\fIFILENAME\fP
+Set file name when reading from 'stdin'
.PP
.TP
-\fB-g\fP \fIGITHUB_URL\fP
-\fRChange the GitHub API URL
+\fB-g \fP\fIURL\fP
+Change the GitHub API URL (default: https://api.github.com/gists)
.PP
.TP
-\fB-p
-\fRMake Gist private
+\fB-p\fP
+Make Gist private
.PP
.TP
-\fB-P
-\fRMake Gist public (default)
+\fB-P\fP
+Make Gist public (default)
.PP
.TP
-\fB-u\fP \fIUSER\fP[:\fIPASSWORD\fP]
-\fRChange the GitHub account the Gist will be posted under. A password can given as well with a separating colon, a prompt is provided if not.
+\fB-u \fP\fIUSER\fP:PASSWORD
+Change the GitHub account the Gist will be posted under. A password can given as well with a separating colon, a prompt is provided if not.
.PP
.TP
-\fB-U
-\fRPost Gist anonymously (default)
+\fB-U\fP
+Post Gist anonymously (default)
.PP
.TP
-\fB-h
-\fRPrint help and exit
+\fB-h\fP
+Print help and exit
.PP
.TP
-\fB-v
-\fRPrint version info and exit
+\fB-v\fP
+Print version info and exit
.PP
.SH USAGE
-Create a new Gist of file `\f[CR]file.txt\fP':
+.PP
+Create a new gist of 'file.txt':
.PP
.RS 4
.EX
@@ -67,8 +67,7 @@ https://gist.github.com/<new-id>
.EE
.RE
-.PP
-There is also support for multiple files in a single Gist:
+There is also support for multiple files in a single gist:
.PP
.RS 4
.EX
@@ -78,8 +77,7 @@ https://gist.github.com/<new-id>
.EE
.RE
-.PP
-Specify the Gist's description:
+Specify the gist's description:
.PP
.RS 4
.EX
@@ -89,8 +87,7 @@ https://gist.github.com/<new-id>
.EE
.RE
-.PP
-The Gist's URL can be piped to other programs, for example to your clipboard to be pasted else where:
+The gist's URL can be piped to other programs, for example to your clipboard to be pasted elsewhere:
.PP
.RS 4
.EX
@@ -99,8 +96,7 @@ $ gs file.txt | xsel -bi
.EE
.RE
-.PP
-You can also create a new Gist from `\f[CR]stdin\fP'. The file name needs to be supplied however:
+You can also create a new gist from 'stdin'. The file name needs to be supplied however:
.PP
.RS 4
.EX
@@ -110,51 +106,77 @@ https://gist.github.com/<new-id>
.EE
.RE
-.PP
-New Gists can be private as well:
+The new gist can be posted under a GitHub user, a prompt will ask for your password:
.PP
.RS 4
.EX
-$ gs -p personal.info
+$ gs -u your-name good-proj.rs
+GitHub password:
https://gist.github.com/<new-id>
.EE
.RE
+To skip the prompt your password can be supplied after a colon with the username:
.PP
-The new Gist can be posted under a GitHub user, a prompt will ask for your password:
+.RS 4
+.EX
+
+$ gs -u your-name:password plugin/func.vim doc/func.txt
+https://gist.github.com/<new-id>
+
+.EE
+.RE
+New gists can be private when created under a user:
.PP
.RS 4
.EX
-$ gs -u your-name good-proj.rs
-GitHub password:
+$ gs -p -u name personal.info
https://gist.github.com/<new-id>
.EE
.RE
+You can also edit a previously created gist under your account, such as adding a new file or updating the description:
.PP
-To skip the prompt your password can be supplied after a colon with the username:
+.RS 4
+.EX
+
+$ gs -e <id> -u name -d "new description" additional-file.txt
+https://gist.github.com/<id>
+
+.EE
+.RE
+It is even possible to delete files, although it should be noted the gist still exists even if you delete all the files within it due to the limitations of the API:
.PP
.RS 4
.EX
-$ gs -u your-name:password plugin/func.vim doc/func.txt
-https://gist.github.com/<new-id>
+$ gs -e <id> -u name -D old.py
+https://gist.github.com/<id>
.EE
.RE
+.SH INSTALLATION
+.PP
+The only dependency needed to build gs is cURL. gs be compiled with a simple 'make' and 'sudo make install' will install the executable and man page.
.PP
.SH CUSTOMIZATION
-gs is customized by creating a custom `\f[CR]config.h\fP' and (re)compiling the source code. This keeps it fast, secure and simple. Most customization can be done through the command line interface however, so basic aliases could also be utilized.
+.PP
+gs can be customized by editing the custom 'config.h' and (re)compiling the source code. This keeps it fast, secure and simple. All customization can be done through the command line interface however, so basic aliases could also be utilized to change default options.
.PP
.SH AUTHOR
+.PP
Ed van Bruggen <ed@edryd.org>
.PP
.SH SEE ALSO
+.PP
See project page at <https://edryd.org/projects/gs.html>
.PP
-View source code at <https://github.com/edvb/gs>
+View source code at <https://git.edryd.org/gs>
.PP
.SH LICENSE
+.PP
zlib License
+.PP
+
