cgal/Manual_tools/scripts/generate_reference_manual/generate_reference_manual

#!/bin/bash

# Goal   : Generate automatically (most of) the Reference Manual of a CGAL package
# Author : Laurent Saboret, INRIA, 2005-2008
# ------------------------------------------

# Print usage and quit
usage ()
{
    echo ""

    # Catenate read-me file generate_reference_manual_readme.txt
    README="$0_readme.txt"
    if [[ ! (-f "${README}") ]]; then
        echo "ERROR: file ${README} does not exist"
    else
        cat "${README}"
    fi

    exit 1
}


#######
# Main
#######

# Turn traces on
# set -x

# Version
echo "generate_reference_manual version 1.0.3."

# Global variables
PACKAGE_ROOT_FOLDER="" # Package's root folder
COPY_DOXYGEN_LATEX_DOC_ARGS="" # Parameters for copy_doxygen_latex_doc
INCLUDE_PATH="" # Path to CGAL include folder
PACKAGE=""  # Package name (without path)
DOXYFILE="" # doxygen configuration file
DEBUG=0 # Debug mode?
VERBOSE=0 # Verbose mode?

# Decode parameters
while [ "${1}" ]
do
    case "${1}" in
    -h|--help) # If usage
        usage
        ;;
    -f|--force) # Ignore obsolete option --force
        ;;
    -d|--debug) # If --debug
        DEBUG=1
        COPY_DOXYGEN_LATEX_DOC_ARGS="${COPY_DOXYGEN_LATEX_DOC_ARGS} ${1}"
        ;;
    -v|--verbose) # If --verbose
        VERBOSE=1
        COPY_DOXYGEN_LATEX_DOC_ARGS="${COPY_DOXYGEN_LATEX_DOC_ARGS} ${1}"
        ;;
    -I|--include) # If -I
        shift
        if [ ! "${1}" ]; then # If no argument after -I
            usage
        fi
        INCLUDE_PATH="${INCLUDE_PATH} ${1}"
        ;;
    -*) # If unknown parameter
        usage
        ;;
    * ) # Else: package's root folder
        PACKAGE_ROOT_FOLDER="${1}"
        ;;
    esac
    shift
done

# Check parameters
if [[ ! "${PACKAGE_ROOT_FOLDER}" || ! "${INCLUDE_PATH}" ]]; then
    usage
fi

# Test if doxygen is installed
which doxygen >/dev/null 2>&1
if [[ $? != 0 ]]; then
    echo "ERROR: cannot find doxygen"
    exit 1
fi

# Test if doxygen configuration file generate_reference_manual_Doxyfile is present
DOXYFILE="$0_Doxyfile"
if [[ ! (-f "${DOXYFILE}") ]]; then
    echo "ERROR: file ${DOXYFILE} does not exist"
    exit 1
fi

# Test if copy_doxygen_latex_doc is installed
which copy_doxygen_latex_doc >/dev/null 2>&1
if [[ $? != 0 ]]; then
    echo "ERROR: cannot find copy_doxygen_latex_doc"
    exit 1
fi

# Goto package's root folder
if [[ -d "${PACKAGE_ROOT_FOLDER}" ]]; then
    cd "${PACKAGE_ROOT_FOLDER}"
else
    echo "ERROR: folder ${PACKAGE_ROOT_FOLDER} does not exist"
    exit 1
fi

# Get package name
PACKAGE=`pwd | sed 's/.*\///'`

# Delete the output of previous uses of generate_reference_manual
rm -rf doc_doxygen
mkdir doc_doxygen

# Run doxygen. m4 is used to search and replace in template Doxyfile.
echo ""
echo "Run doxygen..."
if [[ $VERBOSE == 0 ]]; then
    WARN_IF_DOC_ERROR="NO"
else
    WARN_IF_DOC_ERROR="YES"
fi
m4 -DCGAL_PACKAGE="${PACKAGE}" \
   -DCGAL_WARN_IF_DOC_ERROR="${WARN_IF_DOC_ERROR}" \
   -DCGAL_INCLUDE_PATH="${INCLUDE_PATH}" \
   "${DOXYFILE}" > generate_reference_manual_Doxyfile
doxygen generate_reference_manual_Doxyfile 2>&1 | egrep -v 'BoundingBox not found'
if [[ $DEBUG == 0 ]]; then
    rm -f generate_reference_manual_Doxyfile
fi

# Update the Reference Manual
echo ""
echo "Update the Reference Manual..."
for cgal_doc in doc_tex/*_ref/*.tex
do
    # Skip main.tex and intro.tex
    if [[ (`basename "${cgal_doc}"` != "main.tex") && \
          (`basename "${cgal_doc}"` != "intro.tex") ]];
    then
        # Get the list of classes/structs/functions... documented in "${cgal_doc}"
        items=`cat ${cgal_doc} | perl -p -e 's/[ \t]//g' | egrep '^[^%]*\\\\begin\{ccRef' | \
            perl -p -e 's/^[^%]*\\\\begin\{ccRef.*?\}(.*?)\{(.*?)[<}].*/$1$2/g'`

        for item in $items
        do
            # Extract scope of ${item} indicated in ${cgal_doc}.
            # It may be either a namespace or a class name.
            scope=`echo $item | perl -e 'while (<>) {if (m/\[(.*?)\]/) {print "$1\n";}}'`
            item=`echo $item | perl -p -e 's/^\[.*?\]//'` # remove namespace

            # Find the file containing the doxygen-generated documentation.
            # We search in CGAL namespace and in the global scope (e.g. for concepts).
            doxygen_doc=""
            for namespace in "$scope" "CGAL::$scope" "CGAL::" ""
            do
                # Mangled item and namespace names in individual doxygen output files
                item_base_file_name=`echo "${item}" | sed 's/_/__/g'`
                namespace_base_file_name=`echo "${namespace}" | sed 's/_/__/g' | sed 's/:/_1/g'`

                # Name of doxygen output file containing the global functions of the namespace
                namespace_tex_file="namespace`echo "${namespace}" | sed 's/::$//' | sed 's/:/_1/g'`.tex"

                # Item name in Doxygen output file (mangled for latex)
                item_latex_name=`echo "${item}" | sed 's/_/\\\\\\\\_\\\\\\\\-/g'`

                # Test if ${item} is a class or a class concept
                [ ! -f "${doxygen_doc}" ] && \
                    doxygen_doc="doc_doxygen/latex/class${namespace_base_file_name}${item_base_file_name}.tex"
                # Test if ${item} is a struct or a struct concept
                [ ! -f "${doxygen_doc}" ] && \
                    doxygen_doc="doc_doxygen/latex/struct${namespace_base_file_name}${item_base_file_name}.tex"

                # Test if ${item} is a function in the global scope
                [ ! -f "${doxygen_doc}" ] && \
                    doxygen_doc=`grep -l -P '\\\\paragraph\\{.*\\b'${item_latex_name}'\\s*\\(' \
                                 "doc_doxygen/latex/${item_base_file_name}_8h.tex" 2>/dev/null`
                # Test if ${item} is a function in a namespace
                [ ! -f "${doxygen_doc}" ] && \
                    doxygen_doc=`grep -l -P '\\\\paragraph\\{.*\\b'${item_latex_name}'\\s*\\(' \
                                 "doc_doxygen/latex/${namespace_tex_file}" 2>/dev/null`
            done

            # Insert the doxygen-generated documentation into ${cgal_doc}
            if [[ -f "${doxygen_doc}" ]]; then
                if [[ $DEBUG == 0 ]]; then
                    echo "* ${item}"
                else
                    echo copy_doxygen_latex_doc ${COPY_DOXYGEN_LATEX_DOC_ARGS} "${item}" "`pwd`/${doxygen_doc}" "`pwd`/${cgal_doc}"
                fi
                copy_doxygen_latex_doc ${COPY_DOXYGEN_LATEX_DOC_ARGS} "${item}" "${doxygen_doc}" "${cgal_doc}"
            else
                echo "ERROR: cannot find doxygen documentation for ${scope}${item} (documented in ${cgal_doc})"
            fi
        done
    fi
done

# Update citations (hard-coded).
# TODO: add here citations for all packages using generate_reference_manual.
perl -pi -e 's/\[(GHJV95|GOF95)\]/\\cite{cgal:ghjv-dpero-95}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[FH05\]/\\cite{cgal:fh-survey-05}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[Flo03\]/\\cite{cgal:f-mvc-03}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[DMA02\]/\\cite{cgal:dma-ipsm-02}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[LPRM02\]/\\cite{cgal:lprm-lscm-02}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[Tut63\]/\\cite{t-hdg-63}/s' doc_tex/*_ref/*.tex
perl -pi -e 's/\[EDD\+95\]/\\cite{cgal:eddhls-maam-95}/s' doc_tex/*_ref/*.tex

exit 0