waste/artemus.pod

   1 # -*- Mode: plain
   2
   3 =pod
   4
   5 (English text below)
   6
   7 =head1 NAME
   8
   9 artemus - Herramienta de sustitución de texto y más cosas
  10
  11 =head1 SYNOPSIS
  12
  13  # sustituye textos
  14  artemus -i|--input={input file} -o|--output={output file}
  15                 [-c|--conf={config file}]
  16                 [-p|--paragraph={paragraph_separator}]
  17                 [-m|--msdos] [-a|--append]
  18
  19  # envía por ftp
  20  artemus -f|--ftp {files to ftp...}
  21
  22  # crea un makefile típico para proyectos web
  23  artemus -k|--makefile > Makefile
  24
  25  # construye una página con el mapa del sitio
  26  artemus -s|--site-map {directories} > sitemap/index.artemus
  27
  28 =head1 DESCRIPTION
  29
  30 B<artemus> es una herramienta que permite efectuar sustituciones en ficheros
  31 de texto (pensado fundamentalmente para preprocesar HTML). Las macros se
  32 definen en el fichero F<artemus.conf>, en la forma B<clave=valor>, siendo
  33 B<valor> el texto destino, que puede incluir parámetros. La forma de incluir
  34 la macro en el fichero origen es incluir la B<clave> entre las marcas
  35 B<{-> y B<}>. Los (posibles) parámetros se separarán de la B<clave> mediante
  36 el símbolo B<|>.
  37
  38 Ejemplos:
  39
  40 En el fichero F<artemus.conf>:
  41
  42  # varias definiciones simples
  43  Perl=<a href="http://www.perl.com">Perl</a>
  44  LWN=<a href="http://www.lwn.net">Linux Weekly News</a>
  45  separator=<br><hr><br>
  46  head=<html><body bgcolor=ffffff>
  47
  48  # definiciones con parámetros
  49  # link genérico
  50  link=<a href="http://$1">$0</a>
  51  # meta genérico
  52  meta=<meta name="$1" content="$0">
  53  # enlace usando la macro link
  54  CPAN={-link|CPAN|www.cpan.org}
  55
  56 En un fichero origen F<index.artemus>:
  57
  58  {-head}
  59  {-meta|links, free software|keywords}
  60  <h1>Enlaces</h1>
  61  <ul>
  62  <li>{-Perl}
  63  <li>{-LWN}
  64  <li>{-CPAN}
  65  <li>{-link|kernel.org|www.kernel.org}
  66  </ul>
  67  {-separator}
  68
  69 Ejecutando
  70
  71  artemus -i index.artemus -o index.html
  72
  73 se obtiene el fichero F<index.html>:
  74
  75  <html><body bgcolor=ffffff>
  76  <meta name="keywords" content="links, free software">
  77  <h1>Enlaces</h1>
  78  <ul>
  79  <li><a href="http://www.perl.com">Perl</a>
  80  <li><a href="http://www.lwn.net">Linux Weekly News</a>
  81  <li><a href="http://www.cpan.org">CPAN</a>
  82  <li><a href="http://www.kernel.org">kernel.org</a>
  83  </ul>
  84  <br><hr><br>
  85
  86 El parámetro I<--paragraph> permite definir la cadena que sustituirá a cada
  87 línea en blanco. Así, si se define como <p>, se pueden crear ficheros HTML
  88 separando cada párrafo con sólo una línea en blanco, pues B<artemus> añadirá
  89 los <p> él sólo.
  90
  91 El parámetro I<--msdos> crea los fines de línea típicos de MSDOS CR+LF.
  92
  93 El parámetro I<--append> añade la salida al fichero destino en lugar de
  94 sustituirlo.
  95
  96 El parámetro I<--makefile> genera un makefile típico para proyectos HTML
  97 basados en artemus (incluyendo reglas para construcción y envío ftp). Debe
  98 ser modificado para adaptarse a las necesidades del proyecto.
  99
 100 El parámetro I<--site-map> recorre los directorios enviados como argumento
 101 en busca de ficheros HTML y envía a la salida estándar un fichero con el
 102 mapa del sitio. Crea como cabecera y pie las marcas B<artemus> especiales
 103 B<site-map-head> y B<site-map-foot>, que deberán estar definidas en
 104 F<artemus.conf>. Una definición típica sería:
 105
 106  site-map-head={-head|Site Map}
 107  site-map-foot={-foot}
 108
 109 =head1 FTP
 110
 111 B<artemus> incluye, desde la versión 2.04, la capacidad de enviar por ftp al
 112 servidor definido en F<artemus.conf> los ficheros enviados como argumento. Para
 113 ello, hay que crear en dicho fichero de configuración las siguientes
 114 entradas:
 115
 116  ftp.host=<host>
 117  ftp.user=<usuario>
 118  ftp.passwd=<palabra clave>
 119  ftp.dir=<directorio destino (opcional)>
 120
 121 Debe tenerse en cuenta que, al incluir la clave de acceso, el fichero
 122 F<artemus.conf> se hace sensible a posibles mirones.
 123
 124 =head1 AUTHOR
 125
 126 (C) Angel Ortega <angel@triptico.com> 2000/2001
 127
 128 ---------------
 129
 130 =head1 NAME
 131
 132 artemus - Text substitution tool and much more
 133
 134 =head1 SYNOPSIS
 135
 136  # substitutes text
 137  artemus -i|--input={input file} -o|--output={output file}
 138         [-c|--conf={config file}]
 139         [-p|--paragraph={paragraph_separator}]
 140         [-m|--msdos] [-a|--append]
 141
 142  # send via ftp
 143  artemus -f|--ftp {files to ftp...}
 144
 145  # creates a template makefile for html projects
 146  artemus -k|--makefile > Makefile
 147
 148  # builds a site map page
 149  artemus -s|--site-map {Directories} > sitemap/index.artemus
 150
 151 =head1 DESCRIPTION
 152
 153 B<artemus> is a text substitution tool (thought mainly for preprocessing HTML).
 154 Macros are defined in the file F<artemus.conf>, in the form B<key=value>,
 155 being B<value> the destination text, that can have parameters. The macro is
 156 included in the source file between the B<{-> and B<}> marks. The (possible)
 157 parameters are delimited by the B<|> symbol.
 158
 159 Examples:
 160
 161 In F<artemus.conf> file:
 162
 163  # some simple definitions
 164  Perl=<a href="http://www.perl.com">Perl</a>
 165  LWN=<a href="http://www.lwn.net">Linux Weekly News</a>
 166  separator=<br><hr><br>
 167  head=<html><body bgcolor=ffffff>
 168
 169  # definitions with parameters
 170  # generic link
 171  link=<a href="http://$1">$0</a>
 172  # generic meta
 173  meta=<meta name="$1" content="$0">
 174  # link using the link macro
 175  CPAN={-link|CPAN|www.cpan.org}
 176
 177 In a source file F<index.artemus>:
 178
 179  {-head}
 180  {-meta|links, free software|keywords}
 181  <h1>Links</h1>
 182  <ul>
 183  <li>{-Perl}
 184  <li>{-LWN}
 185  <li>{-CPAN}
 186  <li>{-link|kernel.org|www.kernel.org}
 187  </ul>
 188  {-separator}
 189
 190 By running
 191
 192  artemus -i index.artemus -o index.html
 193
 194 you obtain the file F<index.html>:
 195
 196  <html><body bgcolor=ffffff>
 197  <meta name="keywords" content="links, free software">
 198  <h1>Links</h1>
 199  <ul>
 200  <li><a href="http://www.perl.com">Perl</a>
 201  <li><a href="http://www.lwn.net">Linux Weekly News</a>
 202  <li><a href="http://www.cpan.org">CPAN</a>
 203  <li><a href="http://www.kernel.org">kernel.org</a>
 204  </ul>
 205  <br><hr><br>
 206
 207 The I<--paragraph> argument let us define a string to substitute the empty
 208 lines in the document. If defined as <p>, you can create HTML documents
 209 separating the paragraphs with only a blank line, as B<artemus> will fill
 210 them with <p>.
 211
 212 The I<--msdos> argument creates the typical MSDOS end of line, CR+LF.
 213
 214 The I<--append> argument appends the output to destination file, instead
 215 of overwriting it.
 216
 217 The I<--makefile> argument creates a typical makefile for artemus-based
 218 HTML projects (including building and ftp-uploading rules). You must
 219 modify it to suit your needs.
 220
 221 The I<--site-map> argument walks the directories sent as arguments searching
 222 for HTML files and sends to standard output the map of the site. As header
 223 and footer it creates the special B<artemus> tags B<site-map-head> and
 224 B<site-map-foot>, that must be defined in F<artemus.conf>. A typical
 225 definition could be
 226
 227  site-map-head={-head|Site Map}
 228  site-map-foot={-foot}
 229
 230 =head1 FTP
 231
 232 B<artemus> includes, since version 2.04, ftp capabilities to send the files
 233 specified as arguments to a server defined in F<artemus.conf>. The entries
 234 in this file must be:
 235
 236  ftp.host=<host>
 237  ftp.user=<user>
 238  ftp.passwd=<passwd>
 239  ftp.dir=<destination directory (optional)>
 240
 241 Note that including this information in F<artemus.conf> makes it
 242 security-sensible.
 243
 244 =head1 AUTHOR
 245
 246 (C) Angel Ortega <angel@triptico.com> 2000/2001
 247
 248 =cut
 249