README 5.79 KB
Newer Older
1 2 3
TELNET-SITE
===========

4

5 6 7
DESCRIPTION
-----------

mbionchi's avatar
mbionchi committed
8
  telnet-site - a glorified file reader intended to be used as a telnet site.
9

mbionchi's avatar
mbionchi committed
10
  The telnet-site executable takes the following parameters:
11

mbionchi's avatar
mbionchi committed
12
  --site <path-to-dir>       specify the path to the directory with site files
13

mbionchi's avatar
mbionchi committed
14
  --splash <path-to-file>    specify the path to the splash screen file (optional)
15

mbionchi's avatar
mbionchi committed
16 17 18
  The files in the --site directory can either be plaintext with some formatting
(see the FORMATTING and ANIMATIONS sections) or shared objects specifying special
functions to work with the site(see the DYNAMIC LIBRARIES section).
19

20

21
BUILDING
22
--------
23

24 25 26
  If you have autotools, you can just run
    ./autogen.sh
and then do the normal `./configure && make && make install` with your favourite
27
flags.  See BUILD-TIME OPTIONS to find out about features you can compile in or out.
28 29

  Otherwise, you can run
mbionchi's avatar
mbionchi committed
30
    gcc -o telnetsite -lncurses -ldl -Isrc ./src/*.c
31

32

33 34 35 36 37 38 39 40 41 42
BUILD-TIME OPTIONS
------------------

  You can pass the following options to the configure script:

    --disable-follow-link       Disable following symbolic links when reading content files.

    --enable-unicode            Enable unicode support for content files (note: not filenames).


43 44 45 46
SERVING OVER TELNET
-------------------

  Right now, in order to serve this over telnet, you need to use telnetd with
mbionchi's avatar
mbionchi committed
47
either inetd or xinetd.  Assuming you are running inetutils-telnetd and inetd,
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
your config should look like this:

  /etc/services, replacing <port> with the port you'd like to put the site on:

mytelnetsite <port>/tcp

  /etc/inetd.conf, replacing <user> with the user you'd like to run the site as
and <path-to-wrapper-script> with the path to the wrapper script (see below):

mytelnetsite stream tcp nowait <user> /usr/sbin/tcpd /usr/sbin/telnetd -h -E <path-to-wrapper-script>

  And finally, you should create a small script at <path-to-wrapper-script>,
with the following:

#!/bin/sh
mbionchi's avatar
mbionchi committed
63
exec <path-to-binary> --site <path-to-site.d> [--splash <path-to-splash-file>]
64

65
  where <path-to-binary> is the path to the telnet-site executable, and
66 67
<path-to-site.d> is the path to the root directory of the site.

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
FORMATTING
----------

  - If a line in the file ends in a space character (ascii 0x20 that is), then the
newline at the end is "escaped" and the next line from the file is treated as a part
of the same paragraph and will be reflowed based on the screen width, for example:

  Hello 
world!

  Will be treated as a single line due to Hello having a trailing space.  (I guess
you might need a hex editor to see this one :^))

  - If the first non-whitespace character at the beginning of a line is not a
letter, then this line is treated as a list item and, if it needs re-flowing,
will be aligned to the first letter character on this line, for example:

  [] this is list item number one

  Given limited columns, can be re-flowed by the algorithm as:

  [] this is
     list
     item
     number
     one
95

mbionchi's avatar
mbionchi committed
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
  - You can change text or animation alignment by using the `;align <how>`
    directive, on a line by itself, where <how> is one-of {left,right,center}.
    The chosen alignment will apply until explicitly changed.  Example:

;align center
* * *

;align right
  This paragraph will be right-aligned.

  And same for this one.

;align left
  However, this paragraph will be left-aligned!  How wonderful.

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

ANIMATIONS
----------

  Animation specification must start with a ;anim on the line by
itself and end with either ;loop or ;noloop on the line by itself.
In between those two lines, it is expected that the user will specify
frames by using the keyword ;frame followed by the number of ticks this
frame should last (where one tick is 1/10th a second), all on one line
with nothing else on it.  On the next line, and until the next ;frame,
the lines will be treated as frame data.  The number of lines must be
the same among all frames.

  For example, here's a specification of a loading spinner:

;anim
;frame 1
loading... |
;frame 1
loading... /
;frame 1
loading... -
;frame 1
loading... \
;loop

mbionchi's avatar
mbionchi committed
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

DYNAMIC LIBRARIES
-----------------

  In order to allow for more interactive functionality (such as user input or
programmable animations), telnet-site can dynamically load shared objects it
finds in the --site path.  The shared object files must end in .so in order for
the program to recognize it as such.  The "src/module.h" file contains the
preprocessor macro definitions for function names that the shared object must
define in order to interoperate with the telnet-site:

void INIT_FUNC_NAME(WINDOW *)  -  mandatory, called on the initial load of the
                                  shared object.  The WINDOW pointer points to
                                  the section of the screen the module is supposed
                                  to print on.

void SCROLL_FUNC_NAME(int)  -  optional, called when the main input loop gets a
                               command to scroll up (-1) or down (1).

void SETMODE_FUNC_NAME(enum mode)  -  optional, called when the main input loop
                                      detects mode change (COMMAND to INSERT or
                                      the other way around).  Used for custom user
                                      input.

void GETCH_FUNC_NAME(int)  -  optional, called when getch() in the main input loop
                              returns during INSERT mode.

void KILL_FUNC_NAME()  -  optional, called when the content is about to go out of
                          focus.  Is expected to clean up whatever memory was allocated
                          during the module's life.

  You can find an example that uses all of the features above to implement a
simple guestbook in the examples/guestbook.c file.

  To compile the example module as a shared library, you will need to:
      gcc -g -o guestbook.so -Isrc -fpic -shared examples/guestbook.c src/*.c


175 176 177
BUGS
----

178
  You know it.