GRASS manual translation: proposed script

From GRASS-Wiki
Jump to: navigation, search

Script to facilitate the creation of GRASS GIS manual pages in various languages:

The script

 #!/bin/bash
 ############################################################################
 #
 # MODULE:       grassdoclang.sh
 # AUTHOR(S):    Marco Curreli
 # PURPOSE:      build translation of GRASS full manual pages
 # COPYRIGHT:    (C) 2012 by Marco Curreli (at least for now)
 #
 #               This program is free software under the GNU General Public
 #               License (>=v2). Read the file COPYING that comes with GRASS
 #               for details.
 #
 # Tool to facilitate building GRASS GIS manual pages in your language,
 # including description and headers; the translation of the headers
 # is made by extracting mstr from grassmods_lang.po file
 #############################################################################
 
 
 # Usage: grassdoclang.sh [options]
 
 # inizializza le opzioni
 # initiate flags
 make_all="FALSE"
 make_translation="FALSE"
 make_man="FALSE"
 display_help="FALSE"
 check_update="FALSE"
 proceed="FALSE"
 
 # imposta le opzioni
 # set options
 while getopts "atmh" opt
 do
 	case "$opt" in
 	  "a")
 	      make_all="TRUE"
 	      proceed="TRUE"
 	      ;;
 	  "t")
 	      make_translation="TRUE"
 	      proceed="TRUE"
 	      ;;
 	  "m")
 	      make_man="TRUE"
 	      proceed="TRUE"
 	      ;;
 	  "h")
 	      display_help="TRUE"
 	      ;;
	  "c")
	      check_update="TRUE"
	      ;;
 	  "*")
 	      echo "is not a valid option"
 	      exit 1
 	      ;;
 	esac
 done
 shift $(($OPTIND - 1))
 
 
 ########  VARIABILI  ########
 ########  VARIABLES  ########
 # imposta la lingua
 # set lang
 export lang=$(echo $LANG  | cut  -c 1-2)
 
 # directory dei sorgenti di grass
 # grass source directory
 cd ../../..
 export SRCGRASSDIR=$(pwd)
 cd locale/desc/tools
 
 # directory contenente i file description.html tradotti
 # directory containing the translated files description.html
 export DESCDIR=$SRCGRASSDIR/locale/desc
 
 # directory dei manuali html
 # html manuals directory
 export HTMLDIR=$SRCGRASSDIR/dist.i686-pc-linux-gnu/docs/html
 
 # elenco dei file description tradotti
 # list of the description files translated
 export FILE=$(ls $DESCDIR/$lang | grep html)
 
 # directory dei manuali html completi tradotti
 # directory of the html complete manuals translated
 export HTMLlangDIR=$SRCGRASSDIR/dist.i686-pc-linux-gnu/docs/html_$lang
 
 # directory e file .po
 # .po directory and files
 export PODIR=$SRCGRASSDIR/locale/po
 export POFILE=grassmods_$lang.po
 
 # dir. ed elenco dei messaggi(numero di riga della riga msgid del file .po)
 # dir. and messages list (msgid row number of .po file)
 export LSTMSGDIR=$SRCGRASSDIR/locale/desc/temp
 export LSTMSG=$(cat $LSTMSGDIR/lstmsg_$lang)
 
 # manuali html completi tradotti
 # html complete manuals translated
 export HTMLlangFILE=$(grep -l KEYWORD $HTMLlangDIR/*.html | grep -v r.li.html)
 
 export html2man_dir=$SRCGRASSDIR/tools/g.html2man
 export MANDIR=$SRCGRASSDIR/dist.i686-pc-linux-gnu/man
 export MANlangDIR=$MANDIR/$lang
 export FULLFILE=$(ls $HTMLlangDIR | grep html)
 
 
 ########  FUNZIONI  ########
 ########  FUNCTIONS  #######
 
 displayHelp ()
 {
    cat <<'EOF'
 	
    	Tool to facilitate building grass manual pages in your language,
 	including description and headers; the translation of the headers
        	is made by extracting mstr from grassmods_lang.po file
 
 	Usage: ./grassdoclang.sh [-a] | [-t] [-m] [-h]
 
 	Options:
 
 	-a  executes the entire script
 
 	-t  executes only header translation
 
 	-m  only creates the man pages
 
 	-h  display this help and exit

	-c  check for updates and exit
 
 	Note:
 
 	Option -a excludes other options
 
 	If both -t and -m are flagged, either -t and -m options are executed,
         in this order
 
 EOF
 
 }

 checkUpdate ()
 {
 for file in $FILE ; do
   cd $SRCGRASSDIR
   cd  $(find -type d -name $(basename $file .html))
   if [ -f ./description.html ] ; then
    if [[ $(grep -o -E "Last changed.*Date.*\+" description.html) = $(grep -o -E "Last changed.*Date.*\+" $DESCDIR//$lang/$file) ]] ; then
	   echo $file is updated
      else
        echo $file IS NOT UPDATED
   fi
   elif [[ $(grep -o -E "Last changed.*Date.*\+" $file) = $(grep -o -E "Last changed.*Date.*\+" $DESCDIR//$lang/$file) ]] ; then
	   echo $file is updated
      else
        echo $file IS NOT UPDATED
  fi
 done
}
 
 makeList ()
 {
   # crea il file con la lista dei msgid
   # creates the msgid list file
   echo "creating msgid list ..."
   grep -n ^msgid $PODIR/$POFILE > $LSTMSGDIR/lstmsg_$lang
  
   sed -i '
    {
    /\%./ d
    /\.\.\./ d
    /^#/ d
    /\*/ d
    /[Uu]nable to/ d
    /[Cc]annot/ d
    /[Cc]an not/ d
    /Can.t/ d
    /[Cc]ould not/ d
    /[Ff]ailed to/ d
    /[Ee]rror .*in/ d
    /[Nn]o.*found/ d
    /Please/ d
    /[Pp]ermission denied/ d
    s|:msgid.*||
    1 d
   } '  $LSTMSGDIR/lstmsg_$lang
 }
 
 docPrepare ()
 {
   # copia i file tradotti nelle ripettive directory
   #   e li rinomina in description.html
   # copies translated files to respective directories
   #  and renames them description.html
   mkdir $HTMLlangDIR
 
   for file in $FILE
   do
   	cd $SRCGRASSDIR
 	cd  $(find -type d -name $(basename $file .html))
 
 	if [ -f ./description.html ] ; then
 		mv description.html description_en.html
 	       	cp -v ${DESCDIR}/$lang/$file description.html
 	   else
 	     mv $file ${file}_en
 	     cp -v ${DESCDIR}/$lang/$file ./
 	fi
 
 	make clean && make
 
 	if [ -f $HTMLlangDIR/$file ] && $(diff $HTMLlangDIR/$file $HTMLDIR/$file >/dev/null) ; then
             echo " file exists and is the same"
   	  else
 	    cp -v $HTMLDIR/$file $HTMLlangDIR
   	fi
   done
 
   for file in $FILE
   do
 	cd $SRCGRASSDIR
 	cd  $(find -type d -name $(basename $file .html))
 	mv -f -v description_en.html description.html
 	mv -v ${file}_en $file
 	make clean && make
   done
 }
 
 headerTranslator ()
 {
   # traduce i messaggi dal file _lang.po
   # translates messages of _lang.po files
   echo "translating headers ..."
   echo
   for MSG in $LSTMSG
   do
    MSGID=$(
     sed -n '
 	'"$MSG"',/^$/ {
 		/msgid/,/msgstr/ {
 			s|msgid \"||
 			/msgstr/ d
 			s|^\"||g
 			s|\"$||g
 			s|\\"|\"|g
 			s|%.*||g
 			s|\*.*||g
 			s|\.\.\.||
 			s|\\n|<br>|
 			p
 		}
 	} ' $PODIR/$POFILE
    )
 
    MSGSTR=$(
     sed -n '
 	'"$MSG"',/^$/ {
 		/msgstr/,/^$/ {
 			s|msgstr "||
 			s|^\"||g
 			s|\"$||g
 			s|\\"|\"|g
 			s|\%.*||g
 			s|\*.*||g
 			s|\.\.\.||
 			s|\\n|<br>|	
 			/^$/ d
 			p
 		}
 	} ' $PODIR/$POFILE
    )
 
    ID=$(echo $MSGID  | sed -e 's|[]\[\^\$\.\*\/]|\\&|g' )
    TR=$(echo $MSGSTR  | sed -e 's|[]\[\^\$\.\*\/]|\\&|g' )
 
    if echo $MSGSTR | grep -q [a-zA-Z]
    then
      sed -i ' 
      /NAME/,/DESCRIPTION/ {
   	/NAME/,/KEYWORDS/ s@'"$ID"'$@'"$TR"'@
   	/NAME/,/KEYWORDS/ s@'"$ID"'<BR>$@'"$TR"'@
 	/KEYWORDS/,/SYNOPSIS/ s@'"$ID"'$@'"$TR"'@
 	/SYNOPSIS/,/DESCRIPTION/ s@<em>'"$ID"'<\/em>@<em>'"$TR"'<\/em>@g
 	/SYNOPSIS/,/DESCRIPTION/ s@<DD>'"$ID"'<\/DD>@<DD>'"$TR"'<\/DD>@g
   } '  $HTMLlangFILE
    fi
   done
 
   cp -n -v $HTMLDIR/*.png $HTMLlangDIR
   cp -n -v $HTMLDIR/*.css $HTMLlangDIR
   cp -n -v $HTMLDIR/*.txt $HTMLlangDIR
   cp -n -v $HTMLDIR/*.jpg $HTMLlangDIR
 
   echo "headers have been translated"
   echo
 }
 
 makeMan ()
 {
   # crea le pagine man
   # creates the manpages
   echo "creating manpages ..."
   echo
   mkdir $MANDIR/$lang
   mkdir $MANDIR/$lang/man1
  
   for file in $FULLFILE
   do
     echo $file
     perl $html2man_dir/g.html2man $HTMLlangDIR/$file $MANlangDIR/man1/$(basename $file .html).1 1
   done
 }
 
 accent2html ()
 {
   # converte le lettere accentate in entità html
   # converts accents to html entities
   echo "converting accents in the headers to html entities"
   sed -i '
   {
     s|è|\&egrave;|g
     s|é|\&eacute;|g
     s|à|\&agrave;|g
     s|ì|\&igrave;|g
     s|ò|\&ograve;|g
     s|ù|\&ugrave;|g
     s|È|\&Egrave;|g
     s|À|\&Agrave;|g
     s|Ù|\&Ugrave;|g
   } ' $HTMLlangDIR/*.html
 }
 
 html2accent ()
 {
   # converte entità html in lettere accentate
   # converts html entities in accents
   cd $MANlangDIR/man1
 
   for m in $(ls $MANlangDIR/man1)
   do
     iconv -f ISO-8859-1 -t UTF-8 $m > $m.tmp
     mv $m.tmp $m
   done 
  echo
  echo "coding has changed to UTF-8"
  echo

   sed -i '
   {
       s|\&egrave;|è|g
       s|\&eacute;|é|g
       s|\&agrave;|à|g
       s|\&igrave;|ì|g
       s|\&ograve;|ò|g
       s|\&ugrave;|ù|g
       s|\&Egrave;|È|g
       s|\&Agrave;|À|g
       s|\&Ugrave;|Ù|g
     } '  $MANlangDIR/man1/*.1
 }
 
 
 ##########  AZIONI  ###########
 ##########  ACTIONS  ##########
 
 if [[ $display_help == TRUE ]] ; then
   displayHelp
   exit 0
 fi
 
 if [[ $check_update == TRUE ]] ; then
  checkUpdate
  exit 0
 fi

 if [[ $make_all == TRUE && $make_translation == TRUE ]] ; then
   echo " solo -a ..."
   proceed="FALSE"
 fi
 
 if [[ $make_all == TRUE && $make_man == TRUE ]] ; then
   echo " solo -a ..."
   proceed="FALSE"
 fi
 
 # If the proceed flag isn't set, we don't proceed...
 if [[ $proceed == "FALSE" ]]; then
 	echo "Please use repchars -h for usage instructions."
 	echo
 	exit 0;
 fi
 
 if [[$make_all == TRUE ]] ; then
   echo " l'opzione -a esegue tutte le funzioni "
   docPrepare && makeList && headerTranslator && accent2html && makeMan && html2accent
   exit 0
 fi
 
 if [[ $make_translation == TRUE ]] ; then
   echo " -t traduce le intestazioni dei manuali "
   makeList && headerTranslator
 fi
 
 if [[ $make_man == TRUE ]] ; then
   echo " solo -m - create le pagine man "
   accent2html && makeMan && html2accent
 fi
 
 exit 0

######################################################################


How it works

Preparing the grass source

Firstly you have to create a dir /locale/desc in the source tree of grass; inside of this, you have to create some sudirs:

  • /tools: it contains the scripts grassdoclang.sh
  • /$lang: the directories, one per language, containing the translate description.html files
  • /temp : contains the lstmsg_$lang temp file, which is the row numbers list of pofile msgids, generated by grassmklst.sh script

Usage

Just go into /locale/desc/tools and run grassdoclang.sh
./grassdoclang.sh [options]

Usage: ./grassdoclang.sh [-a] | [-t] [-m] [-h] [-c]

Options:
-a executes the entire script
-t executes only header translation
-m only creates the man pages
-h display this help and exit
-c check for updates and exit

Note:
Option -a excludes other options
If both -t and -m are flagged, either -t and -m options are executed, in this order

How the script works

building full manual

  1. creates in dist.i686-pc-linux-gnu/docs directory the /html_$lang directory
  2. renames description.html files as description_en.html
  3. copy the tranlated files in their respective directories and renames them as description.html
  4. rebuilds the directories of the modules
  5. copies complete html files that were generated by make in /html_$lang
  6. moves all back, renaming description_en.html files as description.html

translating headers

attends to automatic translation of the headers, inside the files contained in the /html_$lang directory

  1. generates lstmsg_$lang, which is the row numbers list of the msgids
  2. defines MSGID and MSGSTR variables, which are the strings of original messages and corresponding translation respectively, taken from .po files
  3. searches the msgid strings in headers of the html file and substitute them with the corresponding translation (msgtr string)
  4. finally, copies the not html files (txt, css, png, jpg) into /doc/html_$lang directory

creating the manpages

  1. in the headers, converts html entities to accents
  2. creates the manpages by the grass script g.html2man
  3. converts manpages encoding to UTF-8 code
  4. converts html entities in accents