From edaa9db5ef9fbfc6c9705c845320055245712e00 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jul 16 2011 15:59:55 +0000 Subject: Update `texinfo' documentation backend inside `help' functionality: - The ACTIONVAL variable is no longer used. Instead, the MANUAL_SLFN, MANUAL_DIRN, MANUAL_CHAN and MANUAL_SECN array variables are used. These array variables simulate a bidimensional array that increments parallelly on each non-option argument passed to `centos-art.sh' script. Each array entry consists on the following information: 1. The manual name information. This value is stored in the MANUAL_SLFN array. The manual name is always lower case and is used to build the manual's main definition file. 2. The manual directory name. This value is stored in the MANUAL_DIRN array. The manual directory name is always capitalized and is used to store the manual's main definition files as well as auxiliar files (e.g., chapters and sections definitions). 3. The chapter name. This value is stored in the MANUAL_CHAN array. The chapter name is always capitalized and is used to define the chapter directory where all documentation actions will take place on. 4. The section name. This value is stored in the MANUAL_SECN array. The section name is always in lower case and is used to define the section's definition file where documentation actions will take place on. - The `--manual' option is no longer used. Instead, non-option arguments passed to `centos-art.sh' script are used to provide all information required to work with manuals, chapters inside manuals and sections inside chapters. As convenction, when using texinfo documentation backend, non-option arguments must be specified with the `MANUAL:CHAPTER:SECTION' format. To separate words, you can use the minus sign (e.g., `TCAR-UG:Directories:trunk-identity'). - Add `texinfo_copyEntryManual', `texinfo_copyEntryChapter', `texinfo_copyEntrySection' to improve the way manuals, chapters and sections, respectively, are duplicated inside the working copy. Now, you can: - Duplicate sections inside the same chapter. For example, centos-art help --copy MANSRC:CHASRC:SECSRC MANSRC:CHASRC:SECDST - Duplicate sections from one chapter to another different. For example, centos-art help --copy MANSRC:CHASRC:SECSRC MANSRC:CHADST:SECSRC centos-art help --copy MANSRC:CHASRC:SECSRC MANSRC:CHADST:SECDST centos-art help --copy MANSRC:CHASRC:SECSRC MANSRC:CHADST - Duplicate chapters inside a manual. For example, centos-art help --copy MANSRC:CHASRC MANSRC:CHADST - Duplicate manuals inside the working copy. For example, centos-art help --copy MANSRC MANDST - When new documentaion manuals written in texinfo format are created for very first time, they are created using all chapters definitions available inside the documentation template directory with the exception of `Chapters' directory, which is used to store chapter's and section's main definition files. In this commit, only a `Licenses' chapter is inside documentation template directory. This chapter contains the license information refered inside the manual and shouldn't be removed. This chapter is defined as appendix to differentiate it from regular chapters inside the manual. In addition to `Licenses' directory, the `Index' chapter is added too. This chapter is unnumbered. - Add `texinfo_updateStructureSection.sh' file. This function looks for all documentation entry (section) files inside the manual's base directory and updates menu, nodes and cross references for them. - Rename MANUAL_BACKEND variable name to FLAG_BACKEND. --- 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 - }