diff --git a/Scripts/Functions/Help/Texinfo/Templates/manual.conf b/Scripts/Functions/Help/Texinfo/Templates/manual.conf index 84665c4..0aebfe4 100755 --- a/Scripts/Functions/Help/Texinfo/Templates/manual.conf +++ b/Scripts/Functions/Help/Texinfo/Templates/manual.conf @@ -1,7 +1,7 @@ -# This file defines what template file a documentation entry uses. -# Definition of template files is set on the left side and the regular -# expression pattern matching the documentation entry file on the -# right side. The first match wins. +# This file controls what template a section's main definition files +# does use. Template definition is set on the left side using relative +# paths. The section's main definition file is set on the right using +# a regular expression. The first match wins. # ---------------------------------------------------------------------- # $Id$ # ---------------------------------------------------------------------- diff --git a/Scripts/Functions/Help/Texinfo/texinfo.sh b/Scripts/Functions/Help/Texinfo/texinfo.sh index 8a63912..2982c29 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo.sh @@ -1,9 +1,9 @@ #!/bin/bash # -# help.sh -- This function implements Texinfo documentation backend. -# This is, the collection of frequent actions required to produce and -# maintain The CentOS Artwork Repsoitory user's guide in Texinfo -# format. +# texinfo.sh -- This function initilializes the Texinfo documentation +# backend used by centos-art.sh script to produce and maintain Texinfo +# documentation manuals inside the working copy of The CentOS Artwork +# Repository. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -27,49 +27,52 @@ function texinfo { - # Define file extension used by documentation manual source files. + # Define file extension used by source files inside manuals. MANUAL_EXTENSION='texinfo' - # Define manual base directory. This is the place where - # language-specific documentation source files are stored in. + # Define absolute path to directory holding language-specific + # texinfo source files. MANUAL_BASEDIR="${MANUAL_TLDIR}/${MANUAL_L10N}" - # 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.). + # Define absolute path to base file. This is the main file name + # (without extension) we use as reference to build output files in + # different formats (.info, .pdf, .xml, etc.). MANUAL_BASEFILE="${MANUAL_BASEDIR}/${MANUAL_NAME}" - # Define default behaviour when no action has been provided to - # `centos-art.sh' script command-line interface. + # Verify existence of action names. When no action name is + # provided to centos-art.sh script, read manual's output in info + # format in order to provide a way for people to get oriented + # about The CentOS Artwork Repository and its automation tool, the + # centos-art.sh script. Be sure the manual's output file does + # exist and terminate the script execution once the reading is + # done. if [[ $ACTIONNAM == '' ]];then + + # Verify existence of manual's output in info format. + cli_checkFiles ${MANUAL_BASEFILE}.info.bz2 + + # Read Top node from manual's output in info format. /usr/bin/info --node="Top" --file=${MANUAL_BASEFILE}.info.bz2 + + # Terminate script execution right here. exit + fi - # Define chapter name of directory where repository documentation - # entries will be stored in. - MANUAL_CHAPTER_NAME=$(cli_getRepoName "Directories" -d) - - # Define absolute path to chapter directory where repository - # documentation entries will be stored in. 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=${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} - - # Define absolute path to template directory. + # Define absolute path to chapter's directory. This is the place + # where chapter-specific files are stored in. + MANUAL_CHAPTER_DIR=${MANUAL_BASEDIR}/$(cli_getRepoName \ + "${MANUAL_CHAPTER_NAME}" -d | tr -d ' ' | sed -r 's!/$!!') + + # Define absolute path to template directory. This is the place + # where we store locale directories (e.g., en_US, es_ES, etc.) + # used to build manuals in texinfo format. MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/$(cli_getRepoName \ - $MANUAL_BACKEND -d)/Templates + ${FLAG_BACKEND} -d)/Templates - # Define absolute path to language-speicific template directory. + # Define absolute path to language-specific template directory. + # This is the place where we store locale-specific files used to + # build manuals in texinfo format. MANUAL_TEMPLATE_L10N=${MANUAL_TEMPLATE}/${MANUAL_L10N} # Verify absolute path to language-speicific template directory. @@ -79,62 +82,81 @@ function texinfo { MANUAL_TEMPLATE_L10N=${MANUAL_TEMPLATE}/en_US fi - # Create documentation structure, if it doesn't exist. - ${MANUAL_BACKEND}_createStructure - - # 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_BASEDIR} + # Initialize document structure of new manuals. + ${FLAG_BACKEND}_createStructure - # Execute backend functionalities. Notice that there are - # functionalities that need more than one action value in order to - # be executed (e.g., copying, and renaming), functionalities - # that need just one action value to be executed (e.g., - # documentation reading and edition) and functionalities that - # don't need action value at all (e.g., searching, reading and - # updating output files). This way, the execution of backend - # functionalities is splitted here. - if [[ $ACTIONNAM =~ "^(copy|rename|delete)Entry$" ]];then + # Execute action names. Notice that we've separated action name + # execution in order to control and save the differences among + # them. For example, there are action names that need a fixed + # amount of non-option arguments (e.g., when we rename or copy + # documentation entries); but there are other action names that + # have no restriction in the amount of non-option arguments that + # can be provided to it (e.g., when we edit, read or delete + # documentation entries). + if [[ $ACTIONNAM =~ "^(copy|rename)Entry$" ]];then # Execute backend action names that may need to use more than # one action value. - ${MANUAL_BACKEND}_${ACTIONNAM} $@ + ${FLAG_BACKEND}_${ACTIONNAM} + + # Rebuild output files to propagate recent changes. + ${FLAG_BACKEND}_updateOutputFiles + + # 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_BASEDIR} - elif [[ $ACTIONNAM =~ "^(search(Index|Node)|updateOutputFiles)$" ]];then + # Terminate script execution right here. + exit + + elif [[ $ACTIONNAM =~ "^(searchIndex|updateOutputFiles)$" ]];then - # Execute backend action names that might not need any action - # value as reference to do their work. - ${MANUAL_BACKEND}_$ACTIONNAM $@ + # Execute backend action names which don't require non-option + # arguments to be passed at all, in order for them to do their + # work. + ${FLAG_BACKEND}_${ACTIONNAM} - # Backend action names that don't need to use any action value - # as reference to do their work are of one-pass only. They are - # executed and then the script execution is finished. + # Terminate script execution right here. exit else - # Execute backend action names that use one action value, only. - for ACTIONVAL in $@;do - - # Define documentation entry. - MANUAL_ENTRY=$(${MANUAL_BACKEND}_getEntry $ACTIONVAL) + # Define documentation entry. To build the documentation + # entry, we combine the manual's name, the chapter's name and + # the section name retrived from the command-line. + if [[ $MANUAL_CHAPTER_NAME == '' ]];then - # Execute backend action names that may need to use more - # than one action value. - ${MANUAL_BACKEND}_$ACTIONNAM + # When chapter option is not provided, discard the section + # name and define documentation entry based on manual's + # main definition file. + MANUAL_ENTRY="${MANUAL_BASEFILE}.${MANUAL_EXTENSION}" - done + elif [[ $MANUAL_CHAPTER_NAME != '' ]] && [[ $MANUAL_SECTION_NAME == '' ]];then - fi + # When chapter option is provided whith out a section + # name, verify chapter's directory inside the manual, + ${FLAG_BACKEND}_createChapter + + # and define documentation entry based on chapter's main + # definition file. + MANUAL_ENTRY="${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME}/chapter.${MANUAL_EXTENSION}" - # 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_BASEDIR} + elif [[ $MANUAL_CHAPTER_NAME != '' ]] && [[ $MANUAL_SECTION_NAME != '' ]];then - # Rebuild output files to propagate recent changes. - ${MANUAL_BACKEND}_updateOutputFiles + # When both the chapter option and non-option arguments + # are provided, define documentation entries based on + # manual, chapter and non-option arguments. + MANUAL_ENTRY="$(${FLAG_BACKEND}_getEntry "$MANUAL_SECTION_NAME")" + + else + cli_printMessage "`gettext "The parameters you provided are not supported."`" --as-error-line + fi + + # Execute action name on documentation entry. + ${FLAG_BACKEND}_$ACTIONNAM + + fi } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_copyEntry.sh b/Scripts/Functions/Help/Texinfo/texinfo_copyEntry.sh index 246aad2..05b0710 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_copyEntry.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_copyEntry.sh @@ -1,8 +1,9 @@ #!/bin/bash # -# texinfo_copyEntry.sh -- This function copies documentation entries -# inside the working copy and updates the documentation structure to -# reflect the changes. +# texinfo_copyEntry.sh -- This function standardizes the duplication +# actions related to manuals written in texinfo format. This function +# duplicates manuals, chapters inside manuals, and sections inside +# chapters. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -26,84 +27,81 @@ function texinfo_copyEntry { - # Verify number of non-option arguments passed to centos-art.sh - # script. - if [[ $# -lt 2 ]];then - cli_printMessage "`gettext "Two paths are required."`" --as-error-line - elif [[ $# -gt 2 ]];then - cli_printMessage "`gettext "Only two paths are supported."`" --as-error-line - fi - - # Print separator line. - cli_printMessage '-' --as-separator-line - - # Define source documentation entry. This is the documentation - # entry that will be duplicated. - local MANUAL_ENTRY_SRC=$(${MANUAL_BACKEND}_getEntry "${1}") + local MANUAL_ENTRY_SRC='' + local MANUAL_ENTRY_DST='' + local MANUAL_ENTRY='' + local MANUAL_ENTRIES='' - # Define target documentation entry. This is the new documentation - # entry created from the source documentation entry. - local MANUAL_ENTRY_DST=$(${MANUAL_BACKEND}_getEntry "${2}") + # Define both source and target documentation entries. To build + # the source and target documentation entries we take into + # consideration the manual's main definition file, the chapter's + # main definition file and non-option arguments passed to + # centos-art.sh script through the command-line. + if [[ ${MANUAL_SECN[${MANUAL_DOCENTRY_ID}]} != '' ]];then - # Verify parent directory of target documentation entry. If it - # doesn't exist, create it and add it to version control. - if [[ ! -d $(dirname ${MANUAL_ENTRY_DST}) ]];then - mkdir -p $(dirname ${MANUAL_ENTRY_DST}) - svn add $(dirname ${MANUAL_ENTRY_DST}) --quiet - fi + if [[ ${MANUAL_SECN[((${MANUAL_DOCENTRY_ID} + 1))]} != '' ]];then - # Copy source documentation entry to target documentation entry. - if [[ -f ${MANUAL_ENTRY_SRC} ]];then - if [[ ! -f ${MANUAL_ENTRY_DST} ]];then - cli_printMessage "${MANUAL_ENTRY_DST}" --as-creating-line - svn cp "${MANUAL_ENTRY_SRC}" "${MANUAL_ENTRY_DST}" --quiet - else - cli_printMessage "`gettext "The target location is not valid."`" --as-error-line - fi - else - cli_printMessage "`gettext "The source location is not valid."`" --as-error-line - fi + # When the section name is specified both in first and + # second non-option arguments, source and target are set + # as specified in first and second non-option arguments + # respectively. - # Redefine both source and target locations to refer the directory - # where dependent documentation entries are stored in. - MANUAL_ENTRY_SRC=$(echo ${MANUAL_ENTRY_SRC} | sed -r "s/\.${MANUAL_EXTENSION}$//") - MANUAL_ENTRY_DST=$(echo ${MANUAL_ENTRY_DST} | sed -r "s/\.${MANUAL_EXTENSION}$//") + # Define documentation entry source's location. + MANUAL_ENTRY_SRC=$(${FLAG_BACKEND}_getEntry ${MANUAL_SECN[${MANUAL_DOCENTRY_ID}]}) - # Copy dependent documentation entries, if any. - if [[ -d ${MANUAL_ENTRY_SRC} ]];then - if [[ ! -a ${MANUAL_ENTRY_DST} ]];then - cli_printMessage "${MANUAL_ENTRY_DST}" --as-creating-line - svn cp "${MANUAL_ENTRY_SRC}" "${MANUAL_ENTRY_DST}" --quiet - fi - fi + # Define documentation entry target's location. + MANUAL_ENTRY_DST=$(${FLAG_BACKEND}_getEntry ${MANUAL_SECN[((${MANUAL_DOCENTRY_ID} + 1))]}) - # Define list of target documentation entries. - local MANUAL_ENTRY='' - local MANUAL_ENTRIES=$(cli_getFilesList \ - $(dirname ${MANUAL_ENTRY_DST}) \ - --pattern="${MANUAL_ENTRY_DST}.*\.${MANUAL_EXTENSION}") + elif [[ ${MANUAL_SECN[((${MANUAL_DOCENTRY_ID} + 1))]} == '' ]] \ + && [[ ${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} != '' ]];then - # Print separator line. - cli_printMessage '-' --as-separator-line + # When the section name is specified only in the first + # non-option argument and the chapter name has been + # provided in the second non-option argument, use the + # section name passed in first argument to build the + # section name that will be used as target. - # Print action message. - cli_printMessage "`gettext "Updating menus, nodes and cross-references."`" --as-response-line + # Define documentation entry source's location. + MANUAL_ENTRY_SRC=$(${FLAG_BACKEND}_getEntry ${MANUAL_SECN[${MANUAL_DOCENTRY_ID}]}) - # Loop through target documentation entries in order to update - # the documentation structure (e.g., It is not enough with copying - # documentation entry files, it is also needed to update menu, - # nodes and related cross-references). - for MANUAL_ENTRY in ${MANUAL_ENTRIES};do + # Define documentation entry target's location. + MANUAL_ENTRY_DST=$(echo $MANUAL_ENTRY_SRC \ + | sed -r "s!${MANUAL_CHAN[${MANUAL_DOCENTRY_ID}]}!${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]}!") - # Update menu and node definitions from manual sections to - # reflect the changes. - ${MANUAL_BACKEND}_updateMenu - ${MANUAL_BACKEND}_updateNodes + else + cli_printMessage "`gettext "The location provided as target isn't valid."`" --as-error-line + fi - # Update cross reference definitions from manual to reflect - # the changes. - ${MANUAL_BACKEND}_restoreCrossReferences $MANUAL_ENTRY + # Copy documentation entry using source and target locations. + ${FLAG_BACKEND}_copyEntrySection + + elif [[ ${MANUAL_CHAN[${MANUAL_DOCENTRY_ID}]} != '' ]] \ + && [[ ${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} != '' ]];then + + # In this configuration, the section name wasn't specified + # neither in first or second non-option argument. So, we + # perform a copying action for the chapter directory itself. + # In this configuration, the whole chapter directory and all + # the content inside it is duplicated from source to target. + ${FLAG_BACKEND}_copyEntryChapter + + elif [[ ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != '' ]] \ + && [[ ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} + 1))]} != '' ]];then + + # In this configuration, the chapter name wasn't specified + # neither in first or second non-option argument. So, we + # perform copying actions on manual directory itself. Notice + # that, in this configuration, the whole manual is duplicated. + ${FLAG_BACKEND}_copyEntryManual + + # In this configuration, there is no need to update section + # menus, nodes and cross refereces. The section definition + # files were copied from the source manual with any change so + # the manual should build without any problem. Be sure such + # verification will never happen. - done + else + cli_printMessage "`gettext "The parameters you provided are not supported."`" --as-error-line + fi } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_copyEntryChapter.sh b/Scripts/Functions/Help/Texinfo/texinfo_copyEntryChapter.sh new file mode 100755 index 0000000..f37f1c6 --- /dev/null +++ b/Scripts/Functions/Help/Texinfo/texinfo_copyEntryChapter.sh @@ -0,0 +1,82 @@ +#!/bin/bash +# +# texinfo_copyEntryChapter.sh -- This function standardizes chapter +# duplication inside manuals written in texinfo format. +# +# Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG +# +# 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 texinfo_copyEntryChapter { + + # Define documentation entry source's location. + local MANUAL_ENTRY_SRC=${MANUAL_BASEDIR}/${MANUAL_CHAN[${MANUAL_DOCENTRY_ID}]} + + # Redefine chapter name using chapter name passed to + # `centos-art.sh' script as second non-option argument. + local MANUAL_CHAPTER_NAME=${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} + + # Define documentation entry target's location. + local MANUAL_ENTRY_DST=${MANUAL_BASEDIR}/${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} + + # When we are copying chapters, the source location and the target + # location must be different in value. They cannot point to the + # same chapter directory. + if [[ $MANUAL_ENTRY_SRC == $MANUAL_ENTRY_DST ]];then + cli_printMessage "`gettext "The chapter cannot be copied into itself."`" --as-error-line + fi + + # When we are copying chapters, document structure actualization + # needs to be performed against the target chapter not the source + # one used to create the duplication. To achieve this goal, + # redefine both chapter's directory and chapter's name at this + # point. + local MANUAL_CHAPTER_DIR=$MANUAL_ENTRY_DST + local MANUAL_CHAPTER_NAME=${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} + + # When we are copying chapters, the chapter itself cannot be + # copied as we regularly do with sections. Instead, the target + # chapter must be created as a new chapter and then sections from + # source chapter must be copied one by one to the recently created + # chapter. At this point then, is when menu, nodes and cross + # references for the new chapter are updated. + ${FLAG_BACKEND}_createChapter + + # Create list of sections from source chapter that need to be + # copied to target chapter. Don't include chapter main definition + # files. + local MANUAL_ENTRIES=$(cli_getFilesList $MANUAL_ENTRY_SRC \ + --pattern="${MANUAL_ENTRY_SRC}.*\.${MANUAL_EXTENSION}" \ + | egrep -v '/chapter') + + # Copy sections from source chapter to target chapter. + for MANUAL_ENTRY in $MANUAL_ENTRIES;do + svn cp $MANUAL_ENTRY $MANUAL_ENTRY_DST --quiet + done + + # At this point, all copying actions had took place and it is time + # to update the document structure. Start updating chapter + # menu and nodes inside manual structure, + ${FLAG_BACKEND}_updateChaptersMenu + ${FLAG_BACKEND}_updateChaptersNodes + + # and section menu, nodes and cross references later. + ${FLAG_BACKEND}_updateStructureSection ".+\.${MANUAL_EXTENSION}" + +} diff --git a/Scripts/Functions/Help/Texinfo/texinfo_copyEntryManual.sh b/Scripts/Functions/Help/Texinfo/texinfo_copyEntryManual.sh new file mode 100755 index 0000000..5d3c275 --- /dev/null +++ b/Scripts/Functions/Help/Texinfo/texinfo_copyEntryManual.sh @@ -0,0 +1,75 @@ +#!/bin/bash +# +# texinfo_copyEntryChapter.sh -- This function standardizes +# duplication of manuals written in texinfo format. +# +# Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG +# +# 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 texinfo_copyEntryManual { + + # Define list of chapters inside source manual excluding those + # created from template, rendition output and subversion. + local MANUAL_CHAPTER='' + local MANUAL_CHAPTERS=$(cli_getFilesList ${MANUAL_BASEDIR} \ + --maxdepth=1 --mindepth=1 --type="d" --pattern='.+' \ + | egrep -v "(Licenses|\.svn|${MANUAL_NAME}-xhtml)$") + + # Redefine manual name using manual name passed to `centos-art.sh' + # script as second non-option argument. + MANUAL_NAME=${MANUAL_SLFN[((${MANUAL_DOCENTRY_ID} + 1))]} + + # Redefine absolute path to manual directory using manual name + # passed to `centos-art.sh' script as second non-option argument. + MANUAL_TLDIR="$(echo $MANUAL_TLDIR \ + | sed -r "s!${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]}!${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} + 1))]}!")" + + # Redefine absolute path to manual directory using manual name + # passed to `centos-art.sh' script as second non-option argument. + MANUAL_BASEDIR="${MANUAL_TLDIR}/${MANUAL_L10N}" + + # Redefine absolute path to base file using manual name passed to + # `centos-art.sh' script as second non-option argument. + MANUAL_BASEFILE="${MANUAL_BASEDIR}/${MANUAL_NAME}" + + # Create manual structure + ${FLAG_BACKEND}_createStructure + + # Print action maessage. + cli_printMessage "`gettext "Updating chapter menus and nodes inside manual structure."`" --as-response-line + + # Loop through list of chapters. + for MANUAL_CHAPTER in ${MANUAL_CHAPTERS};do + + # Copy chapter directory from source to target using + # subversion. + svn cp ${MANUAL_CHAPTER} ${MANUAL_BASEDIR} --quiet + + # Define manual chapter name. + local MANUAL_CHAPTER_NAME=$(basename ${MANUAL_CHAPTER}) + + # Update chapter information inside the manual's texinfo + # structure. + ${FLAG_BACKEND}_updateChaptersMenu + ${FLAG_BACKEND}_updateChaptersNodes + + done + +} diff --git a/Scripts/Functions/Help/Texinfo/texinfo_copyEntrySection.sh b/Scripts/Functions/Help/Texinfo/texinfo_copyEntrySection.sh new file mode 100755 index 0000000..1d0eeb5 --- /dev/null +++ b/Scripts/Functions/Help/Texinfo/texinfo_copyEntrySection.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# +# texinfo_copyEntrySection.sh -- This function standardizes section +# duplication inside manuals written in texinfo format. +# +# Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG +# +# 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 texinfo_copyEntrySection { + + # Verify source and target locations to be sure they are different + # one another. We cannot copy a source location to itself. + if [[ $MANUAL_ENTRY_SRC == $MANUAL_ENTRY_DST ]];then + cli_printMessage "`gettext "The source and target locations cannot be the same."`" --as-error-line + fi + + # Print separator line. + cli_printMessage '-' --as-separator-line + + # Redefine chapter name using chapter name passed to + # `centos-art.sh' script as second non-option argument. + MANUAL_CHAPTER_NAME=${MANUAL_CHAN[((${MANUAL_DOCENTRY_ID} + 1))]} + + # Redefine chapter directory to use the chapter provided to + # `centos-art.sh' script as second non-option argument. This is + # required in order to update the `chapter-menu.texinfo' file on + # the target chapter the documentation entry was copied in, not + # the source chapter where the documentation entry was taken from. + # This is particulary useful when a documentation entry is copied + # from one chapter to another different. + MANUAL_CHAPTER_DIR=$(dirname ${MANUAL_ENTRY_DST}) + + # When we copy sections, the chapter directory where the section + # copied will be placed in must exist first. In that sake, verify + # the chapter directory of target documentation entry and if it + # doesn't exist, create it adding it to version control. + if [[ ! -d $(dirname ${MANUAL_ENTRY_DST}) ]];then + svn mkdir $(dirname ${MANUAL_ENTRY_DST}) --quiet + fi + + # Copy documentation entry from source to target using subversion. + if [[ -a ${MANUAL_ENTRY_SRC} ]];then + if [[ ! -a ${MANUAL_ENTRY_DST} ]];then + cli_printMessage "${MANUAL_ENTRY_DST}" --as-creating-line + svn cp "${MANUAL_ENTRY_SRC}" "${MANUAL_ENTRY_DST}" --quiet + else + cli_printMessage "`gettext "The target location is not valid."`" --as-error-line + fi + else + cli_printMessage "`gettext "The source location is not valid."`" --as-error-line + fi + + # At this point, all copying actions had took place and it is time + # to update the document structure. + ${FLAG_BACKEND}_updateStructureSection "${MANUAL_ENTRY_DST}" + +} diff --git a/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh b/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh index 43b8588..d730224 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh @@ -1,7 +1,7 @@ #!/bin/bash # -# texinfo_createChapters.sh -- This function creates the chapters' -# base directory structure using templates as reference. +# texinfo_createChapter.sh -- This function creates manual's chapters +# based on templates. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -23,46 +23,83 @@ # $Id$ # ---------------------------------------------------------------------- -function texinfo_createChapters { +function texinfo_createChapter { - local MANUAL_CHAPTER_NAME='' + # Verify chapter's directory inside the manual. The chapter's + # directory is where chapter-specific information (e.g., manual's + # sections) are stored in. If this directory already exist, + # assume it was created correctly in the past. Otherwise, prompt + # its creation. + if [[ -d $MANUAL_CHAPTER_DIR ]];then + return + else + cli_printMessage "`gettext "The following documentation chapter will be created:"`" + cli_printMessage "${MANUAL_CHAPTER_DIR}" --as-response-line + cli_printMessage "`gettext "Do you want to continue?"`" --as-yesornorequest-line + fi - # Define list of chapter templates files used as base to create - # the chapters' documentation manual. + # Initialize chapter information (e.g., title). + local MANUAL_CHAPTER_TITLE='' + + # Retrive manual's information from standard input. + cli_printMessage "`gettext "Enter chapter's title"`" --as-request-line + read MANUAL_CHAPTER_TITLE + + # Print action message. + cli_printMessage "-" --as-separator-line + cli_printMessage "`gettext "Creating chapter's files."`" --as-response-line + + # Define list of template files used to build chapter's main + # definition files. local FILE='' - local FILES=$(cli_getFilesList ${MANUAL_TEMPLATE_L10N} \ - --pattern='chapter(-menu|-nodes)?\.texinfo' --mindepth='2') + local FILES=$(cli_getFilesList "${MANUAL_TEMPLATE_L10N}/Chapters" \ + --maxdepth='1' \ + --pattern="chapter(-menu|-nodes)?\.${MANUAL_EXTENSION}") - # Loop through chapter structures and create them. - for FILE in $FILES;do + # Create chapter's directory using subversion. This is the place + # where all chapter-specific files will be stored in. + if [[ ! -d ${MANUAL_CHAPTER_DIR} ]];then + svn mkdir ${MANUAL_CHAPTER_DIR} --quiet + fi - # Redefine chapter directory based on template files. - MANUAL_CHAPTER_NAME=$(basename $(dirname ${FILE})) + # Create chapter's files using template files as reference. + for FILE in $FILES;do # Verify texinfo templates used as based to build the chapter. # Be sure they are inside the working copy of CentOS Artwork # Repository (-w) and under version control (-n), too. cli_checkFiles ${FILE} -wn - # Verify chapter's directory. If it doesn't exist, create it. - if [[ ! -d ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} ]];then - svn mkdir ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} --quiet - fi - # Copy template files into chapter's directory. - svn cp ${FILE} ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} --quiet - - # Remove content from `chapter-nodes.texinfo' instance to - # start with a clean node structure. This file is also used by - # to create new repository documentation entries, but we don't - # need that information right now (when the `Directories' - # chapter structure is created), just an empty copy of the - # file. The node structure of `Directories' chapter is created - # automatically based on repository directory structure. - if [[ $FILE =~ "Directories/chapter-nodes\.texinfo$" ]];then - echo "" > ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} - fi + svn cp ${FILE} ${MANUAL_CHAPTER_DIR} --quiet done + # Expand translation markers inside chapter's main definition + # file. Before expanding chapter information, be sure the slash + # (/) character be scaped. Otherwise, if the slashes aren't scape, + # they will be interpreted as sed's separator and provoke sed to + # fail. + sed -i -r \ + -e 's/ \// \\\//g' \ + -e "s/=CHAPTER_NAME=/${MANUAL_CHAPTER_NAME}/" \ + -e "s/=CHAPTER_TITLE=/${MANUAL_CHAPTER_TITLE}/" \ + ${MANUAL_CHAPTER_DIR}/chapter.${MANUAL_EXTENSION} + + # Remove content from `chapter-nodes.texinfo' file to start with a + # clean node structure. This file is also used to create new + # documentation entries, but we don't need that information right + # now (when the chapter structure is created), just an empty copy + # of the file. The node structure of chapter is created + # automatically based on action value. + echo "" > ${MANUAL_CHAPTER_DIR}/chapter-nodes.${MANUAL_EXTENSION} + + # Print action maessage. + cli_printMessage "`gettext "Updating chapter menu and nodes inside manual structure."`" --as-response-line + + # Update chapter information inside the manual's texinfo + # structure. + ${FLAG_BACKEND}_updateChaptersMenu + ${FLAG_BACKEND}_updateChaptersNodes + } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh b/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh index a8d0d79..44ec380 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh @@ -32,25 +32,29 @@ function texinfo_createStructure { if [[ -d $MANUAL_BASEDIR ]];then return else - cli_printMessage "`gettext "The manual you provided doesn't exist in your working copy."`" --as-banner-line - cli_printMessage "`gettext "Do you want to create this manual now?"`" --as-yesornorequest-line + cli_printMessage "-" --as-separator-line + cli_printMessage "`eval_gettext "The following documentation manual will be created:"`" + cli_printMessage "${MANUAL_BASEFILE}.texinfo" --as-response-line + cli_printMessage "`gettext "Do you want to continue?"`" --as-yesornorequest-line fi - # Print separator line. - cli_printMessage "-" --as-separator-line + # Initialize first time created variable. Through this variable it + # is possible to know when the manual has been created for first + # time or not. This variable is used to determine whether to + # relize subversion actions or not against the whole manual + # directory structure. + local MANUAL_FIRSTTIME_CREATED='false' # Initialize manual's information (e.g., title, subtitle, abstract). local MANUAL_TITLE='' local MANUAL_SUBTITLE='' local MANUAL_ABSTRACT='' - # Create manual's top-level directory. This is the place where all - # texinfo documentation manuals is stored in. + # Create manual's top-level directory using subversion. This is + # the place where all texinfo documentation manuals is stored in. if [[ ! -d ${MANUAL_TLDIR} ]];then - - # Use subversion to create the top-level directory. svn mkdir ${MANUAL_TLDIR} --quiet - + MANUAL_FIRSTTIME_CREATED='true' fi # Create manual's base directory. This is the place where @@ -58,21 +62,21 @@ function texinfo_createStructure { svn mkdir ${MANUAL_BASEDIR} --quiet # Retrive manual's information from standard input. - cli_printMessage "`gettext "Enter manual's title"`" --as-request-line + cli_printMessage "`gettext "Manual Title"`" --as-request-line read MANUAL_TITLE - cli_printMessage "`gettext "Enter manual's subtitle"`" --as-request-line + cli_printMessage "`gettext "Manual Subtitle"`" --as-request-line read MANUAL_SUBTITLE - cli_printMessage "`gettext "Enter manual's abstract"`" --as-request-line + cli_printMessage "`gettext "Manual Abstract"`" --as-request-line read MANUAL_ABSTRACT # Print action message. cli_printMessage "-" --as-separator-line - cli_printMessage "`gettext "Creating manual's structure in texinfo format."`" + cli_printMessage "`gettext "Creating manual structure in texinfo format."`" --as-response-line # Verify manual's information. The title information must be # non-empty value. if [[ $MANUAL_TITLE == '' ]];then - cli_printMessage "`gettext "The manual's title cannot be empty."`" --as-error-line + cli_printMessage "`gettext "The manual title cannot be empty."`" --as-error-line fi # Define file names required to build the manual. @@ -97,10 +101,10 @@ function texinfo_createStructure { | sed -r "s!manual!${MANUAL_NAME}!") # Copy using subversion to register this action. - svn cp ${FILE} $DST --quiet + svn cp ${FILE} ${DST} --quiet # Expand common translation markers inside target file. - cli_replaceTMarkers $DST + cli_replaceTMarkers ${DST} # Expand specific translation markers inside target file. sed -r -i -e "s!=MANUAL_NAME=!${MANUAL_NAME}!g" \ @@ -111,21 +115,14 @@ function texinfo_createStructure { fi done - # Update manual chapter related files. - ${MANUAL_BACKEND}_createChapters - - # Update manual chapter related menu. - ${MANUAL_BACKEND}_updateChaptersMenu - - # Update manual chapter related nodes (based on chapter related - # menu). - ${MANUAL_BACKEND}_updateChaptersNodes + # Initialize chapter structure inside the manual. + ${FLAG_BACKEND}_createStructureChapters # 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. - if [[ ! -d ${MANUAL_TLDIR} ]];then + if [[ ${MANUAL_FIRSTTIME_CREATED} == 'true' ]];then cli_commitRepoChanges ${MANUAL_TLDIR} fi diff --git a/Scripts/Functions/Help/Texinfo/texinfo_createStructureChapters.sh b/Scripts/Functions/Help/Texinfo/texinfo_createStructureChapters.sh index c11e686..4ee45ec 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_createStructureChapters.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_createStructureChapters.sh @@ -26,21 +26,23 @@ function texinfo_createStructureChapters { + local MANUAL_CHAPTER_DIR='' + # Define list of chapter templates files used to build the - # documentation manual. Do not include the `Directories' directory + # documentation manual. Do not include the `Chapters' directory # here. It is used to build chapters based on value passed though # `--chapter' option passed in the command-line. local FILE='' local FILES=$(cli_getFilesList ${MANUAL_TEMPLATE_L10N} \ --pattern='chapter(-menu|-nodes)?\.texinfo' --mindepth='2' \ - | grep -v '/Directories/') + | grep -v '/Chapters/') # Loop through chapter structures and create them inside the # manual. for FILE in $FILES;do - # Redefine chapter directory based on template files. - MANUAL_CHAPTER_NAME=$(basename $(dirname ${FILE})) + # Redefine manual's chapter directory based on template files. + MANUAL_CHAPTER_DIR=${MANUAL_BASEDIR}/$(basename $(dirname ${FILE})) # Verify texinfo templates used as based to build the chapter. # Be sure they are inside the working copy of CentOS Artwork @@ -48,12 +50,12 @@ function texinfo_createStructureChapters { cli_checkFiles ${FILE} -wn # Verify chapter's directory. If it doesn't exist, create it. - if [[ ! -d ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} ]];then - svn mkdir ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} --quiet + if [[ ! -d ${MANUAL_CHAPTER_DIR} ]];then + svn mkdir ${MANUAL_CHAPTER_DIR} --quiet fi # Copy template files into chapter's directory. - svn cp ${FILE} ${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} --quiet + svn cp ${FILE} ${MANUAL_CHAPTER_DIR} --quiet done diff --git a/Scripts/Functions/Help/Texinfo/texinfo_deleteCrossReferences.sh b/Scripts/Functions/Help/Texinfo/texinfo_deleteCrossReferences.sh index ed97226..ba81431 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_deleteCrossReferences.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_deleteCrossReferences.sh @@ -42,7 +42,7 @@ function texinfo_deleteCrossReferences { fi # Build the node string using entry location. - local NODE=$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY") + local NODE=$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY") # Define regular expression patterns for texinfo cross reference # commands. diff --git a/Scripts/Functions/Help/Texinfo/texinfo_deleteEntry.sh b/Scripts/Functions/Help/Texinfo/texinfo_deleteEntry.sh index 4cf987c..53e11a2 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_deleteEntry.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_deleteEntry.sh @@ -31,7 +31,7 @@ function texinfo_deleteEntry { # Define list of entries to remove using the entry specified in # the command line. - local MANUAL_ENTRIES=$(${MANUAL_BACKEND}_getEntry "$@") + local MANUAL_ENTRIES=$(${FLAG_BACKEND}_getEntry "$@") # Print separator line. cli_printMessage '-' --as-separator-line @@ -125,12 +125,12 @@ function texinfo_deleteEntry { # Update menu and node definitions from manual sections to # reflect the changes. - ${MANUAL_BACKEND}_updateMenu "remove-entry" - ${MANUAL_BACKEND}_updateNodes + ${FLAG_BACKEND}_updateMenu "remove-entry" + ${FLAG_BACKEND}_updateNodes # Update cross reference definitions from manual to reflect # the changes. - ${MANUAL_BACKEND}_deleteCrossReferences $MANUAL_ENTRY + ${FLAG_BACKEND}_deleteCrossReferences $MANUAL_ENTRY done diff --git a/Scripts/Functions/Help/Texinfo/texinfo_editEntry.sh b/Scripts/Functions/Help/Texinfo/texinfo_editEntry.sh index 75ebb50..2f5c01a 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_editEntry.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_editEntry.sh @@ -31,16 +31,12 @@ function texinfo_editEntry { # Verify section definition inside chapters. if [[ ! -f $MANUAL_ENTRY ]];then - # Verify the parent directory of documentation entry. If the - # parent directory of the current documentation entry doesn't - # exist, create it and be sure it is added to version control. - # Also, verify that the parent directory of the documentation - # entry can be created. Otherwise, stop script execution with - # an error for the user to be aware of it. - if [[ ! -d $(dirname $(dirname $MANUAL_ENTRY)) ]];then - cli_printMessage "`gettext "The documentation entry provided hasn't a parent directory."`" --as-error-line - elif [[ ! -d $(dirname $MANUAL_ENTRY) ]];then - svn mkdir $(dirname ${MANUAL_ENTRY}) --quiet + # Verify chapter related to documentation entry. Inside + # manuals, all documentation entries are stored directly under + # its chapter directory. There is no more levels deep so it is + # possible to perform a direct chapter verification here. + if [[ ! -a $(dirname $MANUAL_ENTRY)/chapter.${MANUAL_EXTENSION} ]];then + ${FLAG_BACKEND}_createChapter fi # Print confirmation question. @@ -48,20 +44,9 @@ function texinfo_editEntry { cli_printMessage "$MANUAL_ENTRY" --as-response-line cli_printMessage "`gettext "Do you want to continue?"`" --as-yesornorequest-line - # Update chapter section related menu. - ${MANUAL_BACKEND}_updateMenu - - # Update chapter section related nodes (based on chapter - # section related menu). - ${MANUAL_BACKEND}_updateNodes - - # Update old missing cross references. If for some reason a - # documentation entry is removed by mistake, and that mistake - # is fixing by adding the removed documentation entry back - # into the repository, rebuild the missing cross reference - # message to use the correct link to the documentation - # section. - ${MANUAL_BACKEND}_restoreCrossReferences $MANUAL_ENTRY + # Update section menu, nodes and cross references based on + # changes in order for manual structure to remain cosistent. + ${FLAG_BACKEND}_updateStructureSection "$MANUAL_ENTRY" else diff --git a/Scripts/Functions/Help/Texinfo/texinfo_getEntry.sh b/Scripts/Functions/Help/Texinfo/texinfo_getEntry.sh index bd8bcdc..d4d813f 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_getEntry.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_getEntry.sh @@ -1,9 +1,7 @@ #!/bin/bash # # texinfo_getEntry.sh -- This function builds a documentation entry -# based on a location specified. Location specification can be both -# action value (ACTIONVAL) variable or a value passed as first -# positional parameter. +# based on location specified as first positional parameter. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -27,48 +25,19 @@ function texinfo_getEntry { - # Define variables as local to avoid conflicts outside. local MANUAL_ENTRY='' - local LOCATION='' - local LOCATIONS='' + local MANUAL_SECTION_NAME='' + local MANUAL_SECTION_NAMES="$@" - # Redefine locations in order to make this function reusable not - # just for action value variable but whatever value passed as - # first possitional argument. - if [[ "$@" != '' ]];then - LOCATIONS="$@" - else - LOCATIONS="$ACTIONVAL" - fi + # Loop through list of section names. + for MANUAL_SECTION_NAME in $MANUAL_SECTION_NAMES;do - for LOCATION in $LOCATIONS;do - - # Sanitate action value to use absolute paths. - LOCATION=$(cli_checkRepoDirSource $LOCATION) - - # Define relative path of entry, from trunk directory on. - MANUAL_ENTRY=$(echo $LOCATION | sed -r "s!^${HOME}/artwork/!!") - - # Verify the entry relative path to find out which - # documentation manual we are acting on. As convenction, - # whatever documentation entry you provide outside - # trunk/Manuals/ directory structure is considered as you are - # documenting the repository directory structure. Otherwise, - # if an entry inside trunk/Manuals/ is provided, the directory - # structure provided is used as default documentation manual. - if [[ ${MANUAL_ENTRY} =~ "\.${MANUAL_EXTENSION}$" ]];then - MANUAL_ENTRY=$(echo ${MANUAL_ENTRY} | sed "s!${MANUAL_BASEDIR}!!") - else - MANUAL_ENTRY=$(dirname ${MANUAL_CHAPTER_NAME}/${MANUAL_ENTRY})/$(basename $LOCATION).${MANUAL_EXTENSION} - fi - - # Re-define entry to set absolute path to manuals base - # directory structure. - MANUAL_ENTRY=${MANUAL_BASEDIR}/${MANUAL_ENTRY} + # Define absolute path to documentation entry. + MANUAL_ENTRY=${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME}/${MANUAL_SECTION_NAME}.${MANUAL_EXTENSION} # Output entry's absolute path. echo ${MANUAL_ENTRY} done - + } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_getNode.sh b/Scripts/Functions/Help/Texinfo/texinfo_getNode.sh index 03bb857..4c10bcb 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_getNode.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_getNode.sh @@ -35,9 +35,10 @@ function texinfo_getNode { # Define node from documentation entry. local NODE=$(echo "$MANUAL_ENTRY" | sed -r \ - -e "s!^${MANUAL_BASEDIR}!!" \ + -e "s!^${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME}!!" \ -e "s/(chapter-intro\.${MANUAL_EXTENSION}|\.${MANUAL_EXTENSION})$//" \ - -e 's!/! !g' \ + -e 's!(/|-)! !g' \ + -e 's! ([[:alpha:]])! \u\1!g' \ -e 's!^[[:space:]]+!!') echo "$NODE" diff --git a/Scripts/Functions/Help/Texinfo/texinfo_renameCrossReferences.sh b/Scripts/Functions/Help/Texinfo/texinfo_renameCrossReferences.sh index f7c244f..740d167 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_renameCrossReferences.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_renameCrossReferences.sh @@ -26,14 +26,14 @@ function texinfo_renameCrossReferences { - local MANUAL_ENTRY_SRC=$(${MANUAL_BACKEND}_getEntry "$1") - local MANUAL_ENTRY_DST=$(${MANUAL_BACKEND}_getEntry "$2") + local MANUAL_ENTRY_SRC=$(${FLAG_BACKEND}_getEntry "$1") + local MANUAL_ENTRY_DST=$(${FLAG_BACKEND}_getEntry "$2") # Define node pattern for source documenation entry. - local NODE_SRC=$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY_SRC") + local NODE_SRC=$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY_SRC") # Define node replacement for target documentation entry. - local NODE_DST=$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY_DST") + local NODE_DST=$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY_DST") # Define list of entries to process. local MANUAL_ENTRIES=$(cli_getFilesList ${MANUAL_BASEDIR} \ @@ -67,6 +67,6 @@ function texinfo_renameCrossReferences { # source to target documentation entry, but they are still # commented. So, uncomment them restoring target documentation # entries. - ${MANUAL_BACKEND}_restoreCrossReferences "${MANUAL_ENTRY_DST}" + ${FLAG_BACKEND}_restoreCrossReferences "${MANUAL_ENTRY_DST}" } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_renameEntry.sh b/Scripts/Functions/Help/Texinfo/texinfo_renameEntry.sh index 022ca76..09fff4a 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_renameEntry.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_renameEntry.sh @@ -26,17 +26,17 @@ function texinfo_renameEntry { # Copy source documentation entry. - ${MANUAL_BACKEND}_copyEntry "$1" "$2" + ${FLAG_BACKEND}_copyEntry "$1" "$2" # Delete source documentation entry. The source documentation # entry has been copied already, so to create the rename effect # delete it from repository filesystem. - ${MANUAL_BACKEND}_deleteEntry "$1" + ${FLAG_BACKEND}_deleteEntry "$1" # At this point, source documentation entry has been removed and # all menu, nodes and cross-references have been commented. So, # replace commented menu, nodes and cross-reference information # from source to target documentation entry. - ${MANUAL_BACKEND}_renameCrossReferences "$1" "$2" + ${FLAG_BACKEND}_renameCrossReferences "$1" "$2" } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_restoreCrossReferences.sh b/Scripts/Functions/Help/Texinfo/texinfo_restoreCrossReferences.sh index 8dfff4f..d9992e9 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_restoreCrossReferences.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_restoreCrossReferences.sh @@ -46,7 +46,7 @@ function texinfo_restoreCrossReferences { fi # Build the node string using entry location. - local NODE=$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY") + local NODE=$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY") # Define regular expression patterns to match removed message # format produced by message_removeCrossReferences function. diff --git a/Scripts/Functions/Help/Texinfo/texinfo_searchIndex.sh b/Scripts/Functions/Help/Texinfo/texinfo_searchIndex.sh index 18fdf23..3d96c7a 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_searchIndex.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_searchIndex.sh @@ -26,7 +26,7 @@ function texinfo_searchIndex { # Rebuild output files to propagate recent changes. - ${MANUAL_BACKEND}_updateOutputFiles + ${FLAG_BACKEND}_updateOutputFiles # Print separator line. cli_printMessage '-' --as-separator-line diff --git a/Scripts/Functions/Help/Texinfo/texinfo_searchNode.sh b/Scripts/Functions/Help/Texinfo/texinfo_searchNode.sh index fffb7d5..1651783 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_searchNode.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_searchNode.sh @@ -28,26 +28,17 @@ function texinfo_searchNode { # Print separator line. cli_printMessage '-' --as-separator-line - # Define list of documentation entries. - local MANUAL_ENTRY='' - local MANUAL_ENTRIES=$(${MANUAL_BACKEND}_getEntry "$@") - - # Loop through manual entries and read related node. - for MANUAL_ENTRY in $MANUAL_ENTRIES;do - - # Print action message. - cli_printMessage "${MANUAL_BASEFILE}.info.bz2" --as-reading-line - - # Check documentation entry inside documentation structure. If - # the documentation entry exits use the info reader to open - # the info file at the specified node for reading it on the - # terminal. Otherwise, ask the user to create it. - if [[ -f "$MANUAL_ENTRY" ]];then - /usr/bin/info --node="$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY")" --file=${MANUAL_BASEFILE}.info.bz2 - else - ${MANUAL_BACKEND}_editEntry - fi - - done + # Print action message. + cli_printMessage "${MANUAL_BASEFILE}.info.bz2" --as-reading-line + + # Check documentation entry inside documentation structure. If the + # documentation entry exits use the info reader to open the info + # file at the specified node for reading it on the terminal. + # Otherwise, ask the user to create it. + if [[ -f "$MANUAL_ENTRY" ]];then + /usr/bin/info --node="$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY")" --file=${MANUAL_BASEFILE}.info.bz2 + else + ${FLAG_BACKEND}_editEntry + fi } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersMenu.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersMenu.sh index 0751e8b..ed7b81c 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersMenu.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersMenu.sh @@ -34,7 +34,8 @@ function texinfo_updateChaptersMenu { # even no other node exist. if [[ -f ${MANUAL_BASEFILE}-menu.${MANUAL_EXTENSION} ]];then MENUCHAPTERS=$(cat ${MANUAL_BASEFILE}-menu.${MANUAL_EXTENSION} \ - | egrep -v "^@(end )?menu$" | egrep -v '^\* Index::$') + | egrep -v "^@(end )?menu$" \ + | egrep -v '^\* (Licenses|Index)::$') fi # Re-defined menu of chapters based on action. @@ -47,8 +48,11 @@ function texinfo_updateChaptersMenu { ;; 'update-entry' | * ) - # Update chapter menu using texinfo format. - MENUCHAPTERS="${MENUCHAPTERS} + # Update chapter menu using texinfo format. Be sure the + # chapter node itself is not included here, that would + # duplicate it inside the menu definition file which + # end up being a definition error. + MENUCHAPTERS="$(echo "${MENUCHAPTERS}" | egrep -v "\* ${MANUAL_CHAPTER_NAME}::[[:print:]]*$") * ${MANUAL_CHAPTER_NAME}::" ;; esac @@ -60,16 +64,19 @@ function texinfo_updateChaptersMenu { | egrep -v '^[[:space:]]*$') # Organize menu of chapters alphabetically and verify that no - # duplicated line be included on the list. - MENUCHAPTERS=$(echo "${MENUCHAPTERS}" | sort | uniq) + # duplicated line be included on the list. Notice that organizing + # menu this way supresses the idea of putting the last chapter + # created at the end of the list. + #MENUCHAPTERS=$(echo "${MENUCHAPTERS}" | sort | uniq) # Give format to final menu output. MENUCHAPTERS="@menu ${MENUCHAPTERS} + * Licenses:: * Index:: @end menu" - # Strip opening space/tabs from final menu of chapters. + # Remove opening space/tabs from menu's final definition. MENUCHAPTERS=$(echo "${MENUCHAPTERS}" | sed -r 's!^[[:space:]]+!!' \ | egrep -v '^[[:space:]]*$') diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersNodes.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersNodes.sh index 8afff29..90f434b 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersNodes.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateChaptersNodes.sh @@ -25,15 +25,16 @@ function texinfo_updateChaptersNodes { - # Build list "nodes of chapters" based on menu of chapters. + # Build chapter nodes using entries from chapter menu as + # reference. Don't include `Licenses' or `Index' chapters here. + # These chapters are part of our manual's main defintion file and + # shouldn't be handled as regular chapters. local CHAPTERNODES=$(cat ${MANUAL_BASEFILE}-menu.${MANUAL_EXTENSION} \ - | egrep -v '^@(end )?menu$' | egrep -v '^\* Index::$'\ + | egrep -v '^@(end )?menu$' | egrep -v '^\* (Licenses|Index)::$'\ | sed -r 's!^\* !!' | sed -r 's!::[[:print:]]*$!!g' \ - | sed -r 's! !_!g' | sort | uniq ) + | sed -r 's! !_!g') - # Build list of texinfo inclusions to load chapters' nodes. Don't - # include `Index' chapter here, it has been already included in - # the `repository.texinfo' file. + # Build list of inclusions from chapter nodes. local FILENODE=$(\ for CHAPTERNODE in ${CHAPTERNODES};do INCL=$(echo ${CHAPTERNODE} \ diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateMenu.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateMenu.sh index 9c19336..c2add7f 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateMenu.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateMenu.sh @@ -1,13 +1,12 @@ #!/bin/bash # -# texinfo_updateMenu.sh -- This function updates menu lines inside -# texinfo chapters. If this function is called with the -# 'remove-entry' string as first argument, then the menu line related -# to the entry being processed is removed. If this function is called -# with the 'update-entry' string as first argument, then the menu line -# related to the entry being processed is added to the menu. If no -# argument is passed to this function, the 'update-entry' action is -# assumed. +# texinfo_updateMenu.sh -- This function updates chapter's menu +# definition file. If this function is called with the 'remove-entry' +# string as first argument, the menu line related to the entry being +# processed is removed. Otherwise, if this function is called with the +# 'update-entry' string as first argument, the menu line related to +# the entry being processed is added to menu's bottom. If no argument +# is passed to this function, the 'update-entry' action is assumed. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -31,45 +30,46 @@ function texinfo_updateMenu { - # Specify which action to do inside chapter's menu. + # Specify which action to do with documentation entry inside the + # chapter menu. local ACTION="$1" - # Build the menu node related to the entry being processed - # currently. - local MENUNODE=$(${MANUAL_BACKEND}_getNode "$MANUAL_ENTRY") + # Build node information used inside chapter menu. + local MENUNODE=$(${FLAG_BACKEND}_getNode "$MANUAL_ENTRY") - # Give format to menu line using texinfo style. - local MENULINE="* ${MENUNODE}::" + # Define menu entry using texinfo style and node information as + # reference. + local MENULINE="* ${MANUAL_CHAPTER_NAME} ${MENUNODE}::" - # Define chapter's menu. Remove `@menu', `@end menu' and empty - # lines from output. + # Retrive list of menu entries from chapter menu and exclude + # `@menu', `@end menu' and empty lines from output. local MENU=$(cat $MANUAL_CHAPTER_DIR/chapter-menu.${MANUAL_EXTENSION} \ | egrep -v '^[[:space:]]*$' | egrep -v '^@(end )?menu') - # Re-defined chapter's menu based on action. + # Re-defined chapter menu entries based on action provided to this + # function as first positional parameter. case $ACTION in 'remove-entry' ) - # Remove menu line from chapter's menu. + # Remove menu entry from chapter menu. MENU=$(echo "$MENU" | egrep -v "$MENULINE") ;; 'update-entry' | * ) - # Add menu line to chapter's menu. This is the default - # behaivour if no argument is passed to texinfo_updateMenu - # function. + # Add menu entry to chapter menu list as last entry. MENU="$MENU $MENULINE" ;; + esac - # Organize menu alphabetically, remove empty and duplicated lines. - # At this point, empty line may occur the first time the menu is - # created, don't let them to scape. - MENU=$(echo "$MENU" | egrep -v '^[[:space:]]*$' | sort | uniq ) + # Remove empty lines from chapter menu entries. Don't order + # alphabetically. That would suppress the idea of putting the + # last entry added as last entry in the chapter menu entries. + MENU=$(echo "$MENU" | egrep -v '^[[:space:]]*$') - # Rebuild chapter's menu structure adding '@menu' and '@end menu' - # lines back in menu. + # Rebuild list of chapter menu entries including '@menu' and '@end + # menu' lines back into chapter menu. MENU="@menu $MENU @end menu" @@ -77,7 +77,8 @@ function texinfo_updateMenu { # Remove opening spaces/tabs from final menu structure. MENU=$(echo "$MENU" | sed -r 's!^[[:space:]]+!!g') - # Dump final menu structure back into chapter's menu file. + # Dump chapter menu entries back into chapter's menu definition + # file. echo "$MENU" > $MANUAL_CHAPTER_DIR/chapter-menu.${MANUAL_EXTENSION} } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh index d9582e2..bf631ec 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh @@ -25,18 +25,19 @@ function texinfo_updateNodes { - # Retrive nodes' entries from chapter-menu.texinfo file. + # Build list of chapter nodes using entries from chapter menu as + # reference. local NODES=$(cat $MANUAL_CHAPTER_DIR/chapter-menu.${MANUAL_EXTENSION} \ | sed -r 's!^\* !!' | sed -r 's!:{1,2}.*$!!g' \ - | egrep -v '^@(end )?menu$' | sed -r 's! !:!g' | sort | uniq) + | egrep -v '^@(end )?menu$' | sed -r 's! !:!g') - # Re-build node structure based on menu information. + # Build chapter nodes based on chapter menu. for NODE in $NODES;do NODE=$(echo "${NODE}" | sed -r 's!:! !g') - SECT=$(echo "${NODE}" | cut -d' ' -f2- | sed -r 's! !/!g') - INCL=$(echo "${NODE}" | sed -r 's! !/!g').${MANUAL_EXTENSION} - CIND=$(echo "${NODE}") + INCL=$(echo "${NODE}" | sed -r 's! !/!' | sed -r 's! !-!g' | sed -r 's!/(.+)!/\L\1!').${MANUAL_EXTENSION} + SECT=$(echo "${NODE}" | cut -d' ' -f2- ) + CIND=$(echo "${SECT}" | sed -r 's!^([[:alpha:]]+) (.+)!\u\1 \L\2!') # Create texinfo section file using templates, only if the # section file doesn't exist and hasn't been marked for @@ -46,11 +47,11 @@ function texinfo_updateNodes { if [[ ! -f ${MANUAL_BASEDIR}/$INCL ]] \ && [[ $(cli_getRepoStatus ${MANUAL_BASEDIR}/$INCL) != 'D' ]];then - # Define absolute path to section templates assignment - # file. This is the file that hold the relation between - # section template files and repository paths when - # documentation entries are created. - local CONFFILE="${MANUAL_TEMPLATE_L10N}/manual.conf" + # Define absolute path to template assignment file. This + # is the file that controls the way texinfo template files + # are applied to documentation entries once they have been + # created. + local CONFFILE="${MANUAL_TEMPLATE}/manual.conf" # Verify existence of configuration file. cli_checkFiles $CONFFILE @@ -80,11 +81,11 @@ function texinfo_updateNodes { for CONFLINE in $CONFLINES;do CONFLHS=$(echo $CONFLINE \ - | gawk 'BEGIN{FS = "="}; { print $1 }' \ + | gawk 'BEGIN{FS="="}; { print $1 }' \ | sed -r 's![[:space:]]*!!g') CONFRHS=$(echo $CONFLINE \ - | gawk 'BEGIN{FS = "="}; { print $2 }' \ + | gawk 'BEGIN{FS="="}; { print $2 }' \ | sed -r 's![[:space:]]*!!g' | sed -r 's!^"(.+)"$!\1!') if [[ ${MANUAL_BASEDIR}/${INCL} =~ $CONFRHS ]];then @@ -103,29 +104,37 @@ function texinfo_updateNodes { # reference. svn cp ${TEMPLATE} ${MANUAL_BASEDIR}/$INCL --quiet - # Expand common translation markers in documentation entry. - cli_replaceTMarkers "${MANUAL_BASEDIR}/$INCL" - - # Expand `Goals' subsection translation markers in - # documentation entry. - sed -i -r "s!=SECT=!${SECT}!g" "${MANUAL_BASEDIR}/$INCL" - - # Expand `See also' subsection translation markers in - # documentation entry. - ${MANUAL_BACKEND}_makeSeeAlso "${MANUAL_BASEDIR}/$INCL" "$NODE" - fi + # Expand common translation markers in documentation entry. + cli_replaceTMarkers "${MANUAL_BASEDIR}/$INCL" + + # Replace node, section and concept index definitions already + # defined with node, section and concept index translation + # markers. Otherwise, incorrect sectioning may happen. + sed -i -r \ + -e '/@node/c@node =NODE=' \ + -e '/@section/c@section =SECT=' \ + -e '/@cindex/c@cindex =CIND=' \ + "${MANUAL_BASEDIR}/$INCL" + + # Expand noce, section and concept index translation + # markers in documentation entry. + sed -i -r \ + -e "s!=NODE=!${NODE}!g" \ + -e "s!=SECT=!${SECT}!g" \ + -e "s!=CIND=!${CIND}!g" \ + "${MANUAL_BASEDIR}/$INCL" + # Verify existence of chapter-nodes template files. If no # chapter-nodes template is found, stop script execution with # an error message. We cannot continue without it. - cli_checkFiles ${MANUAL_TEMPLATE_L10N}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} + cli_checkFiles ${MANUAL_TEMPLATE_L10N}/Chapters/chapter-nodes.${MANUAL_EXTENSION} # Output node information chapter-nodes template file using # the current texinfo menu information. - cat ${MANUAL_TEMPLATE_L10N}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} \ - | sed -r -e "s!=NODE=!${NODE}!g" -e "s!=SECT=!${SECT}!g" \ - -e "s!=CIND=!${CIND}!g" -e "s!=INCL=!${INCL}!g" + cat ${MANUAL_TEMPLATE_L10N}/Chapters/chapter-nodes.${MANUAL_EXTENSION} \ + | sed -r "s!=INCL=!${INCL}!g" # Dump node definitions into document structure. done > $MANUAL_CHAPTER_DIR/chapter-nodes.${MANUAL_EXTENSION} diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFiles.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFiles.sh index b8c71a1..fe06a80 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFiles.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFiles.sh @@ -33,12 +33,12 @@ function texinfo_updateOutputFiles { # paths incorrectly. pushd ${HOME}/artwork > /dev/null - ${MANUAL_BACKEND}_updateOutputFileInfo - ${MANUAL_BACKEND}_updateOutputFileXhtml - ${MANUAL_BACKEND}_updateOutputFileXml - ${MANUAL_BACKEND}_updateOutputFileDocbook - ${MANUAL_BACKEND}_updateOutputFilePdf - ${MANUAL_BACKEND}_updateOutputFilePlaintext + ${FLAG_BACKEND}_updateOutputFileInfo + ${FLAG_BACKEND}_updateOutputFileXhtml + ${FLAG_BACKEND}_updateOutputFileXml + ${FLAG_BACKEND}_updateOutputFileDocbook + ${FLAG_BACKEND}_updateOutputFilePdf + ${FLAG_BACKEND}_updateOutputFilePlaintext # Remove the working copy root directory from directory stack. popd > /dev/null diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateStructureSection.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateStructureSection.sh new file mode 100755 index 0000000..e2c853e --- /dev/null +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateStructureSection.sh @@ -0,0 +1,88 @@ +#!/bin/bash +# +# texinfo_updateStructureSection.sh -- This function looks for all +# documentation entry (section) files inside manual's base directory and +# updates menu, nodes and cross references for them. +# +# Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG +# +# 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 texinfo_updateStructureSection { + + local PATTERN='' + local MANUAL_ENTRY='' + local MANUAL_ENTRIES='' + + # Define find's regular expression pattern. + if [[ $1 != '' ]];then + PATTERN="$1" + else + PATTERN=".+\.${MANUAL_EXTENSION}" + fi + + # Define list of target documentation entries using find's regular + # expression pattern as reference. This is required in order to + # process non-existent documentation entries (e.g., when they are + # created for first time). Otherwise, the list of documentation + # entries will be empty an no entry would be processed. + if [[ ${PATTERN} =~ '^/.+\.texinfo$' ]];then + + # When the pattern value is an absolute path to a + # documentation entry, use that value as only documentation + # entry in the list. + MANUAL_ENTRIES=${PATTERN} + + else + + # When the pattern value is a regular expression, use + # cli_getFilesList to build the list of documentation entries + # using it. Don't include manual or chapter definition files + # in this list, it would create documentation entries for them + # and that shouldn't happen. + MANUAL_ENTRIES=$(cli_getFilesList $(dirname ${MANUAL_BASEDIR}) \ + --pattern="$PATTERN" | egrep -v "/(${MANUAL_NAME}|chapter)") + fi + + # Print action message. + cli_printMessage "`gettext "Updating section menus, nodes and cross references."`" --as-response-line + + # Loop through target documentation entries in order to update + # the documentation structure (e.g., It is not enough with copying + # documentation entry files, it is also needed to update menu, + # nodes and related cross-references). + for MANUAL_ENTRY in ${MANUAL_ENTRIES};do + + # Update menu and node definitions for sections inside manual + # in order to reflect the changes. + ${FLAG_BACKEND}_updateMenu + ${FLAG_BACKEND}_updateNodes + + # Resotre cross reference definitions inside manual structure. + # If a documentation entry has been removed by mistake and + # that mistake is later fixed by adding the removed + # documentation entry back into the manual structure, it is + # necessary to rebuild the missing cross reference information + # inside the manual structure in order to reactivate the + # removed cross refereces, as well. + ${FLAG_BACKEND}_restoreCrossReferences $MANUAL_ENTRY + + done + +} diff --git a/Scripts/Functions/Help/help.sh b/Scripts/Functions/Help/help.sh index 3a69c94..f793835 100755 --- a/Scripts/Functions/Help/help.sh +++ b/Scripts/Functions/Help/help.sh @@ -26,47 +26,95 @@ function help { + # Initialize action name with an empty value. local ACTIONNAM='' - local ACTIONVAL='' # Initialize search option (`--search'). This option is used to # look for documentation inside documentation backends. local FLAG_SEARCH="" - # Initialize manual's ID. By default, The CentOS Artwork - # Repository User's Guide is used. This value can be changed - # using the `--manual' option from the command-line. - local FLAG_MANUAL="TCAR-UG" + # Initialize the backend flag (`--backend'). This option sets the + # documentation backed used to perform documentation actions. + local FLAG_BACKEND='texinfo' # Initialize manual's language. local MANUAL_L10N=$(cli_getCurrentLocale) - # Initialize manual's backend. By default, texinfo is used as - # documentation backend. This value can be changed using the - # `--backend' option from the command-line. - local MANUAL_BACKEND='texinfo' + # Initialize arrays related to documentation entries. Arrays + # defined here contain all the information needed to process + # documentation entries written in texinfo format. + local -a MANUAL_SLFN + local -a MANUAL_DIRN + local -a MANUAL_CHAN + local -a MANUAL_SECN + + # Initialize counter of non-option arguments. + local MANUAL_DOCENTRY_COUNT=0 + local MANUAL_DOCENTRY_ID=0 # Interpret option arguments passed through the command-line. ${FUNCNAM}_getOptions - # Initialize manual's backend directory. This is the place where - # the backend specific documentation structure is stored in. - MANUAL_TLDIR="${HOME}/artwork/branches/Manuals/$(cli_getRepoName \ - $MANUAL_BACKEND -d)/${FLAG_MANUAL}" - - # Initialize manual's file name (without extension). - MANUAL_NAME=$(cli_getRepoName "$(basename $FLAG_MANUAL)" -f) + # Redefine arrays related to documentation entries using + # non-option arguments passed through the command-line. At this + # point all options have been removed from ARGUMENTS and + # non-option arguments remain. Evaluate ARGUMENTS to retrive the + # information related documentation entries from there. + ${FUNCNAM}_getEntries - # 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" + # 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_BASEDIR} - # Initialize backend-specific functionalities. + # Initialize backend functionalities. At this point we load all + # functionalities required into the centos-art.sh's execution + # environment and make them available, this way, to perform + # backend-specific documentation tasks. cli_exportFunctions "${FUNCDIR}/${FUNCDIRNAM}/$(cli_getRepoName \ - ${MANUAL_BACKEND} -d)" "${MANUAL_BACKEND}" + ${FLAG_BACKEND} -d)" "${FLAG_BACKEND}" + + # Execute backend-specific documentation tasks for each + # documentation entry specified in the command-line, individually. + # Notice that we've stored all documentation entries passed as + # non-option arguments in array variables in order to process them + # now, one by one. This is particularily useful when we need to + # reach items in the array beyond the current iteration cycle. For + # example, when we perform actions that require source and target + # locations (e.g., copying and renaming): we use the current value + # as source location and the second value in the array as target + # location; both defined from the first iteration cycle. + while [[ $MANUAL_DOCENTRY_ID -lt $MANUAL_DOCENTRY_COUNT ]];do + + # Define name used by manual's main definition file. + MANUAL_NAME=${MANUAL_SLFN[${MANUAL_DOCENTRY_ID}]} + + # Define absolute path to directory holding manual's main + # definition file. + MANUAL_TLDIR="${HOME}/artwork/branches/Manuals/$(cli_getRepoName \ + ${FLAG_BACKEND} -d)/${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]}" + + # Define chapter name. + MANUAL_CHAPTER_NAME=${MANUAL_CHAN[${MANUAL_DOCENTRY_ID}]} + + # Define section name. + MANUAL_SECTION_NAME=${MANUAL_SECN[${MANUAL_DOCENTRY_ID}]} + + # Execute backend-specific documentation tasks. + ${FLAG_BACKEND} + + # Increment documentation entry counter id. + MANUAL_DOCENTRY_ID=$(($MANUAL_DOCENTRY_ID + 1)) + + done + + # Rebuild output files to propagate recent changes. + ${FLAG_BACKEND}_updateOutputFiles - # Execute backend-specific actions. - ${MANUAL_BACKEND} $@ + # 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_BASEDIR} } diff --git a/Scripts/Functions/Help/help_getEntries.sh b/Scripts/Functions/Help/help_getEntries.sh index 27f5feb..3ecba37 100755 --- a/Scripts/Functions/Help/help_getEntries.sh +++ b/Scripts/Functions/Help/help_getEntries.sh @@ -33,37 +33,50 @@ function help_getEntries { # only non-option arguments remain in it. eval set -- "$ARGUMENTS" - # Build manual array to store information required to process - # documentation entries (e.g., manual name, chapter name and - # section name.) At this point all option arguments have been - # removed from positional paramters so we can use the remaining - # non-option arguments as reference to retrive documentation - # entries. Documentation entries passed as non-opiton arguments - # must have the `MANUAL:CHAPTER:SECTION' format in order to be - # processed correctly here. - for DOCENTRY in $@;do + if [[ $@ == '' ]];then - # Manual self name. - MANUAL_SLFN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ - $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $1 }') -f \ - | tr '[:upper:]' '[:lower:]') + # Define default documentation entry. This happen when + # non-option arguments aren't provided to centos-art.sh + # script. Default documentation entry defined here points to + # manual's main definition file, so only the manual's self + # name and manual's directory name need to be defined here. + MANUAL_SLFN[0]='tcar-ug' + MANUAL_DOCENTRY_COUNT=$(($MANUAL_DOCENTRY_COUNT + 1)) - # Manual directory name. - MANUAL_DIRN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ - $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $1 }') -f \ - | tr '[:lower:]' '[:upper:]') + else - # Manual chapter name. - MANUAL_CHAN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ - $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $2 }') -d ) + # Retrive documentation entries passed to centos-art.sh script + # as non-option arguments and store them in array variables in + # order to describe their parts (e.g., manual name, chapter + # name and section name) that way. Documentation entries + # passed as non-opiton arguments must have the + # `MANUAL:CHAPTER:SECTION' format in order to be processed + # correctly here. Empty spaces are not permitted. To separate + # words, use the minus sign (e.g., hello-world) or cammel case + # (e.g., HelloWorld). + for DOCENTRY in $@;do - # Manual section name. - MANUAL_SECN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ - $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $3 }') -f ) + # Manual self name. + MANUAL_SLFN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ + $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $1 }') -f \ + | tr '[:upper:]' '[:lower:]') - # Increment counting of non-option arguments. - MANUAL_DOCENTRY_COUNT=$(($MANUAL_DOCENTRY_COUNT + 1)) + # Manual self directory name. + MANUAL_DIRN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ + $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $1 }') -d ) + + # Manual chapter name. + MANUAL_CHAN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ + $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $2 }') -d ) + + # Manual section name. + MANUAL_SECN[${MANUAL_DOCENTRY_COUNT}]=$(cli_getRepoName \ + $(echo "$DOCENTRY" | gawk 'BEGIN{ FS=":" } { print $3 }') -f ) + + # Increment counting of non-option arguments. + MANUAL_DOCENTRY_COUNT=$(($MANUAL_DOCENTRY_COUNT + 1)) - done + done + fi } diff --git a/Scripts/Functions/Help/help_getOptions.sh b/Scripts/Functions/Help/help_getOptions.sh index 50e234f..a67ecc8 100755 --- a/Scripts/Functions/Help/help_getOptions.sh +++ b/Scripts/Functions/Help/help_getOptions.sh @@ -1,7 +1,8 @@ #!/bin/bash # -# help_getOptions.sh -- This function interpretes arguments passed to -# `help' functionality and calls actions accordingly. +# help_getOptions.sh -- This function interpretes option arguments +# passed to `help' functionality through the command-line and defines +# action names accordingly. # # Copyright (C) 2009, 2010, 2011 The CentOS Artwork SIG # @@ -29,7 +30,7 @@ function help_getOptions { local ARGSS="" # Define long options we want to support. - local ARGSL="quiet,answer-yes,dont-commit-changes,backend:,read,search:,edit,update,copy,delete,rename,manual:" + local ARGSL="quiet,answer-yes,dont-commit-changes,backend:,read,search:,edit,update,copy,delete,rename" # Parse arguments using getopt(1) command parser. cli_parseArguments @@ -59,12 +60,11 @@ function help_getOptions { ;; --backend ) - MANUAL_BACKEND="$(cli_getRepoName "$2" -f)" - shift 2 - ;; - - --manual ) - FLAG_MANUAL=$(cli_getRepoName "$2" -f | tr '[:lower:]' '[:upper:]') + # CAUTION: Be sure to sanitate this input value + # through cli_getRepoName using just the basename of + # the value provided. Otherwise, functionalities might + # be executed from unexpected places. + FLAG_BACKEND="$(cli_getRepoName "$2" -f)" shift 2 ;; @@ -123,11 +123,4 @@ function help_getOptions { # Redefine ARGUMENTS variable using current positional parameters. cli_parseArgumentsReDef "$@" - # Verify non-option arguments passed to command-line. If there - # isn't any, redefine the ARGUMENTS variable to use the current - # location the functionality was called from. - if [[ $ARGUMENTS == '' ]];then - ARGUMENTS=${PWD} - fi - }