#!/bin/bash
#
# help.sh -- This function standardizes the way documentation is
# produced and maintain inside the working copy of CentOS Artwork
# Repository.
#
# Copyright (C) 2009, 2010, 2011 The CentOS Project
#
# This program 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; either version 2 of the License, or (at
# your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# 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.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
# ----------------------------------------------------------------------
# $Id$
# ----------------------------------------------------------------------
    
function help {
 
    local ACTIONNAM=''
    local ACTIONVAL=''
    local -a ACTIONVALS
 
    # Initialize the search option. The search option (`--search')
    # specifies the pattern used inside info files when an index
    # search is perform.
    FLAG_SEARCH=""
 
    # Initialize the backend option. The backend option (`--backend')
    # specifies the backend used to manipulate the repository
    # documentation manual.
    FLAG_BACKEND="docbook"
 
    # Define file name (without extension) for documentation manual.
    MANUAL_NAME=repository
 
    # Interpret option arguments passed through the command-line.
    ${FUNCNAM}_getOptions
 
    # Initialize backend functions.  There is no need to load all
    # backend-specific functions when we can use just one backend
    # among many. Keep the cli_getFunctions function calling after all
    # variables and arguments definitions.
    cli_getFunctions "${FUNCDIR}/${FUNCDIRNAM}" "${FLAG_BACKEND}"
 
    # Redefine positional parameters using ARGUMENTS. At this point,
    # option arguments have been removed from ARGUMENTS variable and
    # only non-option arguments remain in it. 
    eval set -- "$ARGUMENTS"
 
    # Store remaining arguments into an array. This way it is possible
    # to find out which is the last argument in the list.  When
    # copying files inside the repository, the last argument in the
    # list is considered the target location and all other arguments
    # are considered the source locations. Similary, when renaming
    # files, only two arguments can be passed.
    for ACTIONVAL in "$@";do
        ACTIONVALS[((++${#ACTIONVALS[*]}))]="$ACTIONVAL"
    done
 
    # Enforce conditions against remaining non-option arguments before
    # processing them.
    if [[ ${ACTIONNAM} == ${FUNCNAM}_copyEntry ]];then
 
        # When a documentation entry is copied, we need to determine
        # what location to use as target.  To solve this, the last
        # argument passed to centos-art script is taken as target
        # location. All other arguments previously defined are
        # considered source locations. Notice that more than one
        # source location can be specified, but just one target
        # location can exist.
        local -a ENTRY_SRC
        local ENTRY_DST=''
        local COUNT=0
 
        # Define list of source locations using remaining arguments.
        while [[ ${COUNT} -lt $((${#ACTIONVALS[*]} - 1)) ]];do
            ENTRY_SRC[((++${#ENTRY_SRC[*]}))]=${ACTIONVALS[$COUNT]}
            COUNT=$(($COUNT + 1))
        done
 
        # Define target location.
        ENTRY_DST=$(cli_checkRepoDirTarget "${ACTIONVALS[((${#ACTIONVALS[*]} - 1))]}")
 
        # Define target documentation entry.
        ENTRY_DST=$(help_getEntry "$ENTRY_DST")
 
        # Redefine arguments to store source locations only.
        ARGUMENTS=${ENTRY_SRC[@]}
 
    elif [[ ${ACTIONNAM} == ${FUNCNAM}_renameEntry ]];then
 
        # When documentation entry is renamed, we need to restrict the
        # number of arguments to two arguments only.  More than two
        # arguments are useless since the renaming action works with
        # two arguments only. This is, the source location and the
        # target location.
        local ENTRY_SRC=''
        local ENTRY_DST=''
 
        # Verify number of arguments passed to centos-art.sh script.
        if [[ ${#ACTIONVALS[*]} -gt 2 ]];then
            cli_printMessage "`gettext "Only two arguments are accepted."`" --as-error-line
        elif [[ ${#ACTIONVALS[*]} -lt 2 ]];then
            cli_printMessage "`gettext "Two arguments are required."`" --as-error-line
        fi
 
        # Define source location. 
        ENTRY_SRC=${ACTIONVALS[0]}
 
        # Define target location.
        ENTRY_DST=$(cli_checkRepoDirTarget "${ACTIONVALS[1]}")
 
        # Define target documentation entry.
        ENTRY_DST=$(help_getEntry "${ACTIONVALS[1]}")
 
        # Redefine arguments to store source locations only.
        ARGUMENTS=$ENTRY_SRC
 
    else
 
        # Redefine arguments to store all arguments.
        ARGUMENTS=$@
 
    fi
 
    # Verify non-option arguments.  When non-option arguments are
    # passed to `centos-art.sh' script, use the base manual directory
    # structure. This make possible that option like `--search' and
    # `--update' can be executed without passing any `path/to/dir'
    # information in the command line.
    if [[ $ARGUMENTS == '' ]];then
        ARGUMENTS=${MANUAL_BASEDIR}
    fi
 
    # Define action value. As convenction, we use non-option arguments
    # to define the action value (ACTIONVAL) variable.
    for ACTIONVAL in $ARGUMENTS;do
 
        # Check action value passed through the command-line using
        # source directory definition as reference.
        cli_checkRepoDirSource
    
        # Define manuals base directory. This is the place where
        # documentation manuals base directory structures are stored
        # and organized in.
        MANUAL_BASEDIR="$(cli_getRepoTLDir)/Manuals/$(cli_getRepoName ${FLAG_BACKEND} -d)"
 
        # Define base name for documentation manual files (without
        # extension). This is the main file name used to build output
        # related files (.info, .pdf, .xml, etc.).
        MANUAL_BASEFILE="${MANUAL_BASEDIR}/${MANUAL_NAME}"
 
        # Define function configuration directory. The function
        # configuration directory is used to store functionality's
        # related files.
        MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/Templates
 
        # Define documentation entry.
        ENTRY=$(${FUNCNAM}_getEntry)
 
        # Define documentation entry directory. This is the directory
        # where the entry file is stored.  When the file extension be
        # removed, consider that several backends could be used.
        ENTRY_DIR=$(dirname ${ENTRY} | sed -r "s/\.${FLAG_BACKEND}$//")
 
        # Define documentation entry file (without extension).
        ENTRY_FILE=$(basename ${ENTRY} | sed -r "s/\.${FLAG_BACKEND}$//")
 
        # Define directory to store documentation entries.  At this
        # point, we need to take a desition about documentation
        # design, in order to answer the question: How do we assign
        # chapters, sections and subsections automatically, based on
        # the repository structure?  and also, how such design could
        # be adapted to changes in the repository structure?
        #
        # One solution would be: represent the repository's directory
        # structure as sections inside a chapter named `Directories'
        # or something similar. Subsections and subsubsections will
        # not have their own files, they all will be written inside
        # the same section file that represents the repository
        # documentation entry.
        MANUAL_CHAPTER_DIR=$(echo $ENTRY | cut -d / -f-8)
 
        # Define chapter name for the documentation entry we are
        # working with.
        MANUAL_CHAPTER_NAME=$(basename "$MANUAL_CHAPTER_DIR")
 
        # Syncronize changes between repository and working copy. At
        # this point, changes in the repository are merged in the
        # working copy and changes in the working copy committed up to
        # repository.
        cli_syncroRepoChanges ${MANUAL_CHAPTER_DIR}
 
        # Verify action name against the file ought to be initialized
        # from. If the file exists it is very sure that it has been
        # already initialized, so execute the action name. Otherwise,
        # if the file doesn't exist, print an error message. It is not
        # possible to execute a function which definition hasn't been
        # initialized.
        if [[ -f ${FUNCDIR}/${FUNCDIRNAM}/${ACTIONNAM}.sh  ]];then
            eval $ACTIONNAM
        else
            cli_printMessage "`gettext "A valid action is required."`" --as-error-line
        fi
 
        # Commit changes from working copy to central repository only.
        # At this point, changes in the repository are not merged in
        # the working copy, but chages in the working copy do are
        # committed up to repository.
        cli_commitRepoChanges ${MANUAL_CHAPTER_DIR}
 
    done
 
    # Perform language-specific actions when the current language is
    # other but English language.
    if [[ ! $(cli_getCurrentLocale) =~ '^en' ]];then
 
        # Update translatable strings in related portable objects.
        eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh locale --update ${MANUAL_BASEFILE}.xhtml --dont-commit-changes
 
        # Update translatable strings in related portable objects.
        eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh locale --edit ${MANUAL_BASEFILE}.xhtml
 
        # Print separator.
        cli_printMessage '-' --as-separator-line
 
        # Print action message.
        cli_printMessage "${MANUAL_BASEFILE}.xhtml/$(cli_getCurrentLocale)" '--as-updating-line'
 
        # Render translated versions of the XHTML output files,
        # supressing the rendition output.
        eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh render ${MANUAL_BASEFILE}.xhtml --dont-commit-changes --quiet
 
    fi
 
}