===================================================
          Tutorial de Gopher en el SDF
===================================================
[Desde http://sdf.org/?tutorials/gopher]

Contenidos
   1. Qué es Gopher
   2. Crear su Espacio Gopher
   3. Gopher log
   4. Contenido Dinámico (topos)


Que ess Gopher?

  Desde: http://en.wikipedia.org/wiki/Gopher_(protocol)

El Gopher es un protocolo de capa de Aplicación diseñado para
distribuir, buscar y recuperar documentos a través de la Internet (...).
El protocolo ofrece algunas características que no están soportadas de
forma nativa por la Web, e impone una jerarquízación mucho más marcada
en cuanto al almacenamiento de la información.

Podrá encontrar más información aquí:

    * FAQ > GOPHER
    * http://www.scn.org/~bkarger/gopher-manifesto
    * http://gopher.floodgap.com/overbite/relevance.html

Crear su espacio Gopher

Para crear un directorio llamado "gopher" en su $HOME propio, puede
emplear el comando "mkgopher". Después de ejecutarlo, tipee "setup" en
la línea de prompt "MKGOPHER> ". Podrá ingresar la orden "help" para
obtener mayores detalles. Este directorio es en realidad un enlace
simbólico al directorio /ftp/pub/users/$USER/. Usted podrá colocar allí
todos los ficheros que desee dejar disponibles en su Espacio Gopher.

Puede utilizar mkgopher para publicar sus documentos, crear directorios,
etcétera. También es posible administrar su Espacio Gopher de forma
manual. Si decide hacerlo de esta manera, recuerde que el servidor no
mostrará el contenido si este no está hecho visible a todos. Esto
significa que deberá otorgarle permisos de acceso de lectura a todos a
los ficheros (chmod o+r $HOME/gopher/sufichero). Los directorios también
deben ser ejecutables para todos (chmod o+rx $HOME/gopher/sudirectorio),
etc. Debe tener en cuenta que el servidor Gophernicus servirá los
archivos ejecutables bajo el directorio /cgi-bin y también los ficheros
gophermaps que cuenten con permisos de ejecución (en forma de CGIs de
Gopher o "topos", ver debajo). Esto podría llevar a provocar errores en
el caso de los ficheros gophermap, de modo que debe asegurarse que sus
ficheros gophermap carezcan de permisos de ejecución innecesarios (chmod
-x $HOME/gopher/sudirectorio/gophermap).

El comando usual "mkgopher -p" no ha sido actualizado aún para reflejar
los requerimientos de permisos específicos del servidor Gophernicus. De
modo que podría necesitar resetear los permisos para todos los archivos
y directorios en su directorio gopher como se ha indicado arriba. Los
siguientes dos comandos realizarán esta tarea, revirtiendo todos los
archivos como legibles al mundo pero no ejecutables, y todos los
directorios como legibles por todo elmundos pero ejecutables.

find ~/gopher -type f -print0 | xargs -0 chmod 644
find ~/gopher -type d -print0 | xargs -0 chmod 755

Tenga presente que una vez después de ejecutados estos dos comandos,
podría tener que agregar manualmente los permisos de ejecución
requeridos a cualquier fichero gophermap dinámico o a los ficheros que
se encuentren bajo el directorio /cgi-bin


 Gophermap

       Nota: Puede ver el gophermap de ejemplo que viene con
       Gophernicus aquí. README.Gophermap.

       Asumamos que tiene "fichero1.txt", "fichero2.pdf",
       "dichero3.rtf" y el directorio "dir" en su espacio Gopher.

$ ls -lF
drwxr-x---  2 $USER  nobody  512 Dec  2 10:15 dir/
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 fichero1.txt
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 fichero2.pdf
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 fichero3.rtf

Cuando lo visite, en el caso de no existir un fichero llamado
"gophermap" (sin extensión alguna) verá una lista simple de archivos y
al directorio, de esta forma:


                                 Gopher Menu

(DIR) dir
(FILE) fichero1.txt
(FILE) fichero2.pdf
(FILE) fichero3.rtf

       Si existiese un archivo gophermap, el servidor lo procesará y
       presentará su contenido de la forma que lo haya especificado en
       el gophermap.

La sintaxis del fichero gophermap es:

XAlgún texto aquí<TAB>/ruta/al/contenido<TAB>ejemplo.org<TAB>N

Aquí el primer caracter ("X" en el ejemplo) es un "itemtype" (ver
abajo). "Algún texto aquí" es el texto que desea que se muestre, <TAB>
es el caracter de tabulación, "/ruta/al/contenido" es la localización de
su contenido, "ejemplo.org" es el servidor donde el contanido estña
localizado y el último caracter ("N" en el ejemplo) es el puerto de
servidor (usualmente es 70). El contenido luego del segundo <TAB> es
opcional si está enlanzando al contenido en su propio Espacio Gopher.

Los "itemtype" son algunos de estos caracteres:

       Itemtype        Contenido
       0               Fichero de texto
       1               Directorio
       2               Servidor de nombres CSO
       3               Error
       4               Archivador Mac HQX
       5               Binario de PC
       6               Fichero uu-encoded UNIX
       7               Servidor de búsqueda
       8               Sesión de Telnet
       9               Archivo Binario
       c               Calenadrio (no en 2.06)
       e               Evento (no en 2.06)
       g               Imagen GIF
       h               Lenguaje de Hipertexto HTML
       i               Tipo de Texto "en línea"
       s               Sonido
       I               Imagen (otra que no sea GIF)
       M               Mensaje mixto MIME Multiparte.
       T               Sesión TN3270



       Ejemplo de gophermap

Supongamos que queremos mostrar un mensaje de bienvenida, una
descripción para "fichero1.txt", "fichero2.pdf" y "dir", un enlace a un
servidor externo, un enlace a un URL http. Su fichero gophermap debería
parecerse al siguiente.


Bienvenido a mi Espacio Gopher!

0Mi fichero de texto    fichero1.txt
9Mi fichero PDF fichero2.pdf
1Mi directorio  dir

0Porque Gopher es relevante?    /gopher/relevance.txt   gopher.floodgap.com 70
hUn elnace http URL:http://sdf.lonestar.org/

  Recuerda la sintaxis de Gophermap. Sea cuidadoso con los caracteres
  de tabulación. En el ejemplo de arriba, hay algunas tabulaciones. Por
  ejemplo, la tercera línea es:

0Mi fichero de texto<TAB>fichero1.txt

  ...mientras que la séptima es

0Porque Gopher es relevante?<TAB>/gopher/relevance.txt<TAB>gopher.floodgap.com <TAB>70

¿Como es que el fichero PDF tiene un itemtype 9? Bueno, no todo tipo de
fichero tiene su itemtype propio, de modo que podemos utilizar uno que
tenga más sentido.

Aunque no necesitamos dejar una línea en blanco como la segunda de
nuestro docuemnto, podemos encontrar útil esto ya que existe un bug
conocido en Lynx que hace que se muestre la segunda línea junto con la
primera (puede encontrar un parche aquí:
gopher://sdf.lonestar.org/0/users/bulibuta/openbsd/patches/lynx-gopher-
newline.patch).

Esta será (más o menos) el resultado que obtendrá al usar un fichero
gophermap como el anteriormente descripto:

                                 Gopher Menu

      Bienvenido a mi Espacio Gopher!

(FILE) Mi fichero de texto
(BIN) Mi fichero PDF
(DIR) Mi directorio

(FILE) Porque Gopher es relevante?
(HTML) Un enlace http

Gopher log

Un gopher log ("gloc o phlog") es similar a un blog, pero en el Espacio
Gopher. Puede crear su phlog y agregarlo a la phlogósfera.

Mantener un glog consiste básicamente (pero no necesariamente) en crear
una entrada (en su directorio log) y modificiar su gophermap de modo que
la entrada nueva sea mostrada con su fecha de creación. Existe un script
que puede ejecutar en el SDF llamado "mkgopherentry" (localizado in
/sys/sdf/bin/mkgopherentry) que le permitirá hacer precisamente esto.
También extraerá el primer párrafo de la entrada y la agregará al
gophermap con un enlace "Continined..." que apuntará a su último posteo.
Crear una entrada es tan simple como ejecutar el siguiente comando:
mkgopherentry titulo archivodetexto, donde los dos argumentos son
autoexplicativos.

Digamos que tiene dos entradas en su diario. Si usará "mkgopherentry",
estas quedarán de la siguiente manera:

--Este es mi segundo post!!--
   Tuesday, December 01th, 2009
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Cras eros turpis, tristique semper aliquet sit amet,
hendrerit peron vivat. Integer pulvinar leo in posuere
blandit.
Continued...


--Primer post--
   Monday, November 30th, 2009
Primera entrada en mi Gopher log en el SDF.
Continued...

 Otro software glog/phlog

  Existen varios programas de software creados por miembros del SDF que
  puede encontrar útil para mantener un gopher log.

  germ
         gopher://sdf.lonestar.org/1/users/wt/soft/my/germ/

  slerm
         gopher://sdf.org/0/users/slugmax/about-slerm.txt
         gopher://sdf.org/9/users/slugmax/code/slerm-1.8.tgz
         http://slugmax.tx0.org/slerm-1.8.tgz

  glog
         gopher://sdf.lonestar.org/0/users/yargo/scripts/glog.sh

  mkphlog
         gopher://sdf.lonestar.org/1/users/octotep/scripts/mkphlog/

  phlogit
         gopher://sdf.org/0/users/slugmax/code/phlogit.txt

  tirph
         gopher://sdf.org/1/users/papa/tirph

  ugo
         gopher://sdf.lonestar.org/1/users/chr/scripts/ugo/

  Puede encontrar mas recursos en la sección "Glogging/Phlogging" en
  gopher://sdf.lonestar.org/1/users/wt/soft/gopher.


Contenido Dinámico (CGIs de gopher o topos)

El servidor empleado por el SDF (Gophernicus) es capaz de servir
"topos". Los Topos son ficheros ejecutables localizados en el directorio
/cgi-bin que son procesados por el servidor como CGIs. Esto significa
que podrá escribir un script, que el servidor ejecutará y presentará sus
resultados como si fuese una salida de texto estándar. No es necesario
declarar su tipo de contenido. Los Topos obtienen sus argumentos desde
la dirección utilizada para acceder al documento, y pueden ser accedidos
con cualquier itemtype que tenga sentido para usted según sea el tipo de
salida que genere el topo.

Puede programar el topo empleando cualquier lenguaje/s que ele resulte
cómodo, y pueda usarse en el SDF. A continuación verá algunos ejemplos
empleando scripts del intérprete de comandos.

       Ejemplos de topo

Recuerde que sus topos necesitan tener permisos de ejecución y lectura
para todos, y estar bajo el directorio /cgi-bin. De modo que tendrá que
ingresar: chmod 755 suscript.cgi.

El siguiente ejemplo generará un refrán aleatorio.

#!/bin/sh
/usr/pkg/games/fortune

  Fácil, ¿verdad? Como su resultado se presenta en forma de texto
  simple, podrá accederlo empleando un titemtype = 0, que está
  localizado en:
  gopher://sdf.lonestar.org/0/users/YOUR-USERNAME/cgi-bin/fortune.cgi

Tenga presente que fortune fue activado con su ruta completa. Ello se
debe a que su ruta en el servidor es
"PATH=/sbin:/bin:/usr/sbin:/usr/bin". Eso significa que si llama un
programa sin ingresar su ruta, el servidor lo buscará únicamente en
"/sbin", "/bin", "/usr/sbin" y "/usr/bin". "/usr/pkg/games" y otras
rutas no están en la variable $PATH del servidor (eventualmente podría
agregar una ruta de su preferencia, por ejemplo, con
PATH=$PATH:/usr/pkg/games).

       ls.cgi

El siguiente ejemplo generará un listado de los ficheros localizados en
un directorio especificado. Será posible ordenar su contenido
alfabéticamente o por fecha y hora de modificación, en base a los
parámetros que ingrese en el script.

#!/bin/sh

directory=/ftp/pub/users/YOUR-USERNAME
rel_dir=/users/YOUR-USERNAME
server=sdf.lonestar.org
port=70

# El separador de campo interno está configurado para ser una línea
# nueva.
IFS='
'

if [ -n "$1" -a "$1" = 'date' ] ; then
   ls_arg=t
fi

for i in $(ls -l${ls_arg} $directory) ; do

   content=$(echo "$i" | awk '{ print $9}')
   date=$(echo "$i" | awk '{ print $6,$7,$8}')

   if [ -z "$content" ] ; then
       continue
   fi

   if [ -d $directory/$i ] ; then
       itemtype=1
   else
       itemtype=0
   fi

   echo "$itemtype$content ($date) $rel_dir    $server $port"
done


Note que la línea "echo..." es

echo "$itemtype$content ($date)<TAB>$rel_dir<TAB>$server<TAB>$port"

Si va a gopher://sdf.lonestar.org/1/users/YOUR-USERNAME/cgi-bin/ls.cgi,
verá una lista de sus archivo ordenados alfabéticamente. Si acede a su
topo como
gopher://sdf.lonestar.org/1/users/YOUR-USERNAME/cgi-bin/ls.cgi?date,
entonces debería ver sus ficheros/directorios ordenados por fecha de
modificación.

   figlet.cgi

  Podrá agregar alguna interactividad empleando la itemtype 7. Este
  itemtype está pensado para hacer posible tipear algunos caracteres en
  un campo de búsqueda en su navegador. Sin embargo, puede emplearlo
  para hacer posible pasar argumentos a sus scripts. El ejemplo a
  continuación usará alguna texto que usted ingrese en el campo de
  búsqueda y lo pasará al programa "figlet" que grafica el texto en un
  cartelón ASCII.

#!/bin/sh
IFS='
'

for line in $(/usr/pkg/bin/figlet "$@") ; do
   echo "i$line"  # Esto es itemtype=i + texto
done

Cuando usted acede al scritp a través de
gopher://sdf.lonestar.org/7/users/YOUR-USERNAME/cgi-bin/figlet.cgi , su
navegador le solicitará que ingrese algún texto (la forma de hacerlo
depende de su navegador). Luego, le mostrará su texto en la medida que
figlet lo transforme.

La "i" en la línea "echo..." es importante. De hecho, el documento ha
sido accedido con un itemtype "7" (y lo mismo se aplica para el itemtype
"1"=. De modo que el documento debe ser estructurado de la misma forma
en gophermaps. Sin embargo, no es un gophermap. Este es el motivo por el
cual se requiere explícitamente indicar la línea que debe mostrarse como
"simple" (o texto "en línea").

Caveat

Además de lo dicho en el último párrafo para el script "figlet.cgi",
también debe tenerse en cuenta otra cosa. En dicho ejemplo (como en todo
lo que sea servido como un directorio virtual con un itemtype 1 o 7), el
contenido no se mostrará si accede al script a través de un proxy
intermedio (o tal vez otros distintos) En este caso, deberá "formatear"
la salida de su script. Afortunadamente, esto es muy fácil. Por ejemplo,
en el script figlet.cgi, deberá modificar la línea "echo..." de esta
manera: echo "i$i<TAB><TAB>error.host<TAB>1", donde <TAB> es un caracter
de tabulador (¡ya debería saber esto!). C y "error.host" y 1 son,
respectivamente, un servidor falso y un número de puerto. Podría haber
escrito "fake" en lugar de "error.host", y "300" en lugar de "1").

  $Id: gopher.html,v 1.19 2017/05/08 17:21:40 slugmax Exp $