From f8fb31a458249135a34108bc933fe3f815532bf5 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Dec 02 2010 23:51:56 +0000 Subject: Update manual functionality: - Add manual_removeCrossReferences.sh -- This function removes a documentation entry cross refereces from all texinfo files the documentation manual is built on. - Add manual_restoreCrossReferences.sh -- This function restores old missing cross references back into their link form. This function applies in those cases where new documentation entries are added to documentation structure. It is a verification looking for matching documentation entries previously defined as missing. This function relays in the missing message output produced by functions like manual_removeCrossReferences, in order to return them back into the link format. - Update manual_createEntry.sh to use manual_recoverCrossReferences. - Update manual_removeEntry.sh to use manual_removeCrossReferences. --- diff --git a/Scripts/Bash/Functions/Manual/manual_createEntry.sh b/Scripts/Bash/Functions/Manual/manual_createEntry.sh index 5871ddb..2b7e2b4 100755 --- a/Scripts/Bash/Functions/Manual/manual_createEntry.sh +++ b/Scripts/Bash/Functions/Manual/manual_createEntry.sh @@ -35,4 +35,11 @@ function manual_createEntry { # Update chapter-nodes (based on chapter-menu). manual_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_restoreCrossReferences + } diff --git a/Scripts/Bash/Functions/Manual/manual_removeCrossReferences.sh b/Scripts/Bash/Functions/Manual/manual_removeCrossReferences.sh new file mode 100755 index 0000000..6b10927 --- /dev/null +++ b/Scripts/Bash/Functions/Manual/manual_removeCrossReferences.sh @@ -0,0 +1,69 @@ +#!/bin/bash +# +# manual_removeCrossReferences.sh -- This function removes a +# documentation entry cross refereces from all texinfo files the +# documentation manual is built on. +# +# Copyright (C) 2009, 2010 Alain Reguera Delgado +# +# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +# USA. +# +# ---------------------------------------------------------------------- +# $Id$ +# ---------------------------------------------------------------------- + +function manual_removeCrossReferences { + + local -a PATTERN + local -a REPLACE + + # Build the node string using global entry (ENTRY) variable being + # processed currently. + local NODE=$(echo "$ENTRY" \ + | cut -d / -f10- \ + | tr '/' ' ' \ + | sed -r "s/(${MANUALS_FILE[7]}|\.texi)$//") + + # Define regular expression patterns for texinfo cross reference + # commands. + PATTERN[0]="@(pxref|xref|ref)\{(${NODE})\}" + PATTERN[1]="^(\* ${NODE}:(.*)?:(.*)?)$" + + # Define replacement string for missing entries. It is convenient + # to keep missing entries in documentation for documentation team + # to know. Removing the missing cross reference may intorudce + # confussion. Imagine that! you are spending lots of hours in an + # article and suddenly one of your cross refereces disappears with + # no visible reason, with the next working copy update you + # perform. That's frustrating. Instead, when centos-art.sh script + # finds a missing cross reference it removes the link and remark + # the issue for you to act on it. + REPLACE[0]='--- @strong{'`gettext "Removed"`'}(\1:\2) ---' + REPLACE[1]='@comment --- '`gettext "Removed"`'(\1) ---' + + # Sanitate all missing cross references, related to entry, in + # section texinfo files. Missing cross references, related to + # entry, in chapter texinfo files are already handled by + # manual_updateMenu, and manual_updateNode functions. If we don't + # sanitate missing cross refereces before info file is created, + # errors are displayed since makeinfo don't produce info output + # with broken cross refereces. + sed -r -i \ + -e "s!${PATTERN[0]}!${REPLACE[0]}!Mg" \ + -e "s!${PATTERN[1]}!${REPLACE[1]}!g" \ + $(find ${MANUALS_DIR[2]} -mindepth 3 -name '*.texi') + +} diff --git a/Scripts/Bash/Functions/Manual/manual_removeEntry.sh b/Scripts/Bash/Functions/Manual/manual_removeEntry.sh index db93d92..af818e2 100755 --- a/Scripts/Bash/Functions/Manual/manual_removeEntry.sh +++ b/Scripts/Bash/Functions/Manual/manual_removeEntry.sh @@ -31,6 +31,9 @@ function manual_removeEntry { local ENTRIES_COUNTER=0 local LOCATION='' + # Check changes in the working copy. + cli_commitRepoChanges "$ENTRY" + # Check if the entry has been already removed. if [[ ! -f $ENTRY ]];then cli_printMessage "`gettext "The following entry doesn't exist:"`" @@ -69,8 +72,8 @@ function manual_removeEntry { # Show a verification message before doing anything. cli_printMessage "`ngettext "The following entry will be removed:" \ - "The following entries will be removed:" \ - $ENTRIES_COUNTER`" + "The following entries will be removed:" \ + $ENTRIES_COUNTER`" # Show list of affected entries. for ENTRY in $ENTRIES;do @@ -95,10 +98,9 @@ function manual_removeEntry { # of changes. Only if documentation entry is clean of # changes we can mark it for deletion. So use subversion's # `del' command to do so. - eval svn del "$ENTRY" --quiet + svn del "$ENTRY" --quiet - elif [[ "$(cli_getRepoStatus "$ENTRY")" == '?' ]] \ - || [[ "$(cli_getRepoStatus "$ENTRY")" == '' ]] ;then + elif [[ "$(cli_getRepoStatus "$ENTRY")" == '?' ]];then # Documentation entry is not under version control, so we # don't care about changes inside unversioned @@ -122,11 +124,14 @@ function manual_removeEntry { fi - # Update section's menu and nodes to reflect the fact that - # documentation entry has been removed. + # Remove entry on section's menu and nodes to reflect the + # fact that documentation entry has been removed. manual_updateMenu "remove-entry" manual_updateNodes + # Remove entry cross references from documentation manual. + manual_removeCrossReferences + done # Update chapter's menu and nodes in the master texinfo document. diff --git a/Scripts/Bash/Functions/Manual/manual_restoreCrossReferences.sh b/Scripts/Bash/Functions/Manual/manual_restoreCrossReferences.sh new file mode 100755 index 0000000..012c267 --- /dev/null +++ b/Scripts/Bash/Functions/Manual/manual_restoreCrossReferences.sh @@ -0,0 +1,70 @@ +#!/bin/bash +# +# manual_restoreCrossReferences.sh -- This function restores old +# missing cross references back into their link form. This function +# applies in those cases where new documentation entries are added to +# documentation structure. It is a verification looking for matching +# documentation entries previously defined as missing. This function +# relays in the missing message output produced by functions like +# manual_removeCrossReferences, in order to return them back into the +# link format. +# +# Copyright (C) 2009, 2010 Alain Reguera Delgado +# +# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +# USA. +# +# ---------------------------------------------------------------------- +# $Id$ +# ---------------------------------------------------------------------- + +function manual_restoreCrossReferences { + + local -a PATTERN + local -a REPLACE + + # Build the node string using global entry (ENTRY) variable being + # processed currently. + local NODE=$(echo "$ENTRY" \ + | cut -d / -f10- \ + | tr '/' ' ' \ + | sed -r "s/(${MANUALS_FILE[7]}|\.texi)$//") + + # Define regular expression patterns from + # message_removeCrossReferences function output. + PATTERN[0]="--- @strong\{`gettext "Removed"`\}\((pxref|xref|ref):(${NODE})\) ---" + PATTERN[1]="^@comment --- `gettext "Removed"`\((\* ${NODE}:(.*)?:(.*)?)\) ---$" + + # Define replacement string for message_removeCrossReferences + # function output. Here is where we turn Removed messages back + # into links. + REPLACE[0]='@\1{\2}' + REPLACE[1]='\1' + + # Sanitate messages built from broken cross reference messages + # produced by manual_removeCrossReferences function for section + # texinfo files. We don't toch chapter texinfo files because they + # are handled by manual_updateMenu, and manual_updateNode + # functions. If we don't sanitate messages built from broken + # cross reference messages, they may become obsoletes since the + # documentation entry, they represent, can be recreated in the + # future and at that time the link wouldn't be broken any more, so + # we need to be aware of this. + sed -r -i \ + -e "s!${PATTERN[0]}!${REPLACE[0]}!Mg" \ + -e "s!${PATTERN[1]}!${REPLACE[1]}!g" \ + $(find ${MANUALS_DIR[2]} -mindepth 3 -name '*.texi') + +}