client-help.txt
NAME
    noah - client program to access Noah Server via command line

SYNOPSIS
    noah [COMMAND] [OPTIONS] ... [filenames]

DESCRIPTION
    noah is a client program that is used in a command line shell
    to access the Noah Server via http protocol to upload or download
    files one at a time or in batches using wildcards. It can also
    re-synchronize local files through a scripting environment.

What are some Client Scripting Applications ?

    - efficiently upload many files at once to a NOAH Server which 
      would otherwise be tedious through the browser interface.     

    - select files for upload through the convenience of
      a Windows Explorer interface.

    - file synchronization of files between client machines
      and NOAH Server .. either upload or download.
    
    The intent of Client Scripting is not to replace the
    browser interface but rather to compliment the browser
    interface enabling users to better leverage the database
    nature of the Nordicwind Document Management System.

OPTIONS

.EX
    noah get -docno 'Fn'
    noah get 'filename(s)' 
    noah put -docno 'Fn' [-notdefault]
    noah put 'filename(s)' [-notdefault] [-new] [-dir 'target dir'] [-nodups]
    noah reg 'filename(s)'
    noah reg -docno 'Fn'
    noah getall [-verbose]
    noah putall [-verbose] [-notdefault]
    noah menu 'filename(s)' 
    noah -init
    noah -h     : Quick Help (This 12 line summary)
    noah -help  : Verbose Help (this file)
.EE

    Noah is generally envoked with a command followed by
    any number of options. A 'get' command downloads files
    where as a 'put' command uploads files. There are also
    some interesting commands to register files for regular
    updating and backup as well as a menu command so you
    don't have to remember as many options and commands.

noah get -docno 'Fn' 
        
    Get a document based on the document number. Document
    numbers always start with uppercase F followed by a
    number. One can discover the document number of a document
    by hovering the mouse over a document entry in the NOAH
    browser interface (shows a tooltip of docno=Fn) or by
    using the elinks option.

    When this command option is run and there is no file
    in the current directory on the client machine that
    matches the filename on the server, the file is
    downloaded onto the client machine.

    If there is a local file on the client machine that
    matches the download filename, a check is done
    on the file to see if it matches a previous
    version of this document. If it does, the current 
    default version is downloaded replacing the 'old' version.

    If the local file on the client machine does NOT 
    match any previous version, then the download is
    aborted to ensure this local unknown file is not
    lost.  The user must either delete the 
    local file and re-run the command or decide to keep
    the file and perhaps do a 'noah put' command instead.

noah get 'filename(s)' 

    This command is the same as the -docno option except
    that the NOAH Server is searched for an entry that matches
    this 'filename'. If multiple matches occur, the user is
    given a menu to choose the match based on a listing of
    'filename' meta-data. 

    Multiple filenames in command line are permitted.
    
noah put -idno 'Fn' [-notdefault] 

    This command is similar to the 'get -idno' but it uploads
    the file to NOAH Server. The file name is obtained from
    the NOAH Server. If the name matches the local filename
    on the client machine (in the directory that noah is run
    from), the upload is performed.

    If the local filename is identical to the last file version
    uploaded, the upload is aborted.

    The new file version is set to be the default file on the 
    NOAH Server unless the user specifies the -notdefault 
    option.

noah put 'filename(s)'  [-new] [-dir 'target dir']

    This command is similar to the "get 'filename'" command
    except of course the file must exist in the local 
    client directory. If the 'filename' matches more than
    one filename in the database, the user is given a 
    selection menu.

    With the -new option, the user can force the upload and
    creation of this file to the default directory called
    /UserUploads/'username'. 

    If this directory does not exist on the NOAH Server, it 
    is automatically created. 

    If the file already exists in this directory, the upload
    is aborted.

    With the -dir option, the user can specify a different
    directory and the directory tree will be created if it
    does not already exist.

    Multiple filenames in command line are permitted.

noah reg 'filename(s)'

    This command tests that the 'filename' exists on the
    NOAH Server and then registers the file in the 
    client's local register file. 

    This 'register' file is used by the "putall" or "getall"
    commands to automatically upload or download registered
    files.

    Multiple filenames in command line are permitted.

noah getall [-verbose]
noah putall [-verbose] [-notdefault]

    These two commands access the users 'register' file
    and checks each entry for candidates for uploading to
    or downloading from the NOAH Server.
    
    The same rules are applied as for the "get" and "put"
    commands so local files are never over written unless
    they already exist in the NOAH database.

    The effect of the "getall" command is to re-fresh local
    client files with the current default files on the 
    NOAH Server.

    The effect of the "putall" command is to upload local
    client files that have recently changed and upload 
    these files as new file versions as defaults
    UNLESS the -notdefault option is specified.

noah menu 'filename(s)'

    See section on Shell Menu Mode for description
        
noah -init

    This option initializes the users configuration by
    asking the for hostname, cgi-bin directory, port #,
    username and password.

    Passwords are stored encrypted in the users configuration
    file and expire automatically within 24 hours if not
    used.

        
[-username 'user'] [-password 'password']

    With any of the above  command-line arguments, the
    user may add an optional "username" or "password".

[-debug]

    Adding the debug option to any of these commands, dumps http
    traffic to the standard output permitting analysis of
    strange behaviour.
    
Windows Explorer Launch (Windows OS only)

    When installing noah in a windows XP or similar
    OS, the users' environment is modified to make it
    easy to access naoh from the Explorer File Manager.

    
    When a user selects a file and then right-clicks the mouse,
    a "Open with NOAH" option appears.  This will open this
    file with the menu option described previously and permit
    the user to perform an operation on the file.

    When a user selects multiple files and then right-clicks the
    mouse and selects "Open with NOAH", a noah menu will pop
    up for EACH file selected. This is probably not what the
    user had in mind! 
    Instead, when selecting multiple files, right-click and select
    the "SendTo" sub-menu and select "NOAH_menu" or 
    "NOAH_register_files". 

    In the "NOAH_menu" case, a single noah menu will appear and 
    the user will be able to use the '+' (or '=') and '-' keys in 
    the menu to work with each file one at a time.

    In the "NOAH_register_files" case, noah will register all the
    selected files in the client's 'register' file. If the file
    does NOT exist on the NOAH Server, the file will be 
    automatically uploaded to the server into the directory 
    /UserUploads.'username'. If the directory does not exist, it
    will be created.

Windows Desktop Launch (Windows OS only)

    The Windows noah installation program creates
    a desktop shortcut to noah with the 'menu' option. 
    When noah starts with just the 'menu' option, only the 
    menu items for the register options appear.
    The user can then test for uploads (putall) or test for 
    downloads (getall).

    If the user drags and drops file(s) to the desktop shortcut,
    all the files will be opened with the noah menu option 
    using the '+' and '-' menu items to move through the file list.

Shell Menu Mode

    From the command line, the user can run "noah" with the
    menu option and with one or more filenames:

noah menu 'filename(s)'

    This invokes a menu that gives the user a number 
    of options that behave like the command-line options
    described previously.

    The menu looks similar to this:

.RS 4
.EX
       NOAH ===========================  rev: July 27/2005

       FILE: france.2003.checklist.pdf

       u:   upload ......... set as default version
       U:   upload ... DON'T set as default version
       n:   upload as NEW file to dir: /UserUploads.harold
       d:   download default version
       r:   register as a client NOAH file
       +:   next       file: spain.2008.checklist.pdf

       tu:  test for client uploads   (upload new versions as defaults)
       TU:  test for client uploads   (upload new versions: NOT defaults)
       td:  test for client downloads (refresh to default version)
       ed:  edit register file (to delete entry)
       v:   set verbose mode

       h:   help
       q:   quit

       select action ... followed with  :
.EE
.RE

    There are a few things that the menu can do that are special:

    - If the user specifies more than one file in the
      command-line, the '+' menu item will appear.
      Select the '+' to go to next file in list, or '-' to
      go to previous file. 

      NOTE that the '=' sign will behave like a '+' to save the user 
           from hitting the shift key on some keyboards.

    - The 'ed' menu item opens the register file in the
      local editor to permit the user to see and possibly
      modify the register file.

    - The 'h' menu item opens this help file in the local editor.

    The 'tu' and 'td' commands are identical to the "putall"
    and "getall" command-line commands. The 'v' item for 'verbose' 
    primarily affects these 'tu' and 'td' commands as -verbose
    does in the "putall" and "getall" commands.

Creating Batch Jobs

    In the previous section, the command-line options have
    been fully described.  With this information, it is easy
    for a user to put multiple commands together in a batch
    mode to perform a multitude of operations.


Windows Installation

    The 'install' program that comes with the  noah-client
    package gathers two pieces of information from the WINDOWS
    environment before installing files: 

	ProgramFiles and USERPROFILE.

    The 'noah.exe' and 'client-help.txt' files are copied into 
    a directory called 'noah' in the ProgramFiles directory.

    The 'NOAH_register_files.lnk' and 'NOAH_menu.lnk' files
    are copied into the SendTo directory below the USERPROFILE
    directory.

    The 'NOAH_menu.lnk' file is copied into the Desktop directory
    below the USERPROFILE directory.

    Finally, a 'noah.reg' file is created which defines a 
    'HKEY_CLASSES_ROOT\*\shell\noah' key and a 'command' subkey
    that calls the "noah menu" command when the user
    right clicks the mouse. The install program then runs
    'regedit noah.reg' to install this key.

    If the two environment variables ProgramFiles and USERPROFILE
    are not found, the install program makes decisions on 
    file locations assuming a Windows 98 environment.

    To enable access to noah in a command shell, the installer
    will have to add the path to the 'noah.exe' directory to the
    path variable.

    When a user starts noah for the first time, it will 
    assume the -init option and ask questions on the server and
    username etc. as discussed in the command-line descriptions.
    The configuration file is then stored in USERPROFILE\noah_client
    and is called 'config'.

    NOTE: Typically in a WIN-XP environment, the USERPROFILE
    directory is "C:\Documents and Settings\'username'".

Linux Installation

    In a Linux environment, there is nothing to do other than
    put the noah binary in a location such as /usr/local/bin 
    or /usr/bin and make sure it is found in the users path.

    The users configuration file is stored in  the ~/noah_client 
    directory when noah is started for the first time.

    If you are installing from Debian with the noah .deb file,
    all this is handled for you including installation of a
    man page.


FILES

    Running noah for the first time and answering the questions to
    the init sequence will create a directory in the users home 
    directory by the name of noah_client.

:F   /noah_client/client-help.txt
        Help file (essentially, this file)

:F   /noah_client/config 
        configuration

:F   /noah_client/noah-client-license.txt 
        copyright and more

:F   /noah_client/COPYING   
        GPL license

:F   /noah_client/'hostname'.'username'.reg
        File created by noah to record files that are registered
        for automatic upload or download by the getall or putall 
        commands.

EXAMPLES

noah put -new *.jpg

    This will push all .jpg files in this directory up into
    the database. These will be NEW files so any name matching with
    existing files will be ignored. 

    Since a directory is not specified, the default directory is 
    /UserUploads/'username'. If a file with the same name exists 
    in this directory, the new file will be added to the directory
    with a different document ID number. 

    NOTE that it is possible to have more than one document with 
    the same name in a directory or anywhere in the database 
    as all documents have unique id numbers to distinguish them.

noah put -new *.jpg -nodups

    Same as previous example except if there is a duplicate 
    filename any where in the database, the transfer of that 
    file will be skipped.

noah put shoppinglist.xls

    This command will push 'shoppinglist.xls' up to the database 
    provided the file allready exists. If there is more than 
    one file with that name, the user will be given an option as 
    to which file you want to update. Ofcourse this upload will 
    add another version to the file and set the default version 
    to this latest version.

noah put shoppinglist.xls -notdefault

    This command pushes the new file version up to the database
    but does not change the current default version number. 

AUTHOR
    Harold Blount - Nordicwind Inc. www.nordicwind.ca

REPORTING BUGS
    http://noah.@nordicwind.ca
    
COPYRIGHT
    NOAH - Copyright (c) 2004-2012 Nordicwind Inc.  
    All rights reserved.  

    This is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as 
    published by the Free Software Foundation, version 3 or later
    .

    This software is distributed WITHOUT ANY WARRANTY; without even 
    the implied warranty of MERCHANTABILITY or FITNESS FOR A 
    PARTICULAR PURPOSE.  See the GNU General Public License 
    for more details.


SEE ALSO
    Noah Document Management Server : http://noah.nordicwind.ca