How to Baubles: adding markup to logfiles

Put summary tags around sections of logfile that you want highlighted for the user. In baubles, these sections are given prominence when the user views the logfile contents.

To indicate that a section of log should be counted as a summary, put the text:

<!--SUMMARY_BEGIN-->

at the start of the section, and

<!--SUMMARY_END-->

at the end.

There can be as many summary sections as you wish.

Use warning markup to highlight information that you want to draw the user's attention to. Baubles extracts warning messages and prints them before the logfile contents.

If you're using the CCP4 libraries then you can call CCPERR(2,...) (in Fortran) or ccp4error(2,...) (in the C libraries - also callable from C++) which will automatically create a warning message in the correct format.

Otherwise you can generate your own markup using the template:

 $TEXT:Warning: $$ Any text here that you like $$
One or more lines of text about something that
the reader really ought to take note of.
 $$

The parts in bold are those that need to be included; anything in the "Any text here that you like" section is ignored by baubles, and can be left blank; the remaining text will be extracted by baubles and displayed as a warning, e.g.:

Warnings can (and probably should) be enclosed inside summaries, and a logfile can have as many warnings as necessary.

While there is a limit to the number of lines of text (currently around 50 lines) that can be put into a warning and still have it detected by baubles, typically warning messages are one or two lines at most.

Each program can have at most one result section (or none). This is like a "master summary" for the program run.

Marking up the result is similar to the warnings above, the template looks like:

$TEXT:Result: $$ $$
Final Q-factor = 6

Final Z-factor = -12
$$

The text in the result section is extracted by baubles, then processed to and displayed as its own summary outside of the main logfile:

The text in the results section is subjected to a fairly sophisticated processing algorithm which tries to generate nicely-formatted HTML tables from the plain text. The best way to proceed for now is to try it and see what happens (and contact me for more information if it doesn't do what you want).

References use the same markup as warnings and results sections, for example from the current Refmac5 log:

$TEXT:Reference1: $$ comment $$ 
   "Refinement of Macromolecular Structures by the  Maximum-Likelihood Method:"
   G.N. Murshudov, A.A.Vagin and E.J.Dodson,(1997)
   Acta Crystallogr. D53, 240-255
   EU  Validation contract: BIO2CT-92-0524

 $$

In this case baubles collects all the references marked up in this way and prints a summary of references at the head of the log, e.g.:

1. Original logfile and the baubles-processed version of the original logfile

2. Version of the original logfile with additional markup inserted and the baubles-processed version

In the second example the following markup has been added by hand:

• Summary tags have been inserted around the CIS peptide and link warnings, and around the final message warning that the ligand has a minimal description.
• The initial part of the minimal description message has been marked up as a warning

(You can see the differences between the files - you may need to use "View Source" after clicking the above link.)

1. Original logfile and the baubles-processed version of the original logfile

2. Version of the original logfile with additional markup inserted and the baubles-processed version

In the second example the following markup has been added by hand:

• Summary tags have been inserted around the CIS peptide warning, around the bond outliers report, and around the torsion angle outliers report.
• The CIS peptide warning has been marked up as a $TEXT:Warning.
• A block of data at the tail of the logfile concerning bond-angles, bond-distances etc have been marked up as a result section.

(You can see the differences between the files - you may need to use "View Source" after clicking the above link.)

The final baubles-generated file also shows how baubles processes the text in the result section to generate tables, if the data appears to be tabular (as in this case).