artemus.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 artemus - Text substitution tool and much more
   6
   7 =head1 SYNOPSIS
   8
   9  # substitutes text
  10  artemus -i|--input={input file} -o|--output={output file}
  11         [-c|--conf={config file}]
  12         [-p|--paragraph={paragraph_separator}]
  13         [-m|--msdos] [-a|--append]
  14
  15  # send via ftp
  16  artemus -f|--ftp {files to ftp...}
  17
  18  # creates a template makefile for html projects
  19  artemus -k|--makefile > Makefile
  20
  21  # builds a site map page
  22  artemus -s|--site-map {Directories} > sitemap/index.artemus
  23
  24 =head1 DESCRIPTION
  25
  26 B<artemus> is a text substitution tool (thought mainly for preprocessing HTML).
  27 Macros are defined in the file F<artemus.conf>, in the form B<key=value>,
  28 being B<value> the destination text, that can have parameters. The macro is
  29 included in the source file between the B<{-> and B<}> marks. The (possible)
  30 parameters are delimited by the B<|> symbol.
  31
  32 Examples:
  33
  34 In F<artemus.conf> file:
  35
  36  # some simple definitions
  37  Perl=<a href="http://www.perl.com">Perl</a>
  38  LWN=<a href="http://www.lwn.net">Linux Weekly News</a>
  39  separator=<br><hr><br>
  40  head=<html><body bgcolor=ffffff>
  41
  42  # definitions with parameters
  43  # generic link
  44  link=<a href="http://$1">$0</a>
  45  # generic meta
  46  meta=<meta name="$1" content="$0">
  47  # link using the link macro
  48  CPAN={-link|CPAN|www.cpan.org}
  49
  50 In a source file F<index.artemus>:
  51
  52  {-head}
  53  {-meta|links, free software|keywords}
  54  <h1>Links</h1>
  55  <ul>
  56  <li>{-Perl}
  57  <li>{-LWN}
  58  <li>{-CPAN}
  59  <li>{-link|kernel.org|www.kernel.org}
  60  </ul>
  61  {-separator}
  62
  63 By running
  64
  65  artemus -i index.artemus -o index.html
  66
  67 you obtain the file F<index.html>:
  68
  69  <html><body bgcolor=ffffff>
  70  <meta name="keywords" content="links, free software">
  71  <h1>Links</h1>
  72  <ul>
  73  <li><a href="http://www.perl.com">Perl</a>
  74  <li><a href="http://www.lwn.net">Linux Weekly News</a>
  75  <li><a href="http://www.cpan.org">CPAN</a>
  76  <li><a href="http://www.kernel.org">kernel.org</a>
  77  </ul>
  78  <br><hr><br>
  79
  80 The I<--paragraph> argument let us define a string to substitute the empty
  81 lines in the document. If defined as <p>, you can create HTML documents
  82 separating the paragraphs with only a blank line, as B<artemus> will fill
  83 them with <p>.
  84
  85 The I<--msdos> argument creates the typical MSDOS end of line, CR+LF.
  86
  87 The I<--append> argument appends the output to destination file, instead
  88 of overwriting it.
  89
  90 The I<--makefile> argument creates a typical makefile for artemus-based
  91 HTML projects (including building and ftp-uploading rules). You must
  92 modify it to suit your needs.
  93
  94 The I<--site-map> argument walks the directories sent as arguments searching
  95 for HTML files and sends to standard output the map of the site. As header
  96 and footer it creates the special B<artemus> tags B<site-map-head> and
  97 B<site-map-foot>, that must be defined in F<artemus.conf>. A typical
  98 definition could be
  99
 100  site-map-head={-head|Site Map}
 101  site-map-foot={-foot}
 102
 103 =head1 FTP
 104
 105 B<artemus> includes, since version 2.04, ftp capabilities to send the files
 106 specified as arguments to a server defined in F<artemus.conf>. The entries
 107 in this file must be:
 108
 109  ftp.host=<host>
 110  ftp.user=<user>
 111  ftp.passwd=<passwd>
 112  ftp.dir=<destination directory (optional)>
 113
 114 Note that including this information in F<artemus.conf> makes it
 115 security-sensible.
 116
 117 =head1 AUTHOR
 118
 119 (C) Angel Ortega <angel@triptico.com> 2000/2003
 120
 121 =cut