<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Rodrigo</firstname>">
  <!ENTITY dhsurname   "<surname>Gallardo</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>January 14, 2005</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>rodrigo@nul-unu.com</email>">
  <!ENTITY dhusername  "Luis Rodrigo Gallardo Cruz">
  <!ENTITY dhucpackage "<refentrytitle>PUBTAL</refentrytitle>">
  <!ENTITY dhpackage   "pubtal">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  <!ENTITY html        "<acronym>HTML</acronym>">

  <!ENTITY uploadSite  "<command>uploadSite</command>">
  <!ENTITY updateSite  "<command>updateSite</command>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2004, 2005</year>
      <holder>Colin Stewart</holder>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>PubTal</refname>
    <refpurpose>Generate a web site from content and templates, and
    upload it to its destination</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &updateSite;

      <arg>options</arg>
      <arg choice="req"><replaceable>site.config</replaceable></arg>
      <group>
        <arg><replaceable>content-dir</replaceable></arg>
        <arg><replaceable>content-type</replaceable></arg>
      </group>
      <arg>...</arg>

<!--      
   <arg><option>-e <replaceable>this</replaceable></option></arg>
  -->

    </cmdsynopsis>
    <cmdsynopsis>
      &uploadSite;

      <arg>options</arg>
      <arg choice="req"><replaceable>site.config</replaceable></arg>
      <group>
        <arg><replaceable>destination-dir</replaceable></arg>
        <arg><replaceable>destination-file</replaceable></arg>
      </group>
      <arg>...</arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents briefly the &updateSite; and
      &uploadSite; commands from the PubTal package</para>

    <para>This manual page was written for the &debian; distribution
    because the original program does not have a manual page.
    Instead, it has documentation in &html; format;
    see below.</para>

    <para>&updateSite; generates &html; pages
      starting from a series of content files and templates written in
    the <acronym>ZPT</acronym> language.</para>

    <para>The command takes a minimum of one parameter, the location of
    the website configuration file.</para>

    <para>The &updateSite; command first reads in the configuration file
    and so locates the content, template, and destination directories
    (defaulting to content, template, and dest respectively).  If only
    one parameter is passed to &updateSite;, it will then find each
    file under the content directory and build the corresponding
    output files.</para>

    <para>If more than one parameter is passed, then each extra parameter
    is taken as content to build.  If the parameter is a directory
    under the content directory, then any content files in that
    directory will be built recursively.  If the parameter is a file
    in the content directory (or one of its children), then just that
    file will be built.</para>

    <para>Take for example:

      <userinput>
	updateSite new-site/site.config new-site/content/index.txt new-site/content/examples/
      </userinput>

      This will build the index.txt file into index.html and all
      content files under content/examples/ will be built into their
      corresponding output files.
    </para>

    <para>&uploadSite; uploads the generated
    pages.  This takes a minimum of one parameter, the location of the
    website configuration file.</para>

    <para>The &uploadSite; command first reads in the configuration
    file and so locates the destination directories.  If only one
    parameter is passed to &uploadSite;, it will then find each file
    under the destination directory that needs to be uploaded.  The
    logic used to determine whether a file needs to be uploaded is
    explained in the Uploading section.</para> 

    <para>If more than one parameter is passed, then each extra
    parameter is taken as destination to upload.  If the parameter is
    a directory under the destination directory then any files in that
    directory will be considered for upload recursively.  If the
    parameter is a file in the destination directory (or one of its
    children), then just that file will be considered for
    upload.</para>

    <para>Take for example:

      <userinput>
	uploadSite new-site/site.config new-site/dest/index.html new-site/dest/examples/
    </userinput>

      This will examine the index.html file and all files under
    dest/examples/ when determining what files to upload.</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <para>A summary of options is included below.  For a complete
    description, see the &html; documentation.</para>

    <para>Options for &updateSite;</para>

    <variablelist>
      <varlistentry>
	<term>
	  <option>-h</option>
	</term>
	<term>
	  <option>--help</option>
	</term>
        <listitem><para>
	    Prints out the help description for the command.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-a</option>
	</term>
	<term>
	  <option>--all</option>
	</term>
        <listitem><para>
	  Builds all classes of content, not just content in the "normal" class.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--class classParams</option>
	</term>
        <listitem><para>
	  Builds all classes given as supplied in a comma separated list.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--logging</option>
	</term>
        <listitem><para>
	  Turns on logging.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--logfile name</option>
	</term>
        <listitem><para>
	  Logs to the file "name" (defaults to updateSite.log).
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--debug</option>
	</term>
        <listitem><para>
	  Turns on debug logging; implies <option>--logging</option>.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--debug-simpletal</option>
	</term>
        <listitem><para>
	  Turns on debug logging of SimpleTAL, implies <option>--logging</option>.
	</para></listitem>
      </varlistentry>
    </variablelist>

    <para>Options for &uploadSite;</para>

    <variablelist>
      <varlistentry>
	<term>
	  <option>-h</option>
	</term>
	<term>
	  <option>--help</option>
	</term>
        <listitem><para>
	  Prints out the help description for the command.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-a</option>
	</term>
	<term>
	  <option>--all</option>
	</term>
        <listitem><para>
	  Checks all files are uploaded, not just PubTal generated ones.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--force</option>
	</term>
        <listitem><para>
	  Uploads files even if PubTal thinks they are up-to-date.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--dry-run</option>
	</term>
        <listitem><para>
	  Prints out what would have been done, but takes no action.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--logging</option>
	</term>
        <listitem><para>
	  Turns on logging.
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--logfile name</option>
	</term>
        <listitem><para>
	  Logs to the file "name" (defaults to updateSite.log).
	</para></listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>--debug</option>
	</term>
        <listitem><para>
	    Turns on debug logging; implies <option>--logging</option>.
	</para></listitem>
      </varlistentry>
    </variablelist>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para>The programs are documented fully by &html; documentation
      available in /usr/share/doc/pubtal/html.</para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the &gnu; General Public License, Version 2 or any
      later version published by the Free Software Foundation.
    </para>
    <para>
      On Debian systems, the complete text of the GNU General Public
      License can be found in /usr/share/common-licenses/GPL.
    </para>
  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->


