Blame Scripts/Bash/Functions/Help/help.sh

878a2b
#!/bin/bash
878a2b
#
878a2b
# help.sh -- This function initializes the interface used by
878a2b
# centos-art.sh script to perform documentation tasks through
24ece8
# different documentation formats.
878a2b
#
03486a
# Copyright (C) 2009, 2010, 2011, 2012 The CentOS Project
878a2b
#
878a2b
# This program is free software; you can redistribute it and/or modify
878a2b
# it under the terms of the GNU General Public License as published by
878a2b
# the Free Software Foundation; either version 2 of the License, or (at
878a2b
# your option) any later version.
878a2b
#
878a2b
# This program is distributed in the hope that it will be useful, but
878a2b
# WITHOUT ANY WARRANTY; without even the implied warranty of
878a2b
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
878a2b
# General Public License for more details.
878a2b
#
878a2b
# You should have received a copy of the GNU General Public License
878a2b
# along with this program; if not, write to the Free Software
878a2b
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
878a2b
#
878a2b
# ----------------------------------------------------------------------
878a2b
# $Id$
878a2b
# ----------------------------------------------------------------------
878a2b
    
878a2b
function help {
878a2b
878a2b
    # Initialize action name with an empty value.
878a2b
    local ACTIONNAM=''
878a2b
878a2b
    # Initialize search option (`--search'). This option is used to
24ece8
    # look for documentation inside documentation formats.
878a2b
    local FLAG_SEARCH=""
878a2b
878a2b
    # Initialize manual's language.
878a2b
    local MANUAL_L10N=$(cli_getCurrentLocale)
878a2b
878a2b
    # Initialize manuals's top-level directory. This is the place
878a2b
    # where the manual will be stored in. To provide flexibility, the
878a2b
    # current directory where the `centos-art.sh' script was called
878a2b
    # from is used as manual's top-level directory.  Notice that this
878a2b
    # relaxation is required because we need to create/maintain
714232
    # manuals both under `trunk/Documentation/Manuals/' and
714232
    # `branches/Documentation/Manuals/' directories.
878a2b
    local MANUAL_TLDIR=${PWD}
878a2b
878a2b
    # Verify manual's top-level directory. To prevent messing the
4c43b3
    # things up, we need to restrict the possible locations where
4c43b3
    # documentation manuals can be created in the working copy.  When
4c43b3
    # manual's top-level location is other but the ones permitted, use
4c43b3
    # `trunk/Documentation/Manuals/Texinfo' directory structure as
4c43b3
    # default location to store documentation manuals.
4c43b3
    if [[ ! $MANUAL_TLDIR =~ "^${TCAR_WORKDIR}/(trunk|branches)/Documentation/Manuals/Texinfo/[[:alnum:]-]+)$" ]];then
4c43b3
        MANUAL_TLDIR="${TCAR_WORKDIR}/trunk/Documentation/Manuals/Texinfo"
878a2b
    fi
878a2b
878a2b
    # Initialize documentation entries arrays. Arrays defined here
878a2b
    # contain all the information needed to process documentation
878a2b
    # entries (e.g., manual, part, chapter and section).
878a2b
    local -a MANUAL_SLFN
878a2b
    local -a MANUAL_DIRN
878a2b
    local -a MANUAL_PART
878a2b
    local -a MANUAL_CHAP
878a2b
    local -a MANUAL_SECT
878a2b
878a2b
    # Initialize documentation entries counter.
878a2b
    local MANUAL_DOCENTRY_COUNT=0
878a2b
    local MANUAL_DOCENTRY_ID=0
878a2b
878a2b
    # Interpret option arguments passed through the command-line.
878a2b
    help_getOptions
878a2b
878a2b
    # Redefine arrays related to documentation entries using
878a2b
    # non-option arguments passed through the command-line. At this
878a2b
    # point all options have been removed from ARGUMENTS and
878a2b
    # non-option arguments remain. Evaluate ARGUMENTS to retrive the
878a2b
    # information related documentation entries from there.
878a2b
    help_getEntries
878a2b
24ece8
    # Execute format-specific documentation tasks for each
878a2b
    # documentation entry specified in the command-line, individually.
878a2b
    # Notice that we've stored all documentation entries passed as
878a2b
    # non-option arguments in array variables in order to process them
878a2b
    # now, one by one.  This is particularily useful when we need to
878a2b
    # reach items in the array beyond the current iteration cycle. For
878a2b
    # example, when we perform actions that require source and target
878a2b
    # locations (e.g., copying and renaming): we use the current value
878a2b
    # as source location and the second value in the array as target
878a2b
    # location; both defined from the first iteration cycle.
878a2b
    while [[ $MANUAL_DOCENTRY_ID -lt $MANUAL_DOCENTRY_COUNT ]];do
878a2b
878a2b
        # Define name used by manual's main definition file.
878a2b
        MANUAL_NAME=${MANUAL_SLFN[${MANUAL_DOCENTRY_ID}]}
878a2b
878a2b
        # Define absolute path to directory holding language-specific
878a2b
        # directories.
878a2b
        MANUAL_BASEDIR="${MANUAL_TLDIR}/${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]}"
878a2b
878a2b
        # Define absolute path to directory holding language-specific
878a2b
        # texinfo source files.
878a2b
        MANUAL_BASEDIR_L10N="${MANUAL_BASEDIR}/${MANUAL_L10N}"
878a2b
878a2b
        # Define absolute path to changed directories inside the
878a2b
        # manual. For example, when a section entry is edited, copied
878a2b
        # or renamed inside  the same manual there is only one
878a2b
        # aboslute path to look for changes, the one holding the
878a2b
        # section entry.  However, when an entire manual is renamed,
878a2b
        # there might be two different locations to look changes for,
878a2b
        # the source location deleted and the target location added.
878a2b
        MANUAL_CHANGED_DIRS="${MANUAL_BASEDIR_L10N}"
878a2b
878a2b
        # Define absolute path to base file. This is the main file
878a2b
        # name (without extension) we use as reference to build output
878a2b
        # files in different formats (.info, .pdf, .xml, etc.).
878a2b
        MANUAL_BASEFILE="${MANUAL_BASEDIR_L10N}/${MANUAL_NAME}"
878a2b
878a2b
        # Define manual's part name.
878a2b
        MANUAL_PART_NAME=${MANUAL_PART[${MANUAL_DOCENTRY_ID}]}
878a2b
878a2b
        # Define absolute path to manual's part directory.
878a2b
        MANUAL_PART_DIR="${MANUAL_BASEDIR_L10N}/${MANUAL_PART_NAME}"
878a2b
878a2b
        # Define manual's chapter name.
878a2b
        MANUAL_CHAPTER_NAME=${MANUAL_CHAP[${MANUAL_DOCENTRY_ID}]}
878a2b
878a2b
        # Define absolute path to chapter's directory. This is the
878a2b
        # place where chapter-specific files are stored in. Be sure no
878a2b
        # extra slash be present in the value (e.g., when the part
878a2b
        # name isn't provided).
878a2b
        MANUAL_CHAPTER_DIR="$(echo ${MANUAL_PART_DIR}/${MANUAL_CHAPTER_NAME} \
878a2b
            | sed -r 's!/{2,}!/!g' )"
878a2b
878a2b
        # Define section name.
878a2b
        MANUAL_SECTION_NAME=${MANUAL_SECT[${MANUAL_DOCENTRY_ID}]}
878a2b
878a2b
        # Define absolute path to manual's configuration file.  This
878a2b
        # is the file that controls the way template files are applied
878a2b
        # to documentation entries once they have been created as well
878a2b
        # as the style and order used for printing sections. 
878a2b
        MANUAL_CONFIG_FILE="${MANUAL_BASEFILE}.conf" 
878a2b
24ece8
        # Define documentation format. This information defines the
878a2b
        # kind of source files we work with inside the documentation
878a2b
        # manual as well as the kind of actions required by them to
878a2b
        # perform actions related to document management (e.g.,
878a2b
        # creation, edition, deletion, copying, renaming, etc.).
878a2b
        if [[ -f ${MANUAL_CONFIG_FILE} ]];then
878a2b
24ece8
            # Retrive documentation format from configuration file.
24ece8
            MANUAL_FORMAT=$(cli_getConfigValue \
24ece8
                "${MANUAL_CONFIG_FILE}" "main" "manual_format")
878a2b
24ece8
            # Verify documentation format. This is required in order
878a2b
            # to prevent malformed values from being used. Be sure
24ece8
            # only supported documentation formats can be provided as
24ece8
            # value to `manual_format' option inside configuration
878a2b
            # files.
24ece8
            if [[ ! $MANUAL_FORMAT =~ '^(texinfo)$' ]];then
24ece8
                cli_printMessage "`gettext "The documentation format provided isn't supported."`" --as-error-line
878a2b
            fi 
878a2b
878a2b
        else
878a2b
878a2b
            # When the current documentation manual is being created
878a2b
            # for first time, there's no way to get the documentation
24ece8
            # format to use in the future manual, but asking the user
878a2b
            # creating it which one to use.
24ece8
            cli_printMessage "`gettext "Select one of the following documentation formats:"`"
24ece8
            MANUAL_FORMAT=$(cli_printMessage "texinfo" --as-selection-line)
878a2b
878a2b
        fi
878a2b
878a2b
        # Notice that, because we are processing non-option arguments
878a2b
        # one by one, there is no need to sycronize changes or
878a2b
        # initialize functionalities to the same manual time after
878a2b
        # time (assuming all documentation entries passed as
878a2b
        # non-option arguments refer the same manual directory name).
878a2b
        # That would be only necessary when documentation entries
878a2b
        # refer to different manual directory names that could be
24ece8
        # written in different documentation formats.
878a2b
        if [[ ${MANUAL_DOCENTRY_ID} -eq 0 \
878a2b
            || ( ( ${MANUAL_DOCENTRY_ID} -gt 0 ) && ( \
878a2b
            ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} - 1))]} ) ) ]];then
878a2b
878a2b
            # Syncronize changes between repository and working copy.
878a2b
            # At this point, changes in the repository are merged in
878a2b
            # the working copy and changes in the working copy
878a2b
            # committed up to repository.
878a2b
            if [[ -d ${MANUAL_CHANGED_DIRS} ]];then
878a2b
                cli_syncroRepoChanges ${MANUAL_CHANGED_DIRS}
878a2b
            fi
878a2b
24ece8
            # Initialize documentation format functionalities. At
878a2b
            # this point we load all functionalities required into
878a2b
            # `centos-art.sh''s execution environment and make them
24ece8
            # available, this way, to perform format-specific
878a2b
            # documentation tasks.
4c43b3
            cli_exportFunctions "${CLI_FUNCDIRNAM}/$(cli_getRepoName ${MANUAL_FORMAT} -d)/${MANUAL_FORMAT}[[:alpha:]_]*"
878a2b
878a2b
        fi
878a2b
24ece8
        # Execute format-specific documentation tasks.
24ece8
        ${MANUAL_FORMAT}
878a2b
878a2b
        # Unset the exported functions before go on with the next
878a2b
        # documentation entry provided as non-option argument to
878a2b
        # `centos-art.sh' script. Different documentation entries may
24ece8
        # be written in different documentation formats. Each
24ece8
        # documentation format is loaded in order to perform their
878a2b
        # related documentation tasks. Assuming more that one
878a2b
        # documentation entry be passed as non-option argument to
878a2b
        # `centos-art.sh' script and they are written in different
24ece8
        # formats, we might end up loading documentation format
878a2b
        # functionalities that aren't used in the current
878a2b
        # documentation entry being processed. In that sake, unset
878a2b
        # documentation bakend functionalities when the next
878a2b
        # documentation entry refers to a manual directory different
878a2b
        # to that one being currently processed.
878a2b
        if [[ ${MANUAL_DOCENTRY_ID} -gt 0 \
878a2b
            && ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} + 1))]} ]];then
878a2b
            cli_unsetFunctions "${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \
24ece8
                ${MANUAL_FORMAT} -d)" "${MANUAL_FORMAT}"
878a2b
        fi
878a2b
878a2b
        # Increment documentation entry counter id.
878a2b
        MANUAL_DOCENTRY_ID=$(($MANUAL_DOCENTRY_ID + 1))
878a2b
878a2b
    done
878a2b
878a2b
    # Syncronize changes between repository and working copy. At this
878a2b
    # point, changes in the repository are merged in the working copy
878a2b
    # and changes in the working copy committed up to repository.
878a2b
    cli_syncroRepoChanges ${MANUAL_CHANGED_DIRS}
878a2b
878a2b
}