<div dir="ltr"><div><div>Dear COMCIFS<br><br></div>Please see below a draft proposal for dealing with markup in CIF files. Let me know if you agree with the general approach, or suggest better alternatives. Once our general direction is agreed, our COMCIFS subcommittees will go into a huddle and sort out the definitions.<br><br></div>James.<br><br>===============<br clear="all"><div><div><div><br><br>Proposal for regulating markup of CIF text items<br>================================================<br><br>Summary<br>=======<br><br>Data names whose values can be marked-up are given a new type. In<br>consultation with heavy users of markup, a limited set of markup<br>systems (ideally just one) is documented in the CIF core dictionary.<br><br>Introduction<br>============<br><br>From the very first publication describing CIF, markup conventions<br>have been provided in order to extend the range of characters and font<br>effects representable in ASCII. Which data values these conventions<br>might apply to, and whether or not this is more properly a CIF syntax<br>or dictionary (semantic) issue, has been left implicit.<br><br>Marked-up text according to the ad-hoc definitions described in Vol G<br>appears both in CIF data files and in dictionary definitions. While<br>COMCIFS has control over the conventions applying within dictionaries,<br>it has far less control over data values in data files, which are<br>produced both by dedicated software, such as publCIF, and hand-editing<br>or local ad-hoc solutions. Marked-up text in data files plays an<br>important role in the publication workflow.<br><br>Vol G (First Edition) notes in section <a href="http://2.2.5.3">2.2.5.3</a>: "It is hoped that in<br>future different types of such markup may be permitted so long as the<br>data values affected can be tagged with an indication of their content<br>type that allows the appropriate content handlers to be invoked". This<br>document attempts to clean up this outstanding piece of CIF<br>housekeeping, in part by rejecting the premise that multiple markup<br>approaches are desirable.<br><br>Syntax or semantics<br>===================<br><br>The markup conventions have traditionally been presented together with<br>the CIF syntax standard, as a "common semantic feature". However, upon<br>consideration of CIF-JSON and CIF embedded in HDF5, it is clear that<br>the syntax itself does not determine how a particular text string<br>should be marked up: a text string transferred to either of those<br>formats remains identical, with identical meaning as defined in the<br>appropriate dictionary; there is no reason that markup should be any<br>different.<br><br>Therefore, markup conventions should be described either in the<br>relevant DDLm dictionary or in the DDLm attribute definitions. Use of<br>the DDLm attribute dictionary to define markup conventions is too<br>rigid, as DDLm could, in principle, be used in a context completely<br>divorced from crystallography that may well have its own preferred<br>markup. This leaves the dictionary as the appropriate place to define<br>the markup convention.<br><br>I propose we proceed as follows:<br><br>(1) We add a new enumerated value to `_type.contents`<br> e.g. 'Marked-up'. Data names with this type may be marked up.<br>(2) We add a new data name to the core dictionary<br> e.g. `_publ.markup_convention`. The markup convention indicated by<br> this data name applies to all data values of type 'Marked-up'.<br>(3) We provide the `_publ.markup_convention` data name with one or<br> more enumerated values each corresponding to a particular markup<br> convention that may be in operation in a data block<br>(4) We aim to restrict markup options to a single (default) value<br> corresponding to the current markup system. Any expansion or<br> alteration should be carried out in consultation with heavy users<br> of the markup.<br><br>Comments<br>========<br><br>1. It is generally undesirable to allow multiple markup<br> systems. Publication workflows are generally complex, and having to<br> support multiple source text forms would place an undue and<br> unnecessary burden on heavy users of CIF text markup like the IUCr<br> journals. The presence of a dedicated data name does, however,<br> allow proponents of alternative markup conventions to make their<br> case.<br><br>2. Markup is purely for human consumption. In particular, enumerated<br> values must be excluded, and no machine-actionable content should<br> be encoded in marked-up text.<br><br>3. With the agreement of heavy consumers of CIF marked-up text, we may<br> explore expanding the scope of the current convention to include<br> elements such as footnotes.<br><br>4. Since 1993, when the lightweight CIF markup was proposed, a number<br> of lightweight ASCII text markup systems have been developed. These<br> include reStructured text, Markdown and ASCIIDoc. While it might be<br> worthwhile transitioning to one of these in order to use the more<br> comprehensive formatting that would be available, the backslash<br> notation currently used is likely to cause conflict.<br><br><br>-- <br><div class="gmail_signature">T +61 (02) 9717 9907<br>F +61 (02) 9717 3145<br>M +61 (04) 0249 4148</div>
</div></div></div></div>