#ifndef __TEX_UTILS_H
#define __TEX_UTILS_H
/*-------------------------------------------------------------------------
 * Copyright (c) 2000-2002 Kenneth W. Sodemann (stuffle@charter.net)
 *-------------------------------------------------------------------------
 * $Id: tex_utils.h,v 1.1 2003/03/09 20:59:11 stuffle Exp $
 *
 * 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
 * Free Software Foundation, Inc.
 * 59 Temple Place, Suite 330 
 * Boston, MA  02111-1307  USA
 *-------------------------------------------------------------------------
 */
/*! \file tex_utils.h

  \brief A collection of utilities for creating TeX files out of
         problem reports.

  The functions contained here facilitate the creation of TeX files
  from collections of problem reports.  The actual mechanics of feeding 
  the TeX files to whatever filters will be used to process them is best 
  left to the specific UI implementations.

  \author Kenneth W. Sodemann (stuffle@charter.net)
  $Revision: 1.1 $
  $Date: 2003/03/09 20:59:11 $
*/
#include <glib.h>
#include <libpq-fe.h>

/* 
 * __BEGIN_DECLS should be used at the beginning of your declarations,
 * so that C++ compilers don't mangle their names.  Use __END_DECLS at
 * the end of C declarations. 
 */
#undef __BEGIN_DECLS
#undef __END_DECLS
#ifdef __cplusplus
# define __BEGIN_DECLS extern "C" {
# define __END_DECLS }
#else
# define __BEGIN_DECLS /* empty */
# define __END_DECLS /* empty */
#endif

/* 
 * __P is a macro used to wrap function prototypes, so that compilers
 * that don't understand ANSI C prototypes still work, and ANSI C
 * compilers can issue warnings about type mismatches. 
 */
#undef __P
#if defined (__STDC__) || defined (_AIX) \
        || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
                        || defined(WIN32) || defined(__cplusplus)
# define __P(protos) protos
#else
# define __P(protos) ()
#endif

__BEGIN_DECLS
/*! \fn fix_tex_string (GString *str)

 \brief Fix the string for use with TeX.

 Take the string, and fix it so it will be acceptable to TeX.  Escape
 any characters that need to be escaped in order to print.  Double up
 any '\n' characters.  Make sure the string will print out.

 \param str
 The string that needs to be prepared for output to a TeX file.
*/
void fix_tex_string __P((GString *str));


/*! \fn create_main_sql_str (GList *list)

 \brief Create a SQL string to fetch problem reports to print.
 
 Create a SQL string that will fetch the problem report information for 
 the problem report numbers in the list.  The resulting query will
 work with write_tex_file().

 \param list
 A linked list of problem report numbers for the problem reports to 
 be printed.
 
 \return The SQL string that will fetch the neccessary information for
         the requested problem reports.

 \retval NULL 
 The list is empty.
 \retval non-NULL
 SQL string successfully created.
*/
GString *create_main_sql_str __P((GList *list));


/*! \fn write_tex_audit_trail (FILE *fp, PGconn *conn, gint pk_num)

 \brief Write the audit trail for the current problem report.

 Fetch the audit trail information for the requested problem report.
 Format the information for output to a TeX file.  Output the
 information to the requested file.

 \param fp
 Pointer to the TeX file to output the formatted audit trail to.
 \param conn
 Pointer to the database connection.
 \param pk_num
 The problem report number to fetch the audit trail for.
 
 \retval TRUE
 It worked.
 \retval FALSE 
 Internal error.  Check the syslog for messages, and contact the 
 library maintainer.
*/
gboolean write_tex_audit_trail __P((FILE *fp, PGconn *conn, gint pk_num));


/*! \fn write_tex_file (FILE *fp, PGconn *conn, PGresult *res)

 \brief Take the results of a problem report query, and create a TeX
        file.

 The function works well with the SQL query created by 
 create_main_sql_str().  However, the caller can use any query as
 long as the data in the 'select' clause is in the following order:

 \verbatim
  1. Problem Report Number
  2. Problem Report Title
  3. Problem Report Description
  4. Problem Report Fix Description
  5. Project Name
  6. Submitter Name
  7. Assignee Name (Responsible)
  8. Problem Type Name
  9. Severity Name
 10. Status Name
 \endverbatim

 \param fp
 Pointer to the TeX file to output the formatted audit trail to.
 \param conn
 Pointer to the database connection.
 \param res
 Query results to output.  Make sure the items in the 'select' clause
 are as documented in the description. 

 \retval TRUE
 It worked.
 \retval FALSE 
 Internal error.  Check the syslog for messages, and contact the 
 library maintainer.
*/
gboolean write_tex_file __P((FILE *fp, PGconn *conn, PGresult *res));
__END_DECLS
#endif