LIBHTML (CCP4: Library)
NAMElibhtml - Subroutine Library for inserting HTML tags into log files
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) donoted 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 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 funtion:
2. Table of contents
3. Loggraph generation
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:
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:
4.3. Creating links:
5. End of html log file
6. Delimiting summary sectionsThese 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.
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.
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:
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.