From dc1f48e91742ca6d5605b6351da4b812e5e1c8fd Mon Sep 17 00:00:00 2001 From: chris west Date: Sat, 9 May 2020 13:17:49 -0700 Subject: [PATCH] basic manpage --- Makefile | 12 ++++ README.md | 2 +- doc/phd.1 | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/phd.1.md | 151 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 364 insertions(+), 1 deletion(-) create mode 100644 doc/phd.1 create mode 100644 doc/phd.1.md diff --git a/Makefile b/Makefile index 71c09b2..9ff2849 100644 --- a/Makefile +++ b/Makefile @@ -34,3 +34,15 @@ $(RELEASE): $(SOURCES) # Build the debug version $(DEBUG): $(SOURCES) cargo build + +# Build manual +.PHONY: manual +manual: doc/phd.1 + +doc/phd.1: doc/phd.1.md scdoc + scdoc < doc/phd.1.md > doc/phd.1 + +# Must have scdoc installed to build manual. +scdoc: + @which scdoc || (echo "scdoc(1) not found."; \ + echo "please install to build the manual: https://repology.org/project/scdoc"; exit 1) diff --git a/README.md b/README.md index 4962028..578a220 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Point it at a directory and it'll serve up all the text files, sub-directories, and binary files over Gopher. Any `.gph` files will -be served up as [gopermaps][map] and executable `.gph` files will be +be served up as [gophermaps][map] and executable `.gph` files will be run as a program with their output served to the client, like the glorious cgi-bin days of yore! diff --git a/doc/phd.1 b/doc/phd.1 new file mode 100644 index 0000000..7960f96 --- /dev/null +++ b/doc/phd.1 @@ -0,0 +1,200 @@ +.\" Generated by scdoc 1.10.0 +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "PHD" "1" "2020-05-09" +.P +.SH NAME +.P +phd - an estoeric gopher server +.P +.SH SYNOPSIS +.P +\fBphd\fR [\fIOPTIONS\fR] [\fISITE ROOT\fR] +.P +.SH DESCRIPTION +.P +\fBphd\fR is a small, easy-to-use gopher server. +.P +Point it at a directory and it'll serve up all the text files, +sub-directories, and binary files over Gopher. Any \fB.gph\fR files will +be served up as Gophermaps and executable \fB.gph\fR files will be +run as a program with their output served to the client, like the +glorious cgi-bin days of yore! +.P +Usually \fBphd\fR is started with a path to your Gopher site: +.P +.RS 4 +phd /srv/gopher +.P +.RE +If no path is given, \fBphd\fR will use the current directory as the root +of your Gopher site. +.P +.SH OPTIONS +.P +\fB-r\fR \fISELECTOR\fR, \fB--render\fR \fISELECTOR\fR +.P +.RS 4 +Rather than start as a server, render the \fISELECTOR\fR of the site using the options provided and print the raw response to \fBSTDOUT\fR. +.P +.RE +\fB-p\fR \fIPORT\fR, \fB--port\fR \fIPORT\fR +.RS 4 +Set the \fIPORT\fR to use when generating Gopher links. +.P +.RE +\fB-h\fR \fIHOST\fR, \fB--host\fR \fIHOST\fR +.RS 4 +Set the \fIHOST\fR to use when generating Gopher links. +.P +.RE +\fB-h\fR, \fB--help\fR +.RS 4 +Print a help summary and exit. +.P +.RE +\fB-v\fR, \fB--version\fR +.RS 4 +Print version information and exit. +.P +.RE +.SH SPECIAL FILES +.P +The following files have special behavior when present in a directory +that \fBphd\fR is tasked with serving: +.P +\fBheader.gph\fR +.RS 4 +If it exists in a directory, its content will be shown above the directory's content. Put ASCII art in it. +.P +.RE +\fBfooter.gph\fR +.RS 4 +Same, but will be shown below a directory's content. +.P +.RE +\fBindex.gph\fR +.RS 4 +Completely replaces a directory's content with what's in this file. +.P +.RE +\fB??.gph\fR +.RS 4 +Visiting \fBgopher://yoursite/1/dog/\fR will try to render \fBdog.gph\fR from disk. Visiting \fB/1/dog.gph\fR will render the raw content of the .gph file. +.P +.RE +\fB.reverse\fR +.RS 4 +If this exists, the directory contents will be listed in reverse alphanumeric order. Useful for phloggin', if you date your posts. +.P +.RE +.SH GOPHERMAP SYNTAX +.P +Any line in a \fB.gph\fR file that doesn't contain tabs (\fBt\fR) will get an +\fBi\fR automatically prefixed, turning it into a Gopher information item. +.P +For your convenience, phd supports \fBgeomyidae\fR syntax for +creating links: +.P +.nf +.RS 4 +This is an info line\&. +[1|This is a link|/help|server|port] +[h|URL Link|URL:https://noogle\&.com] +.fi +.RE +.P +\fBserver\fR and \fBport\fR will get translated into the server and port of +the actively running server, eg \fBlocalhost\fR and \fB7070\fR. +.P +Any line containing a tab character (\fBt\fR) will be sent as-is to the +client, meaning you can write and serve up raw Gophermap files too. +.P +.SH DYNAMIC CONTENT +.P +Any \fB.gph\fR file that is marked \fBexecutable\fR with be run as if it +were a standalone program and its output will be sent to the client. +It will be passed three arguments: the query string (if any), the +server's hostname, and the current port. Do with them what you will. +.P +For example: +.P +.nf +.RS 4 +$ cat echo\&.gph +#!/bin/sh +echo "Hi, world! You said:" $1 +echo "1Visit Gopherpedia / gopherpedia\&.com 70" +.fi +.RE +.P +Then: +.P +.nf +.RS 4 +$ gopher-client gopher://localhost/1/echo?something +[INFO] Hi, world! You said: something +[LINK] Visit Gopherpedia +.fi +.RE +.P +Or more seriously: +.P +.nf +.RS 4 +$ cat figlet\&.gph +#!/bin/sh +figlet $1 +.fi +.RE +.P +then: +.P +.nf +.RS 4 +$ gopher-client gopher://localhost/1/figlet?hi gopher +[INFO] _ _ _ +[INFO] | |__ (_) __ _ ___ _ __ | |__ ___ _ __ +[INFO] | '_ | | / _` |/ _ | '_ | '_ / _ '__| +[INFO] | | | | | | (_| | (_) | |_) | | | | __/ | +[INFO] |_| |_|_| __, |___/| \&.__/|_| |_|___|_| +[INFO] |___/ |_| +.fi +.RE +.P +.SS RESOURCES +.P +geomyidae source code +.RS 4 +gopher://bitreich.org/1/scm/geomyidae/files.gph +.P +.RE +Example Gophermap +.RS 4 +https://github.com/gophernicus/gophernicus/blob/master/README.Gophermap +.P +.RE +Gophermaps +.RS 4 +https://gopher.zone/posts/how-to-gophermap/ +.P +.RE +RFC 1436: +.RS 4 +https://tools.ietf.org/html/rfc1436 +.P +.RE +.SH ABOUT +.P +\fBphd\fR is maintained by chris west and released under the MIT license. +.P +phd's Gopher hole: +.RS 4 +\fIgopher://phkt.io/1/phd\fR +.RE +phd's webpage: +.RS 4 +\fIhttps://github.com/xvxx/phd\fR diff --git a/doc/phd.1.md b/doc/phd.1.md new file mode 100644 index 0000000..8e8a365 --- /dev/null +++ b/doc/phd.1.md @@ -0,0 +1,151 @@ +PHD(1) + +# NAME + +phd - an estoeric gopher server + +# SYNOPSIS + +*phd* [_OPTIONS_] [_SITE ROOT_] + +# DESCRIPTION + +*phd* is a small, easy-to-use gopher server. + +Point it at a directory and it'll serve up all the text files, +sub-directories, and binary files over Gopher. Any *.gph* files will +be served up as Gophermaps and executable *.gph* files will be +run as a program with their output served to the client, like the +glorious cgi-bin days of yore! + +Usually *phd* is started with a path to your Gopher site: + + phd /srv/gopher + +If no path is given, *phd* will use the current directory as the root +of your Gopher site. + +# OPTIONS + +*-r* _SELECTOR_, *--render* _SELECTOR_ + + Rather than start as a server, render the _SELECTOR_ of the site using the options provided and print the raw response to *STDOUT*. + +*-p* _PORT_, *--port* _PORT_ + Set the _PORT_ to use when generating Gopher links. + +*-h* _HOST_, *--host* _HOST_ + Set the _HOST_ to use when generating Gopher links. + +*-h*, *--help* + Print a help summary and exit. + +*-v*, *--version* + Print version information and exit. + +# SPECIAL FILES + +The following files have special behavior when present in a directory +that *phd* is tasked with serving: + +*header.gph* + If it exists in a directory, its content will be shown above the directory's content. Put ASCII art in it. + +*footer.gph* + Same, but will be shown below a directory's content. + +*index.gph* + Completely replaces a directory's content with what's in this file. + +*??.gph* + Visiting *gopher://yoursite/1/dog/* will try to render *dog.gph* from disk. Visiting */1/dog.gph* will render the raw content of the .gph file. + +*.reverse* + If this exists, the directory contents will be listed in reverse alphanumeric order. Useful for phloggin', if you date your posts. + +# GOPHERMAP SYNTAX + +Any line in a *.gph* file that doesn't contain tabs (*\t*) will get an +*i* automatically prefixed, turning it into a Gopher information item. + +For your convenience, phd supports *geomyidae* syntax for +creating links: + +``` +This is an info line. +[1|This is a link|/help|server|port] +[h|URL Link|URL:https://noogle.com] +``` + +*server* and *port* will get translated into the server and port of +the actively running server, eg *localhost* and *7070*. + +Any line containing a tab character (*\t*) will be sent as-is to the +client, meaning you can write and serve up raw Gophermap files too. + +# DYNAMIC CONTENT + +Any *.gph* file that is marked *executable* with be run as if it +were a standalone program and its output will be sent to the client. +It will be passed three arguments: the query string (if any), the +server's hostname, and the current port. Do with them what you will. + +For example: + +``` +$ cat echo.gph +#!/bin/sh +echo "Hi, world! You said:" $1 +echo "1Visit Gopherpedia / gopherpedia.com 70" +``` + +Then: + +``` +$ gopher-client gopher://localhost/1/echo?something +[INFO] Hi, world! You said: something +[LINK] Visit Gopherpedia +``` + +Or more seriously: + +``` +$ cat figlet.gph +#!/bin/sh +figlet $1 +``` + +then: + +``` +$ gopher-client gopher://localhost/1/figlet?hi gopher +[INFO] _ _ _ +[INFO] | |__ (_) __ _ ___ _ __ | |__ ___ _ __ +[INFO] | '_ \| | / _` |/ _ \| '_ \| '_ \ / _ \ '__| +[INFO] | | | | | | (_| | (_) | |_) | | | | __/ | +[INFO] |_| |_|_| \__, |\___/| .__/|_| |_|\___|_| +[INFO] |___/ |_| +``` + +## RESOURCES + +geomyidae source code + gopher://bitreich.org/1/scm/geomyidae/files.gph + +Example Gophermap + https://github.com/gophernicus/gophernicus/blob/master/README.Gophermap + +Gophermaps + https://gopher.zone/posts/how-to-gophermap/ + +RFC 1436: + https://tools.ietf.org/html/rfc1436 + +# ABOUT + +*phd* is maintained by chris west and released under the MIT license. + +phd's Gopher hole: + _gopher://phkt.io/1/phd_ +phd's webpage: + _https://github.com/xvxx/phd_