source: branches/confman-1.9/confmandoc.sh @ 589

# Copyright (c) 2008, Christopher Cowart and contributors
# All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions 
# are met:
# * Redistributions of source code must retain the above copyright 
#   notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright 
#   notice, this list of conditions and the following disclaimer in the 
#   documentation and/or other materials provided with the distribution.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# $Id$
#
# This is a confman shell library that provides usage and help information.
# I wanted to get it out of the main script, cause it's really long. This also
# makes modularizing the code (think foreign languages) in the future.

function print_usage {
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME [ help | -h ] [ command ]
  $MYNAME setup
  $MYNAME update [ -a ] [ -r revision_string ] [ recipe ]
  $MYNAME commit
  $MYNAME diff [ working_copy ]
  $MYNAME audit
  $MYNAME log [ working_copy ]
  $MYNAME create module [ module ... ]
  $MYNAME rmmod module [ module ... ]
  $MYNAME rename oldmodule newmodule
  $MYNAME import module livefile
  $MYNAME install workingfile [ workingfile ... ]
  $MYNAME status [ working_copy ]
  $MYNAME state
  $MYNAME ls [ workingfile | workingdirectory ]
  $MYNAME lsattr [ workingfile | workingdirectory ]
  $MYNAME chattr attribute value [ workingfile | workingdirectory ]
  $MYNAME recipe [ get | list ]
  $MYNAME recipe [ create | edit | print | remove | set ] recipe_name
  $MYNAME rmattr attribute [ workingfile | workingdirectory ]
  $MYNAME rm workingfile
  $MYNAME cp src_working_copy dest_working_copy
  $MYNAME mv src_working_copy dest_working_copy
  $MYNAME mkdir workingdirectory
  $MYNAME touch workingfile
  $MYNAME revert workingfile
  $MYNAME chown owner [ workingfile | workingdirectory ] 
  $MYNAME chgrp group [ workingfile | workingdirectory ] 
  $MYNAME chmod mode  [ workingfile | workingdirectory ] 
  $MYNAME chcom comment-character [ workingfile | workingdirectory ] 
  $MYNAME chln target link_name 
  $MYNAME checklook module
  $MYNAME checknew module name
  $MYNAME checkclear module name
  $MYNAME rollback module [ checkpoint | YYYYMMDD [HHMM] ]

For specific information on a particular $MYNAME subcommand, please run
  $MYNAME help subcommand

eg: $MYNAME help rollback

EOF

conf_cleanExit $1
}

function print_help {
    [ -z "$1" ] && print_usage 0

  case $1 in
          se* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME setup

The setup command is intended to be run the first time you use $MYNAME.
It will generate your working copy. setup takes no additional arguments.

EOF
;;
          cr* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME create module [ module ... ]

Creates one or more modules for the module arguments provided.
New modules will appear in the top-level-directory of your work-
ing copy.  This change will also be committed to the repository
at the same time.

EOF
;;
          rmm* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME rmmod [ module ... ]

Delete the modules corresponding to the specified module argu-
ments from your working copy. Follow this action with a revert or
commit operation.

EOF
;;
          ren* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME rename oldmodule newmodule

Rename oldmoule to newmodule, updating all singularities, headers, and 
otherwise performing black magic.

EOF
;;
          u* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME update [ -a ] [ -r revision_string ] [ recipe ]

With no arguments, the update command will update your entire working copy 
unless the UPDATE_RELEVANT_ONLY flag is set in confman.conf or your 
~/.confmanrc.  With the UPDATE_RELEVANT_ONLY flag, the default behavior of 
the update command is to update all of the files appearing in the current 
host's recipe file.  With a recipe argument, the update command will update 
all files in the working copy relevant to the recipe.  This command does not 
alter the repository.

If -r is used, confman will retrieve versions of the files indicated by 
the revision string, e.g., -r PREV for the previous working copy.

The -a option will force a full update of all files in your working copy, 
regardless of whether UPDATE_RELEVANT_ONLY is set.  Note that before any
install or commit operation, there is an implicit update that will cause
the latest repository revision to be reflected in your working copy.

EOF
;;
          d* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME diff [ working_copy ]

Look at the changes you've made to your working copy of a file or directory.
EOF
;;
          lo* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME log [ working_copy ]

Look at the log entries for the file or directory specified by working_copy.
EOF
;;
          status )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME status [ working_copy ]

Look at the status entries for the file or directory specified by working_copy.
EOF
;;
          state )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME state

This command indicates whether the system is "dirty" or "clean."

A dirty system is one that has missed an automated "sync" operation in order
to preserve changes made by installation operations occuring between the
repository's export and the system's call to "sync."

Dirty systems may have out-of-date configuration files. Subsquent sync or
commit operations can bring the sytem up-to-date.
EOF
;;
          cp )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME cp src_working_copy dest_working_copy

Copy source to destination. Arguments must be working copies.
EOF
;;
          mv )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME mv src_working_copy dest_working_copy

Move source to destination. Arguments must be working copies.
EOF
;;
          co* )
cat <<EOF
$MYNAME manages configuration files

Usage:
    $MYNAME commit [ -F filename | -m message ]

The commit command causes your changes to take effect. This means that
first, your working copy of all of the modules in the current host's 
recipe will be committed to the repository. This happens after we've run
a $MYNAME update to prevent out-of-date conflicts. If there are any 
conflicts that require human intervention, the command will fail and exit 
non-zero. 

Once $MYNAME is satisfied that all of your changes have been propogated to
the repository, we will roll-out your working copy to the live filesystem.
Every module appearing in the host's recipe file will be rolled out IN THE
ORDER OF APPEARANCE.

If -F or -m are used, the log message will be read from the filename or
the commandline, respectively, instead of prompting the user.

EOF
;;
          im* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME import module livefile

The import subcommand adds the specified file to your working copy of the
repository. 

EOF
;;
          in* )
cat <<EOF
$MYNAME manages configuration files

Usage:
    $MYNAME install [-F filename | -m message] workingfile [workingfile [...]]

The install subcommand allows you to roll out a single file from your working
copy.

If -F or -m are used, the log message will be read from the filename or
the commandline, respectively, instead of prompting the user.

EOF
;;
          rev* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME revert workingfile [ workingfile ... ]

The revert subcommand gives you the opportunity to revert to the file before
you started making changes to it.

EOF
;;
          rm )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME rm file

The remove subcommand removes a file from version control It will NOT remove 
the file from the live filesystem. 

EOF
;;
          mk* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME mkdir directory 

This command will create a new version-controlled directory in your working
copy.  Parent directories do not have to exist; they will be created 
automagically. This command only affects your working copy. It does not commit 
the change.

EOF
;;
          ls )
cat<<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME ls [ file | directory ]

The ls subcommand lists out the contents, in modified long form, of the
current working directory. If a file or directory is specified, it will list
that instead.

EOF
;;
    link | ln )
cat<<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME ( link | ln ) [-f] ( file | directory ) ( link_name | directory)

The ln subcommand creates a symlink within the repository.  The first
argument is the target of the link, which can be either a file or a
directory.  The second argument is either the name of a link or the
directory in which to create a link of the same name as the target.
The force command causes ln to ignore any files or links already
present when creating the link. 
EOF
;;
          lsattr )
cat<<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME lsattr [ file | directory ]

The lsattr subcommand lists out the confman attributes of files in the
repository. These attributes can be used to store information such as
file permissions, ownership, comment characters, syntax checkers, and
even commands to execute when changing the file.

EOF
;;
          chattr )
cat<<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME chattr attribute value [ file | directory ]

The chattr subcommand alters the confman attributes of files in the
repository. These attributes can be used to store information such as
file permissions, ownership, comment characters, syntax checkers, and
even commands to execute when changing the file.

EOF
;;
          rmattr )
cat<<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME rmattr attribute [ file | directory ]

The rmattr subcommand removes the confman attributes of files in the
repository. These attributes can be used to store information such as
file permissions, ownership, comment characters, syntax checkers, and
even commands to execute when changing the file.

EOF
;;
          cho* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME chown [ -R ] owner [ file | directory ] 

The chown command works like it's unix equivalent. It does not support
user:group notation. The only option it will take is -R for recursive.

EOF
;;
          chg* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME chgrp group [ file | directory ] 

The chgrp command works like it's unix equivalent. The only option it will take
is -R for recursive.

EOF
;;
          chm* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME chmod mode [ file | directory ] 

The chmod command works like it's unix equivalent. Note that it will only
accept octets as permissions -- it will not interpret symbolic permissions
correctly. The only option it will take is -R for recursive.

EOF
;;
          chc* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME chcom comment-character [ file | directory ] 

The chcom subcommand takes a file or directory as an argument and changes the
comment string associated with it. This will typically only be useful when
confman has guessed the comment character of your file incorrectly.

EOF
;;
    chl* )
cat <<EOF
$MYNAME manages configuration files

Usage:
   $MYNAME chln target link_name

The chln subcommand takes a confman link as an argument and changes the
target on the live filesystem to which it points.  This works for
"simulated" symlinks to files on the live filesystem, not on actual
symlinks within your confman working copy.
EOF
;;
          checkl* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME checklook module

The checklook command peeks into the checkpoints for the specified module
and gives you a listing of current checkpoints with some other cool info.
This command does not alter the repository.

EOF
;;
          checkn* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME checknew module name

The newcheck command creates a named checkpoint for the specified module.
This change is committed to the repository immediately.

EOF
;;
          checkc* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME checkclear module name

The rmcheck command clears a named checkpoint from the specified module. 
This change is committed to the repository immediately.

EOF
;;
          ro* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME rollback module [ checkpoint | YYYYMMDD [HHMM] ]

The rollback command first rolls your working copy of module back to the
named checkpoint. You can optionally roll-back to a specific point in time
using a date (and optionally time) as specified in the usage statement. 
This change is immediately committed to the repository.

After the rollback is complete, we perform the equivalent of a:
  $MYNAME commit

EOF
;;
    rec* )
cat <<EOF
$MYNAME manages configuration files

Usage:
  $MYNAME recipe [ get | list ]
  $MYNAME recipe [ print | edit ] [ recipe_name ]
  $MYNAME recipe set recipe_name
  $MYNAME recipe [ create | remove ] [ -F file | -m msg ] recipe_name

The recipe command provides an interface to manage confman recipes.

    create      Create a recipe with the given name
    edit        Edit a recipe with the given name
    get         List the host's recipe
    list        List all recipes
    print       Print the given recipe (defaults to this host's recipe)
    remove      Delete a recipe with the given name
    set         Set the host's recipe to the given name

EOF
;;
          * )
print_usage 1
;;
esac
return 0
}