Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mbionchi/telnet-site


https://github.com/mbionchi/telnet-site

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

        
TELNET-SITE

===========



DESCRIPTION

-----------



  telnet-site - a glorified file reader intended to be used as a telnet site.



  The telnet-site executable takes the following parameters:



  --site        specify the path to the directory with site files



  --splash     specify the path to the splash screen file (optional)



  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).



BUILDING

--------



  If you have autotools, you can just run

    ./autogen.sh

and then do the normal `./configure && make && make install` with your favourite

flags.  See BUILD-TIME OPTIONS to find out about features you can compile in or out.



  Otherwise, you can run

    gcc -o telnetsite -lncurses -ldl -Isrc ./src/*.c



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).



SERVING OVER TELNET

-------------------



  Right now, in order to serve this over telnet, you need to use telnetd with

either inetd or xinetd.  Assuming you are running inetutils-telnetd and inetd,

your config should look like this:



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



mytelnetsite /tcp



  /etc/inetd.conf, replacing  with the user you'd like to run the site as

and  with the path to the wrapper script (see below):



mytelnetsite stream tcp nowait  /usr/sbin/tcpd /usr/sbin/telnetd -h -E 



  And finally, you should create a small script at ,

with the following:



#!/bin/sh

exec  --site  [--splash ]



  where  is the path to the telnet-site executable, and

 is the path to the root directory of the site.



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



  - You can change text or animation alignment by using the `;align `

    directive, on a line by itself, where  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.



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



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



BUGS

----



  You know it.