From 420e77685c2d7209b6b4e2475f8ae3609097cb6b Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jun 03 2011 03:05:26 +0000 Subject: Update `help' functionality: Backends/Texinfo/texinfo_updateNodes.sh - When documentation entries are created for functions (files stored in the first directory level under `trunk/Scripts/Functions') a specially design template is used for it. This template was built using the `cp' command man page structure as reference. - When documentation entries are created for non-function directories, a general purpose structure is used to provide goals, description, usage and related references to the documentation entry. - Start using subversion to copy files. This way, the action is also registered on subversion's logs. Backends/Texinfo/texinfo_updateOutputFileInfo.sh - Start using the option `--enable-encoding' when exporting to info format. This option permits to show special characters in Info or plain text output based on `@documentencoding' directive. Set this, all documents written in languages others than English must include the `@documentencoding' directive in order for info and text files output from them to show special characters. It is also required that the terminal enconding be the same of that defined by `@documentencoding' directory. For example, in the Spanish document we set the following directive on `repository.texinfo' file: @documentlanguage es @documentencoding ISO-8859-1 These directives say that the document is in Spanish language and codified in iso-8859-1 standard. Now, after output the info file from this document and, in order for it to show special characters it is required that the terminal had been set to use ISO-8859-1 encoding, as well. Otherwise, the special characters may no be displayed as you expect. Backends/Texinfo/texinfo_updateOutputFileXhtml.sh - Add verification to templates and transformation commands required to produce XHTML output through texi2html. - Add verification to initialization files used by texi2html. These files are generally used to localized the output produced by texi2html from English to different languages. - Add language specification (`--lang') to texi2html command. This is the value used as key to determine what value to use when producing texi2html output in different languages. - Separate transformation commands in common and language-specific transformation commands. This is required because we are supporting more than one language. For example, transformation used to build admonition in English language use one pattern (in English language) and transformation used to build admonitions in Spanish language use another pattern (in Spanish language). Other transformations like adding `class="www"' to `a' XHTML elements is common for all languages, so we kept it as common transformation. Backends/Texinfo/texinfo_createStructure.sh - Simplify code. Start using the `cli_getFilesList' function. - Stop using 'texinfo_updateChaptersFiles'. Start using `texinfo_createChapters' instead. Backends/Texinfo/texinfo_createChapter.sh - Update cli_getFilesList `--pattern'. Backends/Texinfo/texinfo_updateChaptersMenu.sh - Don't consider `* Index::' menu-line when the MENUCHAPTERS is built. This chapter is treated specially compared with `Directories' and `Licenses' chapters. Index is directly included at file `repository.texinfo' and uses the file `repository-index.texinfo' file as definition. These files are created the first time the documentation manual is created and `help' functionality doesn't modify them in anyway. Backends/Texinfo/texinfo_getEntry.sh - Fix invokation of cli_getRepoDirSource based on revision 3194. - Use MANUAL_CHAPTER_NAME variable instead of fixed name. Backends/Texinfo/texinfo_updateChaptersNodes.sh - Don't consider '* Index::' menu-line. Backends/Texinfo/texinfo_editEntry.sh - Remove MANUAL_CHAPTER_DIR verifications. They are already set as part of texinfo_createStructure. - Verify the parent directory of documentation entries. In order to create a documentation entry it is required that a parent directory for this documentation entry does exist. Otherwise stop script execution with an error message describing the issue. help_getOptions.sh - Don't suppress subversion actions internally when reading documentation entries. help.sh - Update texinfo manuals directory structure to support the documentation manual in different languages. I don't know of a `texi2po' command that can be used here (as we did with `xml2po' in SVG files), so one documentation manual structure is created for each language (based on LANG environment variable): trunk/Manuals/Texinfo |-- $LANG | |-- Directories | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | |-- chapter.texinfo | | `-- trunk.texinfo | |-- Licenses | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | `-- chapter.texinfo | |-- repository-index.texinfo | |-- repository-menu.texinfo | |-- repository-nodes.texinfo | `-- repository.texinfo In this configuration, no translation is performed to file and directory names. Doing so let us to reuse them in all manual structures equally, no matter what the prefered language be. This, for example, save us the work of considering the manipulation of different file names for different documentation manuals (e.g., in English we've the word `chapter', but in Spanish we've the word `capítulo'.) which is quiet different. The `Directories' chapter is created automatically when then documentation manual is created for the very first time. The documentation entries related to repository directories are stored herein, using the same names and organization that repository do (e.g., The `trunk.texinfo' file is the documentation entry of 'trunk/' directory.) The `License' chapter is created automatically when the documentation manual is created for the very first time. The licenses themselves are not copied here, but included from `trunk/Scripts/Functions/Help/Backends/Texinfo/$LANG/Licenses/' directory structure using the `@include' definition. The `repository-*.texinfo' files at the base directory structure contain document definitions, specific to the backend associates (e.g., `texinfo') and are created automatically when the documentation manual is created for the very first time. Common information to all languages (e.g., texi2html initialization files, CSS, and sed transformations) are placed in language-specific templates, a common place that all documentation manuals can reuse. For example, both English and Spanish XHTML documentation manuals use the same CSS definitions. Language-specific templates are stored inside the help functionality directory structure and are required in order for a new language-specific documentation manual to be created: trunk/Scripts/Functions/Help/Backends/Texinfo/Templates |-- $LANG | |-- Directories | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | |-- chapter.texinfo | | |-- section-functions.texinfo | | `-- section.texinfo | |-- Licenses | | |-- GFDL.texinfo | | |-- GPL.texinfo | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | `-- chapter.texinfo | |-- repository-index.texinfo | |-- repository-init.pl | |-- repository-menu.texinfo | |-- repository-nodes.texinfo | |-- repository.sed | `-- repository.texinfo The help functionality uses these file as reference to create documentation entries, translate English messages of texi2html to other languages, perform XHTML transformations (e.g., to create admonitions). - There is just one MANUAL_CHAPTER_DIR correct value. This is the place where repository documentation entries are stored in. All actions performed through help functionality will take place in this location. If you change something outside this structure (e.g., adding new authors to `repository.texinfo'), it is required that you take care of committing those by yourself. The help functionality hasn't modification scope there. - There is just one MANUAL_CHAPTER_NAME correct value. This is the name of the file (without extension) we use to store documentation manual main files (e.g., `repository.texinfo', `repository-menu.texinfo', `repository-nodes.texinfo', etc) - Remove unnecessary definitions of MANUAL_CHAPTER_NAME and MANUAL_CHAPTER_DIR. - Readjust subversion verifications. When the manual is created for the first time, commit from working copy to central repository. In normal workflow, changes are braught from central repository first, later changes from the working copy are uploaded. At this poing a clean state of the working copy must be set, so an action is performed. This action may modify the state of the workgin copy so another subversion verification is required here to commit any local change up to central repository. --- 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 ;;