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.
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.
The subroutines have been divided into a number of different sections depending on their function:
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
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.
This is used to start a table of contents, by writing the title "Contents" and then the opening tag <ul> for an unordered list.
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.
Terminates the contents table by writing the close tag </ul> for the unordered list.
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.
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.
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.
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.
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()
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).
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.
Writes the line <!--SUMMARY_BEGIN--> at the beginning of a summary section. In HTML mode, also writes <B><FONT COLOR="#FF0000">
Writes the line <!--SUMMARY_END--> at the beginning of a summary section. In HTML mode, also writes </B></FONT>
There are currently three associated files:
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.
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 |
|---|---|
| < | < |
| > | > |
| & | & |
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.