Using gc

Command Line

gc is started with a command line like

gc *options* *url*

It opens the url (if present) and enters loop where user commands are read and interpreted. url is expected to have the usual protocol identifier. If not url

• is interpreted as file if it starts with one or two dots followed by a slash (i.e. ./ or ../),

• gets %09%09+ appended if it ends with a +,

• is taken as gopher address if it doesn't have a dot .,

• gets the protocol http, gopher or gemini assigned if it starts with www, gopher or gemini respecively.

If no url is given on the command line but a home page is configured gc opens that file.

gc uses a simple interactive line interface: the user enters commands and gc executes them. gc comes without a command line editor. If you want this, use rlwrap (sudo apt-get install rlwrap):

rlwrap ./gc

Notice that Ctrl+C will end gc without a proper cleanup. That is, the temporary file that is used during a gc session is not removed.

Configuration File

When starting gc tries to read configuration options from the file .config.gc or (if that not works) ~/.config/gc/config. Empty lines or comments (lines starting with a #) are allowed. The following options are recognized:

bookmarks fn

set the bookmarks file.

enable key

enables one of gc's interface options.

home url

set the home page, which is loaded from the home command or if no url parameter is given on the command line.

Unknown option print an error message and terminate gc.

If the bookmarks file is not set gc uses ~/.config/gc/bookmarks if the configuration was read from there and .bookmarks.gc else.

Protocols and Content-Types

gc understands the following protocols / URL schemes:

• gopher and gopher+
• http/s
• gemini
• file

Several text types can be reformatted using helper programs, which should be available.

gem2text and md2text come with gc and lynx is expected to be installed. For Markdown, md2text extracts only [text](url "title") links but leaves the text itself as-is.

Moving Around

Navigation is simple. Most often it starts with entering a URL at the command prompt, e.g.

> gopher://gopher.floodgap.com/

gc loads and display the content. Gopher directory item selectors are numbered and entering the number will take you there:

> 21

opens Floodgap's "getting started" directory. Notice that each item that gc displays is paged using less and depending on the text length the display may stay in paging mode until you end this by entering q. gc is ready when you see the > prompt.

gc can render text/html (using lynx -dump) and gemtext (gmi2text utility) and extracts URL from them. These are also numbered and selected by entering their number. Links from the last content file are listed (as URLs) with gc's ref command.

Gopher directories are not considered as content but as navigation. This has the side effect that loading an item does not override the contents of the last visited gopher directory. Try these commands:

> gopher://gopher.floodgap.com/
> gemini://gemini.circumlunar.space/
> ls

There are two more link sources and all of them are selected with their index number: the history and gopher+ attribut blocks. Each time you enter a number to open a link, gc checks which item was displayed last and takes the link from the respective object. These are the commands to display and switch to their context:

Navigation

gc supports a simple prev/next navigation. All files that have no special relation (set by +ADMIN.Relation) and are not downloads are numbered in the order as they appear in the directory. The commands

:(first|prev|next|last)

can be used to move around. Use :rel to display the document with a particular relation, e.g. :home.

Gopher+ servers may supply prev/next information in the +RELATION block but this is currently ignored by gc. It computes the information on its own.

The option -e pnx activates an experimental prev/next. After a document has been shown the navigator prompts for one of the available prev/next actions. Simply pressing return brings you to gc command prompt.

Command Overview

Command name that are enclosed in parenthesis can be abbreviated. Entering as much that the command can be uniquely identified is enough, e.g. pa instead of page..

n+

opens link number n from the current context, which can be the current gopher directory, an item's Gopher+ plus information, references from the current item or the history. The prompt indicates the context. If a + is appended the item is opened in a new xterminal (requires X windows).

:n+

opens link number n from the current gopher directory.

url

loads url; see also open.

dir

modifies to current item's address to guess its directory address and load it.

help

print brief command overview.

(history) [ num | regex ]

list the items in the current history (matching regex) or load entry num.

(ls) [ regex ]

list all items from the curent directory (matching regex).

(open) url

opens url, which might be relative to the current location.

(page)

print the current loaded item if it is a text item.

quit

end gc.

(ref)

list references from the current (html or gemtext) item. An item can be loaded by entering its number.

save [ fn ]

save the current item to fn.

(top)

load the root (i.e. the / directory) of the current server's directory. Does not properly work with Gopher-by-HTTP.

..

load the previous item.

==

show the current item's URL.

Bookmarks

'[ label ]

loads bookmark label.

' [ regex ]

lists all bookmarks or all bookmarks matching regex.

(mark) label [ title ]

creates a bookmark for the current item.

Commands requiring Gopher+

num=

displays the Gopher+ information for directory item num.

:(rel)+

opens the item's link with relation rel.

edit [num]

edits directory item num by reading an writing to the gopher+ representation "+application/markup-source".

(upload) [ local [ remote ] ]

stores the local file fn as remote on the server writing the data to remote%09+PUT.

Commands requiring an X-session

+num

opens link num in a new xterminal.

dup

duplicate the current item into a new xterminal.

Command Line Options

Possible options are

-e key

enables gc user interface options.

-f fn

reads configuration options from fn.

-l libpath

sets the path to gc's helper program md2text etc. This is usually automaically computed.

-V

prints gc's version and exits.

gc's current working directory is important. This is the location where is stores it bookmarks (in the file .bookmarks.gc) and its temporary file. This is only removed on clean exit, not when gc is terminated with CTRL+C or similar.

Notes

When using gc as gopher client there are some things you should know.

• gc is a working gopher client but it is not complete in every aspect. E.g. it does not handle HTTP and gemini redirects (yet). These things will be added later. gc is still useful because the most important things work and being a gopher client is not the only goal. The other main idea behind gc is to have a working client to prototype and show additional functionality.

• gc is written in gawk. This is not the best choice because gawk is for text processing and gopher is also about transferring binary data. Although the problems I expected (e.g. downloaded binary data) did not appear there might be situations, where gc has problems with binary data. I chose gawk because it's a language I know very well and I also think it is easy to understand even if you are new to it.