From 22d0550e2884d15a0677cab143782b3cbb0605fa Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Aug 07 2011 01:56:31 +0000 Subject: Update `help' functionality: - Move some variable definitions from `Help/Texinfo/texinfo.sh' to `Help/help.sh'. - The MANUAL_BACKEND information is no longer retrived from `--backend' option. Instead, the `manual_backend' option inside manual's configuration file is used. When the documentation manual is created for first time, a selection list is prompted with all documentation backends supported in order for the user to select one of them. - Because MANUAL_BACKEND is now retrived from manual's configuration file, MANUAL_BACKEND variable definition was moved into the documentation entry interpretation loop; which, in turn, provokes that all dependent definitions be moved into the loop too. - The `help_updateOutputFiles' invocation was removed from `Help/help.sh' those places inside `Help/Texinfo/texinfo.sh' where it is needed. This invocation movement is required in order to control which backend-specific tasks does perform `help_updateOutputFiles' and which one doesn't. - Don't terminate script execution for functions like `texinfo_searchNodes', `texinfo_searchIndex' and `texinfo_updateOutputFiles' inside `Texinfo/texinfo.sh' file. Such action would prevent us from using those functionalities for more than one documentation entry passed to `centos-art.sh' script command-line. - Update comments. --- diff --git a/Scripts/Functions/Help/Texinfo/texinfo.sh b/Scripts/Functions/Help/Texinfo/texinfo.sh index 2c60f84..b7b9b0c 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo.sh @@ -1,9 +1,9 @@ #!/bin/bash # -# 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. +# texinfo.sh -- This function initilializes Texinfo documentation +# backend used by `centos-art.sh' script to produce and maintain +# documentation manuals written in Texinfo format, inside the working +# copy of The CentOS Artwork Repository. # # Copyright (C) 2009, 2010, 2011 The CentOS Project # @@ -27,45 +27,6 @@ function texinfo { - # Define file extension used by source files inside manuals. - MANUAL_EXTENSION='texinfo' - - # Define absolute path to chapter's directory. This is the place - # where chapter-specific files are stored in. - MANUAL_CHAPTER_DIR="${MANUAL_BASEDIR_L10N}/${MANUAL_CHAPTER_NAME}" - - # 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=${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \ - ${MANUAL_BACKEND} -d)/Templates - - # 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. - # If it doesn't exist, use English language as default location to - # retrive template files. - if [[ ! -d $MANUAL_TEMPLATE_L10N ]];then - MANUAL_TEMPLATE_L10N=${MANUAL_TEMPLATE}/en_US - fi - - # Define absolute path to manual's configuration file. This is the - # file that controls the way texinfo template files are applied to - # documentation entries once they have been created as well as the - # style and order used for printing sections. There is one default - # configuration file inside templates and, optionally, a - # manual-specific configuration file. When manual-specific - # configuration file isn't found, the default configuration file - # is used instead. - if [[ -f ${MANUAL_BASEDIR_L10N}/${MANUAL_NAME}.conf ]];then - MANUAL_CONFIG_FILE="${MANUAL_BASEDIR_L10N}/${MANUAL_NAME}.conf" - else - MANUAL_CONFIG_FILE="${MANUAL_TEMPLATE}/manual.conf" - fi - # Initialize document structure for new manuals. ${MANUAL_BACKEND}_createStructure @@ -115,11 +76,8 @@ function texinfo { # Update manual's output files. ${MANUAL_BACKEND}_updateOutputFiles - # Read manual's Top node from info output file. - info --node="Top" --file=${MANUAL_BASEFILE}.info.bz2 - - # Terminate script execution right here. - exit + # Read manual's Top node from its info output file. + info --node="Top" --file="${MANUAL_BASEFILE}.info.bz2" elif [[ $ACTIONNAM =~ "^(copy|rename)Entry$" ]];then @@ -129,9 +87,12 @@ function texinfo { # processed in the first loop of their interpretation. ${MANUAL_BACKEND}_${ACTIONNAM} - # Break interpretation of non-option arguments, to prevent the + # Rebuild output files to propagate recent changes, if any. + ${MANUAL_BACKEND}_updateOutputFiles + + # Break interpretation of non-option arguments to prevent the # second and further non-option arguments from being - # considered a source location. + # considered as source location. break elif [[ $ACTIONNAM =~ "^(search(Node|Index)|updateOutputFiles)$" ]];then @@ -147,18 +108,15 @@ function texinfo { # control). ${MANUAL_BACKEND}_${ACTIONNAM} - # Terminate script execution right here. Actions realized in - # this configuration doesn't need to update manual output - # files, nor commit changes from working copy up to central - # repository. - exit - else # Execute action names that follow help's execution flow as it # is, without any modification. ${MANUAL_BACKEND}_${ACTIONNAM} + # Rebuild output files to propagate recent changes, if any. + ${MANUAL_BACKEND}_updateOutputFiles + fi } diff --git a/Scripts/Functions/Help/help.sh b/Scripts/Functions/Help/help.sh index ba98c40..6ccbb64 100755 --- a/Scripts/Functions/Help/help.sh +++ b/Scripts/Functions/Help/help.sh @@ -33,10 +33,6 @@ function help { # look for documentation inside documentation backends. local FLAG_SEARCH="" - # Initialize the backend flag (`--backend'). This option sets the - # documentation backed used to perform documentation actions. - local MANUAL_BACKEND='texinfo' - # Initialize manual's language. local MANUAL_L10N=$(cli_getCurrentLocale) @@ -81,13 +77,6 @@ function help { # information related documentation entries from there. ${CLI_FUNCNAME}_getEntries - # Initialize documentation backend functionalities. At this point - # we load all functionalities required into `centos-art.sh''s - # execution environment and make them available, this way, to - # perform backend-specific documentation tasks. - cli_exportFunctions "${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \ - ${MANUAL_BACKEND} -d)" "${MANUAL_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 @@ -121,20 +110,6 @@ function help { # added. MANUAL_CHANGED_DIRS="${MANUAL_BASEDIR_L10N}" - # 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. Notice that, because we are processing - # non-option arguments one by one, there is no need to - # sycronize changes to the same manual time after time - # (assuming all documentation entries passed as non-option - # arguments refer the same manual directory name). - if [[ ${MANUAL_DOCENTRY_ID} -eq 0 \ - || ( ( ${MANUAL_DOCENTRY_ID} -gt 0 ) && ( \ - ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} - 1))]} ) ) ]];then - cli_syncroRepoChanges ${MANUAL_CHANGED_DIRS} - fi - # 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.). @@ -143,20 +118,127 @@ function help { # Define chapter name. MANUAL_CHAPTER_NAME=${MANUAL_CHAN[${MANUAL_DOCENTRY_ID}]} + # Define absolute path to chapter's directory. This is the + # place where chapter-specific files are stored in. + MANUAL_CHAPTER_DIR="${MANUAL_BASEDIR_L10N}/${MANUAL_CHAPTER_NAME}" + # Define section name. MANUAL_SECTION_NAME=${MANUAL_SECN[${MANUAL_DOCENTRY_ID}]} + # Define absolute path to manual's configuration file. This + # is the file that controls the way template files are applied + # to documentation entries once they have been created as well + # as the style and order used for printing sections. + MANUAL_CONFIG_FILE="${MANUAL_BASEFILE}.conf" + + # Define documentation backend. This information defines the + # kind of source files we work with inside the documentation + # manual as well as the kind of actions required by them to + # perform actions related to document management (e.g., + # creation, edition, deletion, copying, renaming, etc.). + if [[ -f ${MANUAL_CONFIG_FILE} ]];then + + # Retrive documentation backend from configuration file. + MANUAL_BACKEND=$(cli_getConfigValue \ + "${MANUAL_CONFIG_FILE}" "main" "manual_backend") + + # Verify documentation backend. This is required because + # in order to prevent malformed values from being used. Be + # sure only supported documentation backends could be + # provided as value to `manual_backend' option in + # configuration files. + if [[ ! $MANUAL_BACKEND =~ '^(texinfo)$' ]];then + cli_printMessage "`gettext "The documentation backend provided isn't supported."`" --as-error-line + fi + + else + + # When the current documentation manual is being created + # for first time, there's no way to get the documentation + # backend to use in the future manual, but asking the user + # creating it which one to use. + cli_printMessage "`gettext "Select one of the following documentation backends:"`" + MANUAL_BACKEND=$(cli_printMessage "texinfo" --as-selection-line) + + fi + + # Define file extension used by source files inside manuals. + MANUAL_EXTENSION="${MANUAL_BACKEND}" + + # 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=${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \ + ${MANUAL_BACKEND} -d)/Templates + + # 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. If it doesn't exist, use English language as + # default location to retrive template files. + if [[ ! -d $MANUAL_TEMPLATE_L10N ]];then + MANUAL_TEMPLATE_L10N=${MANUAL_TEMPLATE}/en_US + fi + + # Notice that, because we are processing non-option arguments + # one by one, there is no need to sycronize changes or + # initialize functionalities to the same manual time after + # time (assuming all documentation entries passed as + # non-option arguments refer the same manual directory name). + # That would be only necessary when documentation entries + # refer to different manual directory names that could be + # written in different documentation backends. + if [[ ${MANUAL_DOCENTRY_ID} -eq 0 \ + || ( ( ${MANUAL_DOCENTRY_ID} -gt 0 ) && ( \ + ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} - 1))]} ) ) ]];then + + # 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_CHANGED_DIRS} + + # Initialize documentation backend functionalities. At + # this point we load all functionalities required into + # `centos-art.sh''s execution environment and make them + # available, this way, to perform backend-specific + # documentation tasks. + cli_exportFunctions "${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \ + ${MANUAL_BACKEND} -d)" "${MANUAL_BACKEND}" + + fi + # Execute backend-specific documentation tasks. ${MANUAL_BACKEND} + # Unset the exported functions before go on with the next + # documentation entry provided as non-option argument to + # `centos-art.sh' script. Different documentation entries may + # be written in different documentation backends. Each + # documentation backend is loaded in order to perform their + # related documentation tasks. Assuming more that one + # documentation entry be passed as non-option argument to + # `centos-art.sh' script and they are written in different + # formats, we might end up loading documentation backend + # functionalities that aren't used in the current + # documentation entry being processed. In that sake, unset + # documentation bakend functionalities when the next + # documentation entry refers to a manual directory different + # to that one being currently processed. + if [[ ${MANUAL_DOCENTRY_ID} -gt 0 \ + && ${MANUAL_DIRN[${MANUAL_DOCENTRY_ID}]} != ${MANUAL_DIRN[((${MANUAL_DOCENTRY_ID} + 1))]} ]];then + cli_unsetFunctions "${CLI_FUNCDIR}/${CLI_FUNCDIRNAM}/$(cli_getRepoName \ + ${MANUAL_BACKEND} -d)" "${MANUAL_BACKEND}" + fi + # Increment documentation entry counter id. MANUAL_DOCENTRY_ID=$(($MANUAL_DOCENTRY_ID + 1)) done - # Rebuild output files to propagate recent changes. - ${MANUAL_BACKEND}_updateOutputFiles - # 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.