LIBHTML (CCP4: Library)

NAME

libhtml - Subroutine Library for inserting HTML tags into log files

DESCRIPTION

These are Kevin Cowtan's routines (with subsequent modifications by Sheila Peters, Alun Ashton, Martyn Winn and Peter Briggs) for inserting HTML tags into log files so that they can be viewed through a HTML browser. The functionality includes:

Some basic knowledge of HTML tags is assumed, and we recommend those who wish to learn to look at one of the large number of on-line references for HTML which can easily be found through any internet search engine. In particular programmers should be aware that log files which are intended to be viewed as HTML should avoid the use of reserved HTML characters which may confuse the HTML browser.

Overview

These routines provide basic tools for inserting HTML formatting tags into CCP4 log files to enable them to be viewed through a HTML browser. The advantages include the ability to link text within the log file to resources either in the same or in a different document, for example a set of parameters generated by a program and printed to the log file might be linked to a relevant section in the program documentation.

In the subroutine descriptions below, the following terminology is used. link text refers to text which will be visible to read by the person viewing the log file, and which is hyperlinked to other text (either in the same file or in a different one) denoted by the link destination i.e. clicking on the link text will cause the browser to jump to another bit of documentation.

The link destination can be another file, or it can be a point in the current file (in which case the link destination will start with a hash symbol "#").

The calling sequence should start with a call to ccp4h_init, which writes an initial comment to the log file and initialises the internal variables which will be used by the other routines.

A table of contents can be generated with a call to ccp4h_toc_beg to begin the contents list (and write the title "Contents" to the log file). Each entry in the contents list requires a call to ccp4h_toc_ent, which creates a link to other text (if the link destinations are to be in the log file then calls to ccp4h_header will need be made at appropriate points, corresponding to each entry in the contents list). Once all the entries have been written, the contents list must be closed by a call to ccp4h_toc_end.

Graphs can be embedded in the log file so that they are displayed using a java applet (provided that the appropriate Java class files are available to the browser - see Associated files). A call to ccp4h_graph_beg is followed by the table/graph information (in the usual loggraph format) and then closed immediately by a call to ccp4h_graph_end.

Preformatted text can be enclosed by the appropriate tags by calling ccp4h_pre_beg and ccp4h_pre_end immediately before and immediately after respectively the text which is to be displayed in this way. This is useful for any information in which spacing is important, for example graphs generated using ascii characters (but see the notes below).

ccp4h_rule will generate a horizontal line in the html log file. The routines ccp4h_link and ccp4h_link_key are used to create links, and ccp4h_header to create destinations for links within the log file.

The routines ccp4h_summary_beg and ccp4h_summary_end can be used to delimit important output that should be included in a summary log file. These functions can be called whether or not the log file is to be in HTML, and whether or not ccp4h_init has been called. The summary text is bounded by identifying tags in the form of an HTML comment string, and separate tools (e.g. the simple awk script awk '/SUMMARY_BEGIN/,/SUMMARY_END/' | grep -v 'SUMMARY') can be used to extract the summary text. If the log file is in HTML, then the summary text is highlighted in the main file, and the summary file will also be in HTML. Many of the main library routines have calls to the summary routines, so all programs will produce some summary tags, but the summary file will only be meaningful if additional calls are made from the program itself.

Description of Subroutines

The subroutines have been divided into a number of different sections depending on their function:

  1. Initialisation of the html log file
  2. Generating table of contents
  3. Embedding log graphs
  4. General html formatting
  5. End of html log file
  6. Delimiting summary sections

1. Initialisation

ccp4h_init_lib(int ihtml, int isumm) - initialises COMMON block variables

On the first call, this initialises some COMMON block variables. This is called from CCPFYP and MTZINI, so should not need to be called from the program.

	ihtml = (input) -1 : suppress printing of HTML tags
	                 0 : activate HTML tags
        isumm = (input) -1 : suppress printing of summary tags
	                 0 : activate summary tags
	

ccp4h_init() - write initial comment to identify file

This writes an initial <html> tag and a comment to the log file and sets some variables used by the other subroutines. This routine effectively activates the writing of an HTML log file, unless the environment variable CCP_SUPPRESS_HTML (and/or the command line option -nohtml) is set, in which case HTML output is suppressed.

2. Table of contents

ccp4h_toc_beg() - write starting Contents section tags

This is used to start a table of contents, by writing the title "Contents" and then the opening tag <ul> for an unordered list.

ccp4h_toc_ent(char*(*) text, char*(*) dest) - write Contents entry

This is used to write an entry into the contents list. It adds a list item (<li>) and a link to another section.
text = the link text
dest = the link destination
The destination can be added using a call to ccp4h_header later in the program.

ccp4h_toc_end() - write ending Contents section tags

Terminates the contents table by writing the close tag </ul> for the unordered list.

3. Loggraph generation

ccp4h_graph_beg(x,y) - write starting JLogGraph applet tag

Sets up the code for generating a log graph.
x = width of the graph in pixels
y = height of the graph in pixels
These set dimensions of the graph applet as it will appear in the log file when viewed through a browser. If both x and y are zero then they default to 400x300.

ccp4h_graph_end() - write ending JLogGraph applet tag

Closes the tag.

NB: The log-graph generation requires that the files JLogGraph.class and JLogCanvas.class be present in $CBIN. See the section on Associated files for more details.

4. General HTML formatting

4.1. Preformatted text:

ccp4h_pre_beg() - begin preformatted (html <pre> tag)
Marks the start of preformatted text (non-proportional spacing) eg for ascii maps of solvent masks.

ccp4h_pre_end() - end preformatted (html <pre> tag)
Marks the end of preformatted text.

Notes on the use of <pre> tags

Within Netscape (and probably in other html browsers) it is necessary to use a <pre> tag at the head of the log file output. This effectively puts the whole log file inside a single <pre> "environment", and is necessary for carriage returns within the file to be recognised as such. Otherwise, any text not enclosed by header tags is run into a single unformatted "paragraph".

Within this environment the browser should use a fixed-width font, so that ascii tables formatted in the text should have their format preserved (i.e. columns will still line up) when viewed in the browser.

However, there appears to be a bug in <pre> tags within Netscape: the presence of other tags modifies the font, switching it to a proportionally spaced one and thus causing the mis-alignment of ascii tables and other formatted text.

There is no fix for this at present - the workaround is to make a call to ccp4h_pre_beg immediately before the table etc. is to be written out, but then not to close the <pre> environment (i.e. don't call ccp4h_pre_end) until the very end of the logfile.

4.2. Horizontal rule:

ccp4h_rule() - rule (html <hr> tag)
Inserts a horizontal line across the width of the page when viewed through a browser.

4.3. Creating links:

ccp4h_link(char*(*) text, char*(*) dest) - link (html <a> tag)

Creates a link to either another document, or (if the destination starts with the hash symbol "#") to another point in the current log file created using ccp4h_header.
text = the link text
dest = the link destination
If dest is not an anchor name (i.e. doesn't begin with a "#"), then the $CHTML path is prefixed automatically.

ccp4h_link_key(char*(*) text, char*(*) dest) - link to CCP4 documentation

Creates a link to the CCP4 documentation for a program keyword. NB. this routine is for the very specific task of creating links for keywords in the input file to the documentation, and can only be used if keyparser is being used to interpret the keyworded input. For other types of link, use ccp4h_link.
text = the keyparser keyword
dest = the link destination filename and anchor, the $CHTML path is prefixed automatically.
Between call memoparse(.false.) and the main keyparser processing, call this routine with any keywords and links which should be linked to the program documentation. Then call parsefail() to restart syntax checking, e.g:

          call memoparse(.false.)
          call ccp4h_link_key('LABIN   ','fft.html#labin')
          call ccp4h_link_key('GRID    ','fft.html#grid')
          call ccp4h_link_key('FFTSPGRP','fft.html#fftspgrp')
          call parsefail()
        

ccp4h_header(char*(*) text, char*(*) name, int level) - header

Creates an "anchor" in the current log file which can be linked to using ccp4h_link.
text = the link text
name = header name to link to
level = 0 to 6, defines the header size (0 gives plain text).

5. End of html log file

ccp4h_html_close() - write closing </html> tag

This writes the closing </html> tag. It is called by the library routine CCPERR for error levels 0 and 1, which should be the normal route for terminating a program.

6. Delimiting summary sections

These routines insert tags for marking up areas of the logfile to be included in a summary file, unless the environment variable CCP_SUPPRESS_SUMMARY (and/or the command line option -nosummary) is set, in which case summary tag output is suppressed.
ccp4h_summary_beg() - begin summary section

Writes the line <!--SUMMARY_BEGIN--> at the beginning of a summary section. In HTML mode, also writes <B><FONT COLOR="#FF0000">

ccp4h_summary_end() - end summary section

Writes the line <!--SUMMARY_END--> at the beginning of a summary section. In HTML mode, also writes </B></FONT>

Associated files

There are currently three associated files:

JLogGraph.java
Java source code for applets to display the log graphs
JLogGraph.class
Compiled java generated from JLogGraph.java
JLogGraph.class
Compiled java generated from JLogGraph.java

These all reside initially in the $CPROG directory; executing "make install" at installation will cause the executable .class files to be copied to the local $CBIN directory.

Note that since Java is platform independent, there is no need to recompile the .class files for different machines. However, the $CBIN directory must be accessible to the browser in order for any log graphs to be displayed.

Environment variables

CBIN
This is normally set by ccp4.setup and is used here to define the codebase for the applet which uses JLogGraph.class
CHTML
This is normally set by ccp4.setup and is used here to define the location of documents in external links, typically the CCP4 documentation.
CCP_PROGRAM_ID
The contents of the environment variable CCP_PROGRAM_ID are concatenated to the end of each link name. This allows multiple runs of a single program from a script to be combined in one file without the links conflicting, by setting CCP_PROGRAM_ID separately for each run.
CCP_SUPPRESS_HTML
If this is non-blank, output of HTML tags is suppressed. This is for the benefit of devotees of plain text.
CCP_SUPPRESS_SUMMARY
If this is non-blank, output of summary tags is suppressed. This is for the benefit of devotees of plain text.

Note on reserved HTML characters

There are a number of special (or reserved) characters in HTML which will not be displayed the same way in a browser as they would be in ascii format - most importantly for mathematical purposes, the "less than" and "greater than" symbols < and > which are used to delimit html tags. The appearance of these characters in a html log file would confuse the browser and have unpredictable results in terms of what would be visible to the user.

The following characters: <, >, & should be avoided in html log files. Possible solutions are: use plain English, e.g. writing explicitly "greater than", use "psuedo fortran", e.g. .gt. for >, or use the HTML code for these characters:

Symbol HTML code
< &lt;
> &gt;
& &amp;

The HTML codes will be displayed as the appropriate symbol when the log file is viewed in a browser, but will be harder to read if the log file is displayed as pure ascii.