diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_createChapters.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_createChapters.sh index 183734d..44861ef 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_createChapters.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_createChapters.sh @@ -31,7 +31,7 @@ function texinfo_createChapters { # the chapters' documentation manual. local FILE='' local FILES=$(cli_getFilesList ${MANUAL_TEMPLATE} \ - --pattern='\.texinfo' --mindepth='2') + --pattern='chapter(-menu|-nodes)?\.texinfo' --mindepth='2') # Loop through chapter structures and create them. for FILE in $FILES;do diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_createStructure.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_createStructure.sh index d66f06e..8f94fe7 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_createStructure.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_createStructure.sh @@ -33,34 +33,34 @@ function texinfo_createStructure { return fi - # Print confirmation question. + # Print action message. cli_printMessage "-" --as-separator-line cli_printMessage "`gettext "Creating manual structure."`" - # Define file names required to build the manual. - local MANUAL_FILE='' - local MANUAL_FILES="${MANUAL_NAME}.${FLAG_BACKEND} - ${MANUAL_NAME}-nodes.${FLAG_BACKEND} - ${MANUAL_NAME}-menu.${FLAG_BACKEND}" - - # Notify that a new directory for a language-specific - # documentation manual will be created. + # Create the language-specific directory used to store all files + # related to documentation manual. svn mkdir ${MANUAL_BASEDIR} --quiet + # Define file names required to build the manual. + local FILE='' + local FILES=$(cli_getFilesList "${MANUAL_TEMPLATE}" \ + --maxdepth='1' \ + --pattern="repository(-menu|-nodes|-index)?\.${FLAG_BACKEND}") + # Verify manual base file. The manual base file is where the # documentation manual is defined in the backend format. Assuming # no file exists (e.g., a new language-specific manual is being - # created), use texinfo templates to create it. - for MANUAL_FILE in $MANUAL_FILES;do - if [[ ! -f ${MANUAL_BASEDIR}/${MANUAL_FILE} ]];then - cli_checkFiles ${MANUAL_TEMPLATE}/${MANUAL_FILE} -wn - svn cp ${MANUAL_TEMPLATE}/${MANUAL_FILE} ${MANUAL_BASEDIR}/${MANUAL_FILE} --quiet - cli_replaceTMarkers ${MANUAL_BASEDIR}/${MANUAL_FILE} + # created), use texinfo templates for it. + for FILE in $FILES;do + if [[ ! -f ${MANUAL_BASEDIR}/$(basename ${FILE}) ]];then + cli_checkFiles ${FILE} -wn + svn cp ${FILE} ${MANUAL_BASEDIR}/$(basename ${FILE}) --quiet + cli_replaceTMarkers ${MANUAL_BASEDIR}/$(basename ${FILE}) fi done # Update manual chapter related files. - ${FLAG_BACKEND}_updateChaptersFiles + ${FLAG_BACKEND}_createChapters # Update manual chapter related menu. ${FLAG_BACKEND}_updateChaptersMenu diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_editEntry.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_editEntry.sh index 2a9349c..b54f64a 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_editEntry.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_editEntry.sh @@ -28,29 +28,21 @@ function texinfo_editEntry { # Print separator line. cli_printMessage '-' --as-separator-line - # Verify chapter definition inside manual. - if [[ ! -d $MANUAL_CHAPTER_DIR ]];then - - # Print confirmation question. - 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 - - # Update manual chapter related files. - ${FLAG_BACKEND}_updateChaptersFiles - - # Update manual chapter related menu. - ${FLAG_BACKEND}_updateChaptersMenu - - # Update manual chapter related nodes (based on chapter - # related menu). - ${FLAG_BACKEND}_updateChaptersNodes - - fi - # 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 + fi + # Print confirmation question. cli_printMessage "`gettext "The following documentation section will be created:"`" cli_printMessage "$MANUAL_ENTRY" --as-response-line diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_getEntry.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_getEntry.sh index 938aa4f..2b5ac3d 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_getEntry.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_getEntry.sh @@ -44,7 +44,7 @@ function texinfo_getEntry { for LOCATION in $LOCATIONS;do # Sanitate action value to use absolute paths. - cli_checkRepoDirSource $LOCATION + LOCATION=$(cli_checkRepoDirSource $LOCATION) # Define relative path of entry, from trunk directory on. MANUAL_ENTRY=$(echo $LOCATION | sed -r "s!^${HOME}/artwork/!!") @@ -59,7 +59,7 @@ function texinfo_getEntry { if [[ ${MANUAL_ENTRY} =~ "\.${FLAG_BACKEND}$" ]];then MANUAL_ENTRY=$(echo ${MANUAL_ENTRY} | sed "s!trunk/Manuals/$(cli_getRepoName ${FLAG_BACKEND} -d)/!!") else - MANUAL_ENTRY=$(dirname Directories/${MANUAL_ENTRY})/$(basename $LOCATION).${FLAG_BACKEND} + MANUAL_ENTRY=$(dirname ${MANUAL_CHAPTER_NAME}/${MANUAL_ENTRY})/$(basename $LOCATION).${FLAG_BACKEND} fi # Re-define entry to set absolute path to manuals base diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersMenu.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersMenu.sh index 293d9a6..70be7e2 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersMenu.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersMenu.sh @@ -34,7 +34,7 @@ function texinfo_updateChaptersMenu { # even no other node exist. if [[ -f ${MANUAL_BASEFILE}-menu.${FLAG_BACKEND} ]];then MENUCHAPTERS=$(cat ${MANUAL_BASEFILE}-menu.${FLAG_BACKEND} \ - | egrep -v "^(@(end )?menu$|\* Index::.*)$") + | egrep -v "^@(end )?menu$" | egrep -v '^\* Index::$') fi # Re-defined menu of chapters based on action. diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersNodes.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersNodes.sh index b88a42c..e879ccb 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersNodes.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateChaptersNodes.sh @@ -27,21 +27,20 @@ function texinfo_updateChaptersNodes { # Build list "nodes of chapters" based on menu of chapters. local CHAPTERNODES=$(cat ${MANUAL_BASEFILE}-menu.${FLAG_BACKEND} \ - | egrep -v '^@(end )?menu$' \ - | egrep -v "^\* `gettext "Index"`::[[:print:]]*$" \ + | egrep -v '^@(end )?menu$' | egrep -v '^\* Index::$'\ | sed -r 's!^\* !!' | sed -r 's!::[[:print:]]*$!!g' \ | sed -r 's! !_!g' | sort | uniq ) - # Build list of texinfo inclusions to load chapters' nodes. + # 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. local FILENODE=$(\ - for CHAPTERNODE in ${CHAPTERNODES};do - - INCL=$(echo ${CHAPTERNODE} | sed -r "s!(${CHAPTERNODE})!\1/chapter\.${FLAG_BACKEND}!") - - # Output inclusion line using texinfo format. - echo "@include $INCL" - - done) + for CHAPTERNODE in ${CHAPTERNODES};do + INCL=$(echo ${CHAPTERNODE} \ + | sed -r "s!(${CHAPTERNODE})!\1/chapter\.${FLAG_BACKEND}!") + # Output inclusion line using texinfo format. + echo "@include $INCL" + done) # Dump organized nodes of chapters into file. echo "$FILENODE" > ${MANUAL_BASEFILE}-nodes.${FLAG_BACKEND} diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateNodes.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateNodes.sh index 4a49596..38560a5 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateNodes.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateNodes.sh @@ -36,14 +36,9 @@ function texinfo_updateNodes { 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').${FLAG_BACKEND} - CIND=$(echo "$NODE") - - # Create an empty directory to store texinfo files. - if [[ ! -d ${MANUAL_BASEDIR}/$(dirname "$INCL") ]];then - mkdir -p ${MANUAL_BASEDIR}/$(dirname "$INCL") - fi + SECT=$(echo "${NODE}" | cut -d' ' -f2- | sed -r 's! !/!g') + INCL=$(echo "${NODE}" | sed -r 's! !/!g').${FLAG_BACKEND} + CIND=$(echo "${NODE}") # Create texinfo section file using templates, only if the # section file doesn't exist and hasn't been marked for @@ -55,17 +50,17 @@ function texinfo_updateNodes { # Define what template to apply using the absolute path of # the documentation entry as reference. - if [[ ${MANUAL_BASEDIR}/${INCL} =~ 'trunk/Scripts/Functions/.+' ]];then - TEXINFO_TEMPLATE="${MANUAL_TEMPLATE}/manual-section-functions.${FLAG_BACKEND}" + if [[ ${MANUAL_BASEDIR}/${INCL} =~ 'trunk/Scripts/Functions/[[:alnum:]]+$' ]];then + TEXINFO_TEMPLATE="${MANUAL_TEMPLATE}/${MANUAL_CHAPTER_NAME}/section-functions.${FLAG_BACKEND}" else - TEXINFO_TEMPLATE="${MANUAL_TEMPLATE}/manual-section.${FLAG_BACKEND}" + TEXINFO_TEMPLATE="${MANUAL_TEMPLATE}/${MANUAL_CHAPTER_NAME}/section.${FLAG_BACKEND}" fi # Verify texinfo template. cli_checkFiles $TEXINFO_TEMPLATE # Copy texinfo template to its destination. - cp ${TEXINFO_TEMPLATE} ${MANUAL_BASEDIR}/$INCL + svn cp ${TEXINFO_TEMPLATE} ${MANUAL_BASEDIR}/$INCL --quiet # Expand common translation markers. cli_replaceTMarkers "${MANUAL_BASEDIR}/$INCL" diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileInfo.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileInfo.sh index a158481..31a2141 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileInfo.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileInfo.sh @@ -29,7 +29,9 @@ function texinfo_updateOutputFileInfo { cli_printMessage "${MANUAL_BASEFILE}.info.bz2" --as-updating-line # Update info file. - /usr/bin/makeinfo ${MANUAL_BASEFILE}.${FLAG_BACKEND} --output=${MANUAL_BASEFILE}.info + /usr/bin/makeinfo --output=${MANUAL_BASEFILE}.info \ + --enable-encoding \ + ${MANUAL_BASEFILE}.${FLAG_BACKEND} # Compress info file. if [[ $? -eq 0 ]];then diff --git a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileXhtml.sh b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileXhtml.sh index 8fb393a..ea77685 100755 --- a/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileXhtml.sh +++ b/Scripts/Functions/Help/Backends/Texinfo/texinfo_updateOutputFileXhtml.sh @@ -25,6 +25,14 @@ function texinfo_updateOutputFileXhtml { + # Verify initialization files used by texi2html. + cli_checkFiles ${MANUAL_BACKEND}/${MANUAL_NAME}-init.pl + cli_checkFiles ${MANUAL_TEMPLATE}/${MANUAL_NAME}-init.pl + + # Verify transformation files used to modify texi2html output. + cli_checkFiles ${MANUAL_BACKEND}/${MANUAL_NAME}.sed + cli_checkFiles ${MANUAL_TEMPLATE}/${MANUAL_NAME}.sed + # Output action message. cli_printMessage "${MANUAL_BASEFILE}.xhtml.tar.bz2" --as-updating-line @@ -49,24 +57,29 @@ function texinfo_updateOutputFileXhtml { pushd ${MANUAL_BASEFILE}.xhtml > /dev/null # Update xhtml files. Use texi2html to export from texinfo file - # format to html using CentOS Web default visual style. - texi2html --init-file=${MANUAL_BASEDIR}/${MANUAL_BASEFILE}-init.pl \ - --output=${MANUAL_BASEDIR}/${MANUAL_BASEFILE}.xhtml \ - ${MANUAL_BASEDIR}/${MANUAL_BASEFILE}.${FLAG_BACKEND} + # format to xhtml using CentOS Web default visual style. + texi2html --lang=$(cli_getCurrentLocale --langcode-only) \ + --init-file=${MANUAL_BACKEND}/${MANUAL_NAME}-init.pl \ + --init-file=${MANUAL_TEMPLATE}/${MANUAL_NAME}-init.pl \ + --output=${MANUAL_BASEDIR}/${MANUAL_NAME}.xhtml \ + ${MANUAL_BASEDIR}/${MANUAL_NAME}.${FLAG_BACKEND} # Remove directory where xhtml files are stored from directory # stack. The xhtml files have been already created. popd > /dev/null # Apply xhtml transformations. This transformation cannot be built - # inside the initialization script (repository.init). For example, - # I can't see a possible way to produce different quotation HTML - # outputs from the same texinfo quotation definition. Instead, + # inside the initialization script (repository-init.pl). For example, + # Would it be a possible way to produce different quotation HTML + # outputs from the same texinfo quotation definition? Instead, # once the HTML code is produced we can take que quotation HTML # definition plus the first letters inside it and transform the # structure to a completly different thing that can be handle # through classed inside CSS definitions. - sed -r -i -f ${MANUAL_BASEFILE}.sed ${MANUAL_BASEFILE}.xhtml/*.xhtml + sed -r -i \ + -f ${MANUAL_BACKEND}/${MANUAL_NAME}.sed \ + -f ${MANUAL_TEMPLATE}/${MANUAL_NAME}.sed \ + ${MANUAL_BASEFILE}.xhtml/*.xhtml # Compress directory structure where xhtml files are stored in. # This compressed version is the one we put under version control. diff --git a/Scripts/Functions/Help/help.sh b/Scripts/Functions/Help/help.sh index 27d2ec5..720d58f 100755 --- a/Scripts/Functions/Help/help.sh +++ b/Scripts/Functions/Help/help.sh @@ -42,23 +42,50 @@ function help { # Interpret option arguments passed through the command-line. ${FUNCNAM}_getOptions - # Define manuals base directory. This is the place where - # documentation manuals base directory structures are stored and - # organized in. - MANUAL_BASEDIR="$(cli_getRepoTLDir)/Manuals/$(cli_getRepoName ${FLAG_BACKEND} -d)" + # Define manual backend directory. This is the place where all + # language specific documentation manuals, for the same backend + # documentation system, are stored in. + MANUAL_BACKEND=$(cli_getRepoTLDir)/Manuals/$(cli_getRepoName ${FLAG_BACKEND} -d) + + # Define manual base directory. This is the place where + # language-specific documentation manual is stored in. + MANUAL_BASEDIR="${MANUAL_BACKEND}/$(cli_getCurrentLocale)" # Define file name (without extension) for documentation manual. - MANUAL_NAME=repository + MANUAL_NAME=$(cli_getRepoName "repository" -f) # 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.). MANUAL_BASEFILE="${MANUAL_BASEDIR}/${MANUAL_NAME}" - # Define function configuration directory. The function - # configuration directory is used to store functionality's related - # files. - MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/Templates + # 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 backend template files. + MANUAL_TEMPLATE=${FUNCDIR}/${FUNCDIRNAM}/Templates/$(cli_getCurrentLocale) + + # 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 + fi # Redefine positional parameters using ARGUMENTS. At this point, # option arguments have been removed from ARGUMENTS variable and @@ -77,6 +104,14 @@ function help { cli_printMessage "`gettext "The backend provided is not supported."`" --as-error-line fi + # Create documentation structure, if it doesn't exist. + ${FLAG_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_CHAPTER_DIR} + # 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 @@ -87,33 +122,12 @@ function help { # functionalities is splitted here. if [[ $ACTIONNAM =~ "${FLAG_BACKEND}_(copy|rename|delete)Entry" ]];then - # Define directories where documentation entries are stored - # in. Since more than one action value might be affected - # here, more than one directory might be considered as chapter - # directory, as well. - MANUAL_CHAPTER_DIR=$(${FLAG_BACKEND}_getChapterDir "$@") - - # 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} - # Execute backend action names that may need to use more than # one action value. ${ACTIONNAM} $@ - # 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_CHAPTER_DIR} - elif [[ $ACTIONNAM =~ "${FLAG_BACKEND}_(search(Index|Node)|updateOutputFiles)" ]];then - # Bring changes from the repository to the working copy. - cli_updateRepoChanges ${MANUAL_BASEDIR} - # Execute backend action names that might not need any action # value as reference to do their work. $ACTIONNAM $@ @@ -128,61 +142,24 @@ function help { # Execute backend action names that use one action value, only. for ACTIONVAL in $@;do - # Define directories where documentation entries are - # stored in. Since just one action value is - # affected here, just one directory is considered as - # chapter directory, as well. - MANUAL_CHAPTER_DIR=$(${FLAG_BACKEND}_getChapterDir "${ACTIONVAL}") - - # Define chapter name for documentation entry we're working with. - MANUAL_CHAPTER_NAME=$(basename "$MANUAL_CHAPTER_DIR") - # Define documentation entry. MANUAL_ENTRY=$(${FLAG_BACKEND}_getEntry $ACTIONVAL) - # 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} - # Execute backend action names that may need to use more # than one action value. $ACTIONNAM - # 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_CHAPTER_DIR} - done fi + # 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_CHAPTER_DIR} + # Rebuild output files to propagate recent changes. ${FLAG_BACKEND}_updateOutputFiles - # Perform language-specific actions when the current language is - # other but English language. - if [[ ! $(cli_getCurrentLocale) =~ '^en' ]];then - - # Update translatable strings in related portable objects. - eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh locale --update ${MANUAL_BASEFILE}.xhtml --dont-commit-changes - - # Update translatable strings in related portable objects. - eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh locale --edit ${MANUAL_BASEFILE}.xhtml - - # Print separator. - cli_printMessage '-' --as-separator-line - - # Print action message. - cli_printMessage "${MANUAL_BASEFILE}.xhtml/$(cli_getCurrentLocale)" '--as-updating-line' - - # Render translated versions of the XHTML output files, - # supressing the rendition output. - eval ${CLI_BASEDIR}/${CLI_PROGRAM}.sh render ${MANUAL_BASEFILE}.xhtml --dont-commit-changes --quiet - - fi - } diff --git a/Scripts/Functions/Help/help_getOptions.sh b/Scripts/Functions/Help/help_getOptions.sh index 6a07140..beca05e 100755 --- a/Scripts/Functions/Help/help_getOptions.sh +++ b/Scripts/Functions/Help/help_getOptions.sh @@ -99,7 +99,6 @@ function help_getOptions { --read ) ACTIONNAM="searchNode" - FLAG_DONT_COMMIT_CHANGES='true' shift 1 ;;