From 6150a1886a2f3fed3f78678d736116d43d940398 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jul 10 2011 18:48:31 +0000 Subject: Update `help' functionality: - Reorganize functionality to work with texinfo files from `branches/Manuals/Texinfo' directory structure and permit creation of more than one documentation manual in this directory through `--manual' option. - The `--manual' option defines the documentation manual which all documentation actions are applied to. You can use this option when more than one documentation manual is available to specify the manual location you want to work with. - In this commit, new manuals are created with two chapters only and localization is based on templates. The first chapter is named `1. The repository directories' and the second one is named `2. Licenses'. Additionally the Index appendix was added too. From these two chapters, the first chapter is used by `help' functionality to store all documentation entries when you use documentation actions (e.g., `--edit', `--update', `--delete'). On the other hand, the second chapter is not editable through `help' functionlity. It links its content from templates used to build texinfo manuals. So, if you need to change something in the Licenses chapter, you need to go to `trunk/Scripts/Functions/Help/Texinfo/Templates' directory and change things there. - In this commit, the `help' functionality doesn't provide control to modify texinfo definitions of manual's main file and manual's chapter files. - Fix newline definition before list items created when `=TEXINFO_SEEALSO=' translation marker is expanded. - Fix path location to template files used to build texinfo manuals. --- diff --git a/Scripts/Functions/Help/Texinfo/texinfo.sh b/Scripts/Functions/Help/Texinfo/texinfo.sh index 2ce808f..8a63912 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo.sh @@ -27,15 +27,12 @@ function texinfo { - # Define file name (without extension) for documentation manual. - MANUAL_NAME=$(cli_getRepoName "$(basename $MANUAL_TLDIR)" -f) - # Define file extension used by documentation manual source files. MANUAL_EXTENSION='texinfo' - # Define manual base directory. This is where language-specific - # documentation source files are stored in. - MANUAL_BASEDIR="${MANUAL_BACKEND_DIR}/${MANUAL_LANG}" + # Define manual base directory. This is the place where + # language-specific documentation source files are stored in. + 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 @@ -68,13 +65,18 @@ function texinfo { # section file that represents the repository documentation entry. MANUAL_CHAPTER_DIR=${MANUAL_BASEDIR}/${MANUAL_CHAPTER_NAME} - # Define absolute path to backend template files. - MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/Texinfo/Templates/${MANUAL_LANG} + # Define absolute path to template directory. + MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/$(cli_getRepoName \ + $MANUAL_BACKEND -d)/Templates + + # Define absolute path to language-speicific template directory. + MANUAL_TEMPLATE_L10N=${MANUAL_TEMPLATE}/${MANUAL_L10N} - # Verify absolute path to backend template files. If the absolute - # path doesn't exist, use the English language templates. - if [[ ! -d $MANUAL_TEMPLATE ]];then - MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/Templates/en_US + # 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 # Create documentation structure, if it doesn't exist. @@ -83,7 +85,7 @@ function texinfo { # Syncronize changes between repository and working copy. At this # point, changes in the repository are merged in the working copy # and changes in the working copy committed up to repository. - cli_syncroRepoChanges ${MANUAL_CHAPTER_DIR} + cli_syncroRepoChanges ${MANUAL_BASEDIR} # Execute backend functionalities. Notice that there are # functionalities that need more than one action value in order to @@ -130,7 +132,7 @@ function texinfo { # this point, changes in the repository are not merged in the # working copy, but chages in the working copy do are committed up # to repository. - cli_commitRepoChanges ${MANUAL_CHAPTER_DIR} + cli_commitRepoChanges ${MANUAL_BASEDIR} # Rebuild output files to propagate recent changes. ${MANUAL_BACKEND}_updateOutputFiles diff --git a/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh b/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh index 5fb89e0..43b8588 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_createChapters.sh @@ -30,7 +30,7 @@ function texinfo_createChapters { # Define list of chapter templates files used as base to create # the chapters' documentation manual. local FILE='' - local FILES=$(cli_getFilesList ${MANUAL_TEMPLATE} \ + local FILES=$(cli_getFilesList ${MANUAL_TEMPLATE_L10N} \ --pattern='chapter(-menu|-nodes)?\.texinfo' --mindepth='2') # Loop through chapter structures and create them. diff --git a/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh b/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh index bf59c64..a8d0d79 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_createStructure.sh @@ -31,21 +31,55 @@ function texinfo_createStructure { # exist, assume it was correctly created in the past. 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 fi - # Print action message. + # Print separator line. cli_printMessage "-" --as-separator-line - cli_printMessage "`gettext "Creating manual structure."`" - # Create the language-specific directory used to store all files - # related to documentation manual. + # 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. + if [[ ! -d ${MANUAL_TLDIR} ]];then + + # Use subversion to create the top-level directory. + svn mkdir ${MANUAL_TLDIR} --quiet + + fi + + # Create manual's base directory. This is the place where + # language-specific documentation source files are stored in. svn mkdir ${MANUAL_BASEDIR} --quiet + # Retrive manual's information from standard input. + cli_printMessage "`gettext "Enter manual's title"`" --as-request-line + read MANUAL_TITLE + cli_printMessage "`gettext "Enter manual's subtitle"`" --as-request-line + read MANUAL_SUBTITLE + cli_printMessage "`gettext "Enter manual's 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."`" + + # 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 + fi + # Define file names required to build the manual. local FILE='' - local FILES=$(cli_getFilesList "${MANUAL_TEMPLATE}" \ + local FILES=$(cli_getFilesList "${MANUAL_TEMPLATE_L10N}" \ --maxdepth='1' \ - --pattern="repository(-menu|-nodes|-index)?\.${MANUAL_EXTENSION}") + --pattern="manual(-menu|-nodes|-index)?\.${MANUAL_EXTENSION}") # Verify manual base file. The manual base file is where the # documentation manual is defined in the backend format. Assuming @@ -53,9 +87,27 @@ function texinfo_createStructure { # created), use texinfo templates for it. for FILE in $FILES;do if [[ ! -f ${MANUAL_BASEDIR}/$(basename ${FILE}) ]];then + + # Be sure the file is inside the working copy and under + # version control. cli_checkFiles ${FILE} -wn - svn cp ${FILE} ${MANUAL_BASEDIR}/$(basename ${FILE}) --quiet - cli_replaceTMarkers ${MANUAL_BASEDIR}/$(basename ${FILE}) + + # Define target file. + local DST=${MANUAL_BASEDIR}/$(basename ${FILE} \ + | sed -r "s!manual!${MANUAL_NAME}!") + + # Copy using subversion to register this action. + svn cp ${FILE} $DST --quiet + + # Expand common translation markers inside target file. + cli_replaceTMarkers $DST + + # Expand specific translation markers inside target file. + sed -r -i -e "s!=MANUAL_NAME=!${MANUAL_NAME}!g" \ + -e "s!=MANUAL_TITLE=!${MANUAL_TITLE}!g" \ + -e "s!=MANUAL_SUBTITLE=!${MANUAL_SUBTITLE}!g" \ + -e "s!=MANUAL_ABSTRACT=!${MANUAL_ABSTRACT}!g" $DST + fi done @@ -73,6 +125,8 @@ function texinfo_createStructure { # 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} + if [[ ! -d ${MANUAL_TLDIR} ]];then + cli_commitRepoChanges ${MANUAL_TLDIR} + fi } diff --git a/Scripts/Functions/Help/Texinfo/texinfo_makeSeeAlso.sh b/Scripts/Functions/Help/Texinfo/texinfo_makeSeeAlso.sh index 05b8010..9a86ad7 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_makeSeeAlso.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_makeSeeAlso.sh @@ -58,7 +58,7 @@ function texinfo_makeSeeAlso { NODECOMPS_TOTAL=$(($NODECOMPS_TOTAL - 1)) done) else - SEEALSO_LIST=$(echo '\\n@item @dots{}') + SEEALSO_LIST=$(echo '\n@item @dots{}') fi # Define the list type and merge its content. diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh index 5eee612..d9582e2 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateNodes.sh @@ -50,7 +50,7 @@ function texinfo_updateNodes { # 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}/${MANUAL_NAME}.conf" + local CONFFILE="${MANUAL_TEMPLATE_L10N}/manual.conf" # Verify existence of configuration file. cli_checkFiles $CONFFILE @@ -88,7 +88,7 @@ function texinfo_updateNodes { | sed -r 's![[:space:]]*!!g' | sed -r 's!^"(.+)"$!\1!') if [[ ${MANUAL_BASEDIR}/${INCL} =~ $CONFRHS ]];then - TEMPLATE="${MANUAL_TEMPLATE}/${CONFLHS}" + TEMPLATE="${MANUAL_TEMPLATE_L10N}/${CONFLHS}" break fi @@ -119,11 +119,11 @@ function texinfo_updateNodes { # 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}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} + cli_checkFiles ${MANUAL_TEMPLATE_L10N}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} # Output node information chapter-nodes template file using # the current texinfo menu information. - cat ${MANUAL_TEMPLATE}/${MANUAL_CHAPTER_NAME}/chapter-nodes.${MANUAL_EXTENSION} \ + 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" diff --git a/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFileXhtml.sh b/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFileXhtml.sh index 8f52124..b5a0cfb 100755 --- a/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFileXhtml.sh +++ b/Scripts/Functions/Help/Texinfo/texinfo_updateOutputFileXhtml.sh @@ -26,12 +26,12 @@ function texinfo_updateOutputFileXhtml { # Verify initialization files used by texi2html. - cli_checkFiles ${MANUAL_BACKEND_DIR}/${MANUAL_NAME}-init.pl - cli_checkFiles ${MANUAL_TEMPLATE}/${MANUAL_NAME}-init.pl + cli_checkFiles ${MANUAL_TEMPLATE}/manual-init.pl + cli_checkFiles ${MANUAL_TEMPLATE_L10N}/manual-init.pl # Verify transformation files used to modify texi2html output. - cli_checkFiles ${MANUAL_BACKEND_DIR}/${MANUAL_NAME}.sed - cli_checkFiles ${MANUAL_TEMPLATE}/${MANUAL_NAME}.sed + cli_checkFiles ${MANUAL_TEMPLATE}/manual.sed + cli_checkFiles ${MANUAL_TEMPLATE_L10N}/manual.sed # Output action message. cli_printMessage "${MANUAL_BASEFILE}.xhtml.tar.bz2" --as-updating-line @@ -59,10 +59,10 @@ function texinfo_updateOutputFileXhtml { pushd ${MANUAL_NAME}-xhtml > /dev/null # Update xhtml files. Use texi2html to export from texinfo file - # format to xhtml using CentOS Web default visual style. + # format to xhtml using The CentOS Web default visual style. texi2html --lang=$(cli_getCurrentLocale --langcode-only) \ - --init-file=${MANUAL_BACKEND_DIR}/${MANUAL_NAME}-init.pl \ - --init-file=${MANUAL_TEMPLATE}/${MANUAL_NAME}-init.pl \ + --init-file=${MANUAL_TEMPLATE}/manual-init.pl \ + --init-file=${MANUAL_TEMPLATE_L10N}/manual-init.pl \ --output=${MANUAL_BASEDIR}/${MANUAL_NAME}-xhtml \ ${MANUAL_BASEDIR}/${MANUAL_NAME}.${MANUAL_EXTENSION} @@ -79,8 +79,8 @@ function texinfo_updateOutputFileXhtml { # structure to a completly different thing that can be handle # through classed inside CSS definitions. sed -r -i \ - -f ${MANUAL_BACKEND_DIR}/${MANUAL_NAME}.sed \ - -f ${MANUAL_TEMPLATE}/${MANUAL_NAME}.sed \ + -f ${MANUAL_TEMPLATE}/manual.sed \ + -f ${MANUAL_TEMPLATE_L10N}/manual.sed \ ${MANUAL_BASEFILE}-xhtml/*.xhtml # Compress directory structure where xhtml files are stored in. diff --git a/Scripts/Functions/Help/help.sh b/Scripts/Functions/Help/help.sh index 3ed6f7d..3a69c94 100755 --- a/Scripts/Functions/Help/help.sh +++ b/Scripts/Functions/Help/help.sh @@ -31,26 +31,32 @@ function help { # Initialize search option (`--search'). This option is used to # look for documentation inside documentation backends. - FLAG_SEARCH="" + local FLAG_SEARCH="" - # Define manual top level directory. This is where - # backend-specific documentation structures are stored in. - MANUAL_TLDIR="$(cli_getRepoTLDir)/Manuals/TCAR-UG" + # 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" - # Define manual language. - MANUAL_LANG=$(cli_getCurrentLocale) + # Initialize manual's language. + local MANUAL_L10N=$(cli_getCurrentLocale) - # Define default documentation backend. - MANUAL_BACKEND='texinfo' - - # Define backend directory path. This is the place where common - # files to all languages and language-specific directories are - # stored in. - MANUAL_BACKEND_DIR=${MANUAL_TLDIR}/$(cli_getRepoName $MANUAL_BACKEND -d) + # 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' # 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 positional parameters using ARGUMENTS. At this point, # option arguments have been removed from ARGUMENTS variable and # only non-option arguments remain in it. @@ -63,8 +69,4 @@ function help { # Execute backend-specific actions. ${MANUAL_BACKEND} $@ - # Unset backend-specific functionalities. - cli_unsetFunctions "${FUNCDIR}/${FUNCDIRNAM}/$(cli_getRepoName \ - ${MANUAL_BACKEND} -d)" "${MANUAL_BACKEND}" - } diff --git a/Scripts/Functions/Help/help_getOptions.sh b/Scripts/Functions/Help/help_getOptions.sh index 8b801d7..50e234f 100755 --- a/Scripts/Functions/Help/help_getOptions.sh +++ b/Scripts/Functions/Help/help_getOptions.sh @@ -29,7 +29,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" + local ARGSL="quiet,answer-yes,dont-commit-changes,backend:,read,search:,edit,update,copy,delete,rename,manual:" # Parse arguments using getopt(1) command parser. cli_parseArguments @@ -63,6 +63,11 @@ function help_getOptions { shift 2 ;; + --manual ) + FLAG_MANUAL=$(cli_getRepoName "$2" -f | tr '[:lower:]' '[:upper:]') + shift 2 + ;; + --search ) ACTIONNAM="searchIndex" FLAG_SEARCH="$2"