Added Docs/release.sh script for easy creation of tar.gz

This script enables easier release tar.gz files with a consistent
format.
The main functionality is that it will create a folder:
   siesta-releases
in the main folder where it will create a branch at the specified
tag. It will subsequently build the documentation and create
any necessary changes to the code that is necessary before
making the code available publicly.

This script is provided by Nick R. Papior

Docs/branch-changes/documentation

+Full restructure of the TeX documentation method.
+
+This will accommodate a complete environment in TeX for more stringent
+formatting of the documentation.
+This will be a work-in-progress as not all flags are transferred but
+will be eventually.
+
+# Splitting of siesta and tbtrans documentation
+
+The documentation also splits the tbtrans and siesta manual in two.
+This is to accommodate the tbtrans as a stand-alone program (which it
+now is).
+The siesta manual links to the tbtrans manual (if it is in the same folder).
+
+## fdf-options
+The fdf-options should be documented as these examples:
+
+  \begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$>
+  \end{fdfentry}
+
+  \begin{fdflogicalT}{FDF.Name!Logical.Default.True}
+  \end{fdflogicalT}
+
+  \begin{fdflogicalF}{FDF.Name!Logical.Default.False}
+  \end{fdflogicalF}
+
+For instance
+
+  \begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$> 
+
+    Description of the FDF flag.
+  
+  \end{fdfentry}
+
+To make examples of fdf flags, use this enviroment (which is a VERBATIM environment
+in disguise):
+
+   \begin{fdfexample}
+
+   \end{fdfexample}
+
+Similarly for shell examples:
+
+   \begin{shellexample}
+
+   \end{shellexample}
+
+Note that the internals of the commands will automatically convert:
+FDF.Name!SubName into FDF.Name.SubName but will use the ! when adding the
+flag to the index files. One may reference fdf flags in the text via:
+  \fdf{FDF.Name!SubName} which will 1) add the place in the file to the index (for back-referencing),
+and 2) transform the shown text as a link to the block where it is created.
+This will make reading the manual much easier as one may press the flags
+and automatically be moved to the location in the PDF (if the viewer supports it).
+If one does not wish to create a link, one may use the starred variant of the
+\fdf* command.
+
+## Files
+Files in the manual may be referenced using: \file{full-file-name} and/or
+\sysfile{file-ending}, where the latter is a shorthand for \file{<SystemLabel>.file-ending}.
+
+## Manual indices
+The new siesta documentation now splits the index into 3, 1) contains generic
+index entries, 2) all fdf-flags, and 3) the siesta files.
+
+To add specific entries in the regular index, simply use the \index command. To add to the
+fdf index, use \fdfindex. For adding to the file index, use \fileindex.
+
+
+Secondly this branch introduces the release.sh script which enables an
+easy release tarball creation.
+We encourage that it is called with these options:
+  ./Docs/release.sh --prev-tag siesta-3.2 --tag 4.0-release --out siesta-4.0
+To create the release of version 4.0.
+The previous tag is used to generate a CHANGES and CHANGES_DETAILED file
+which contain the entire log of the commit messages.
\ No newline at end of file

Docs/release.sh

+#!/bin/bash
+
+# Script for preparing a release
+# of SIESTA.
+# Script-author:
+#  Nick R. Papior, 2016
+#
+# We encourage the use such as this:
+# To create the 4.0 release, we would advocate performing
+# this command:
+#   ./release.sh --prev-tag siesta-3.2 --tag 4.0-release \
+#      --out siesta-4.0
+# which creates the file:
+#   siesta-releases/siesta-4.0.tar.gz
+# We encourage that the prev-tag is ALWAYS the previous
+# stable release tag.
+# This ensures a consistent changes file shipped with
+# the tar-file.
+# I.e. for the 4.1 release, the command would be:
+#   ./release.sh --prev-tag 4.0-release --tag 4.1-release \
+#      --out siesta-4.1
+
+
+# This may actually not be changed, but is useful
+# throughout.
+main_dir=`bzr root`
+pushd $main_dir
+
+# First we setup the default options
+_reldir=siesta-releases
+
+# Get default tags...
+_prev_tag=`bzr tags --sort=time | tail -2 | head -1 | awk '{print $1}'`
+_tag=`bzr tags --sort=time | tail -1 | awk '{print $1}'`
+# Get default output file (siesta-<>.tar.gz)
+_out=siesta-${_tag//-release/}
+_out=${_out//-rel/}
+_out=${_out//release-/}
+_out=${_out//rel-/}
+
+
+function _has_tag {
+    local tag=$1
+    shift
+    local ret=1
+    for T in `bzr tags | awk '{print $1}'`
+    do
+	if [ "$tag" == "$T" ]; then
+	    ret=0
+	fi
+    done
+    printf "%d" "$ret"
+}
+
+function _help {
+    local ret=$1
+    shift
+
+    echo "$0 creates a release of the SIESTA code at the tip-tag"
+    echo ""
+    echo "These options may be used to control the archive."
+    echo ""
+    echo "  --prev-tag instead of selecting the second-latest tag, choose this tag as the"
+    echo "             reference tag for creating a diff with regards to the --tag tag [bzr tags --sort=time]"
+    echo "  --tag      instead of selecting the latest tag, choose this tag as the"
+    echo "             reference tag for creating a release archive [bzr tags --sort=time]"
+    echo "  --out      the default output file is siesta-<tag>.tar.gz."
+    echo "  --help|-h  show this help."
+    exit $ret
+}
+
+# First we check whether the release-manager has
+# specified the tag that is going to be shipped.
+while [ $# -gt 0 ]; do
+    opt=$1
+    shift
+    case $opt in
+	--tag)
+	    _tag=$1
+	    # Check that the tag exists
+	    if [ $(_has_tag $_tag) -eq 1 ]; then
+		echo "$0 could not find tag: '$_tag' in the tags list."
+		echo "The available tags are:"
+		bzr tags | awk '{print " ",$1}'
+		exit 1
+	    fi
+	    shift
+	    ;;
+	--prev-tag)
+	    _prev_tag=$1
+	    # Check that the tag exists
+	    if [ $(_has_tag $_prev_tag) -eq 1 ]; then
+		echo "$0 could not find tag: '$_prev_tag' in the tags list."
+		echo "The available tags are:"
+		bzr tags | awk '{print " ",$1}'
+		exit 1
+	    fi
+	    shift
+	    ;;
+	
+	--out)
+	    _out=$1
+	    shift
+	    ;;
+	
+	--help|-h)
+	    _help 0
+	    ;;
+	
+    esac
+done
+
+
+# 
+	    
+# The current procedure of releasing a SIESTA
+# version is the following:
+# 0. Create a temporary directory
+# 1. Make the proper documentation
+# 2. Create diff files (both detailed and non-detailed)
+# 3. Go out of the top-directory to create the repository.
+
+
+#   Create a temporary work-directory
+cd ../
+# If the release already exists... Tell the user and quit
+if [ -d $_reldir/$_tag ]; then
+    echo "The release has already been processed."
+    echo "Delete this folder:"
+    echo "  rm -rf $(dirname $main_dir)/$_reldir/$_tag"
+    exit 1
+fi
+bzr branch $main_dir -r $_tag release-manager-$_tag
+mkdir -p $_reldir
+# Move the branch into the directory.
+mv release-manager-$_tag $_reldir/$_tag
+
+# Go into the release directory where all work will be done
+pushd $_reldir
+pushd $_tag
+rel_dir=`bzr root`
+
+
+#   Create documentation
+pushd Docs
+#   First create the screen variants...
+make final-screen
+#   Then the regular documentation (for print)
+make final
+#   Only retain the pdf files
+make clean
+
+#   Go out of the documentation directory...
+popd
+
+# Create the two different CHANGES file
+{
+    echo "##############################################"
+    echo " Changes between $_prev_tag and $_tag"
+    echo "##############################################"
+    echo ""
+    bzr log -r$_prev_tag..$_tag
+} > CHANGES
+{
+    echo "##############################################"
+    echo " Detailed Changes between $_prev_tag and $_tag"
+    echo "##############################################"
+    echo ""
+    bzr log -n 0 -r$_prev_tag..$_tag
+} > CHANGES_DETAILED
+
+
+# Return from the branch release
+popd
+
+# Tar the file
+# In some future cases will the tag and out name
+# be equivalent and we shouldn't delete what we should process!
+if [ $_out != $_tag ]; then
+    rm -rf $_out
+    cp -rf $_tag $_out
+fi
+
+# Create the archive... (without any .bzr files)
+tar --exclude '.bzr*' -czf $_out.tar.gz $_out
+
+if [ $_out != $_tag ]; then
+    rm -rf $_out
+fi
+
+popd

Docs/siesta.tex

@@ -3555,14 +3555,14 @@ several orders of consistency cycles.
   
 \end{fdfentry}
 
-\begin{fdfentry}{SCF.Mix!First}[logical]<true|false> 
+\begin{fdflogicalT}{SCF.Mix!First}
   \index{DM.MixSCF1@\fdf*{DM.MixSCF1}|see SCF.Mix.First}
 
   Whether the first SCF should be mixed or it uses the output as input
   in the next SCF step. It is generally advised to set this to true,
   at least when restarting calculations.
   
-\end{fdfentry}
+\end{fdflogicalT}
 
 
 In the following the density matrix ($\DM$) will be used in the

Docs/tex/index.tex

@@ -32,6 +32,18 @@
     }%
 }
 
+% Create shorthand commands for file-indices
+\NewDocumentCommand\fileindex{ m o }
+{%
+    \IfNoValueTF{#2}{%
+        %\index{#1@\fdf*{#1}}%
+        \sindex[sfiles]{#1}%
+    }{%
+        %\index{#1@\fdf*{#1}#2}%
+        \sindex[sfiles]{#1#2}%
+    }%
+}
+
 
 
 %%% Local Variables:

version.info

-trunk-536-doc-25
+trunk-536-doc-26