summary refs log tree commit diff
path: root/spacecookie.gophermap.5.html
blob: cf150c3e6f688e59aa949acf1f10d23dc26e3421 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <link rel="stylesheet" href="style.css" type="text/css" media="all"/>
  <title>SPACECOOKIE.GOPHERMAP(5)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">SPACECOOKIE.GOPHERMAP(5)</td>
    <td class="head-vol">File Formats Manual</td>
    <td class="head-rtitle">SPACECOOKIE.GOPHERMAP(5)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">spacecookie.gophermap</code> &#x2014;
    <span class="Nd">gophermap file format supported by
    <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a></span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">A gophermap file allows to describe a gopher menu without the need
    to include redundant information. The format supported by
    <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> has originally
    been introduced by Bucktooth and is supported by most popular gopher server
    daemons like for example
    <a class="Xr" href="https://manpages.debian.org/unstable/pygopherd.8.en.html">pygopherd(8)</a>.</p>
<p class="Pp">A gophermap file stored as
    &#x2018;<code class="Li">.gophermap</code>&#x2019; in a directory under the
    gopher root of <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>
    is parsed and used as a gopher menu instead of the automatically generated
    default variant. This allows users to customize the directory listings by
    specifying informational text, links to files, (other) directories, gopher
    servers or protocols themselves.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FORMAT"><a class="permalink" href="#FORMAT">FORMAT</a></h1>
<p class="Pp">The format is plain text and line based. Both Unix and DOS style
    line endings are allowed.
    <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> distinguishes
    between two types of lines:</p>
<dl class="Bl-tag">
  <dt id="info"><a class="permalink" href="#info"><b class="Sy">info
    lines</b></a></dt>
  <dd>Info lines are lines of text in a gophermap which don't have any special
      format requirements except that they may not contain any tab characters.
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">Any text which may contain
      anything but tabs.</code></div>
    <p class="Pp">They are also rendered als plain text without any associated
        links to gopher clients which support them. Info lines are technically
        not part of the gopher protocol nor mentioned in RFC1436, but this
        protocol extension is widely supported and used.</p>
    <p class="Pp">The usual purpose is to display additional text, headings and
        decorative elements which are not directly related to other resources
        served via gopher:</p>
    <div class="Bd Pp Bd-indent Li">
    <pre>+------------------------------+
| Welcome to my Gopher Server! |
+------------------------------+

Below you can find a collection of files I deemed
interesting or useful enough to publish them.</pre>
    </div>
    <p class="Pp">Empty lines are interpreted as info lines which have no
        content.</p>
  </dd>
  <dt id="menu"><a class="permalink" href="#menu"><b class="Sy">menu
    entries</b></a></dt>
  <dd>Lines describing menu entries are of the following form. All spaces are
      for readability only and must not be present in the actual format.
      Everything in brackets may be omitted, the semantics of which are
      explained below.
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">gopherfiletypeNAME\t [SELECTOR
      [\tSERVER [\tPORT]]]</code></div>
    <dl class="Bl-tag">
      <dt id="gopherfiletype"><a class="permalink" href="#gopherfiletype"><i class="Em">gopherfiletype</i></a></dt>
      <dd>File type character indicating the file type of the linked resource to
          the client. See
          <a class="Lk" href="https://tools.ietf.org/html/rfc1436#page-14">RFC1436</a>
          for a list of valid file types. Additionally,
          <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> supports
          &#x2018;<code class="Li">i</code>&#x2019; which indicates an info line
          and &#x2018;<code class="Li">h</code>&#x2019; which indicates an HTML
          document.</dd>
      <dt id="NAME~2"><a class="permalink" href="#NAME~2"><i class="Em">NAME</i></a></dt>
      <dd>Name of the linked resource which will show up as the text of the menu
          entry. May contain any characters except newlines and tabs.
          <i class="Em">NAME</i> must always be terminated by a tab.</dd>
      <dt id="SELECTOR"><a class="permalink" href="#SELECTOR"><i class="Em">SELECTOR</i></a></dt>
      <dd>Gopher selector the entry should link to. Same restrictions in terms
          of characters apply as for <i class="Em">NAME</i>, but there should
          only be a tab character afterwards if another field is specified. If
          it is omitted, the value of <i class="Em">NAME</i> is used. If the
          <i class="Em">SELECTOR</i> starts with
          &#x2018;<code class="Li">/</code>&#x2019;, it is interpreted as an
          absolute path and given to the client as-is. If it starts with
          &#x2018;<code class="Li">URL:</code>&#x2019;, it is assumed that it is
          a link to another protocol and passed to the client without
          modification (see below). In all other cases, it is assumed that the
          selector is a relative path and is converted to an absolute path
          before serving the menu to a client.
        <p class="Pp">You can read more about
            &#x2018;<code class="Li">URL:</code>&#x2019; links which are another
            common gopher protocol extension in
            <a class="Lk" href="http://gopher.quux.org:70/Archives/Mailing%20Lists/gopher/gopher.2002-02%7C/MBOX-MESSAGE/34">this
            email from John Goerzen.</a></p>
      </dd>
      <dt id="SERVER"><a class="permalink" href="#SERVER"><i class="Em">SERVER</i></a></dt>
      <dd>Describes the server <i class="Em">SELECTOR</i> should be retrieved
          from. Same character restrictions apply and it must come after a tab
          character as well. If it is omitted, the hostname of the server
          generating the menu is used.</dd>
      <dt id="PORT"><a class="permalink" href="#PORT"><i class="Em">PORT</i></a></dt>
      <dd>Describes the port <i class="Em">SERVER</i> is running on. Must come
          after a tab and is terminated by the end of the line or file. If this
          field is left out, the server generating the menu uses its own
        port.</dd>
    </dl>
  </dd>
</dl>
<p class="Pp">A gophermap file may contain any number of menu and info lines.
    They are then converted to actual gopher protocol menu entries clients
    understand line by line as described above.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE"><a class="permalink" href="#EXAMPLE">EXAMPLE</a></h1>
<p class="Pp">Tabs are marked with &#x2018;<code class="Li">^I</code>&#x2019;
    for clarity.</p>
<div class="Bd Pp Bd-indent Li">
<pre>spacecookie
===========

Welcome to spacecookie's gopher page!

Get a copy either by downloading the latest
stable release or cloning the development version:

hGitHub page^I	URL:https://github.com/sternenseemann/spacecookie/
9latest tarball^I	/software/releases/spacecookie-0.3.0.0.tar.gz

The following documentation resources should get you started:

0README^I	README.md
1man pages^I	manpages/

Other gopher server daemons (the first link only works
if this server is running on port 70):

1pygopherd^I	/devel/gopher/pygopherd^I	gopher.quux.org
1Bucktooth^I	/buck^I	gopher.floodgap.com^I	70</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr" href="https://manpages.debian.org/unstable/pygopherd.8.en.html">pygopherd(8)</a>,
    <a class="Lk" href="gopher://gopher.floodgap.com/0/buck/dbrowse?faquse%201a">Bucktooth's
    gophermap documentation</a> and
    <a class="Lk" href="https://tools.ietf.org/html/rfc1436#page-14">the file
    type list from RFC1436</a>.</p>
<p class="Pp"><a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>,
    <a class="Xr" href="./spacecookie.json.5.html">spacecookie.json(5)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">spacecookie.gophermap</code> documentation
    has been written by <span class="An">sternenseemann</span>,
    <a class="Mt" href="mailto:sterni-spacecookie@systemli.org">sterni-spacecookie@systemli.org</a>.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">April 18, 2023</td>
    <td class="foot-os">Nixpkgs</td>
  </tr>
</table>
</body>
</html>