<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:x="urn:schemas-microsoft-com:office:excel" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman",serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0in;
margin-right:0in;
margin-bottom:0in;
margin-left:.5in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman",serif;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri",sans-serif;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:1359968934;
mso-list-type:hybrid;
mso-list-template-ids:-933486178 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l0:level1
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level2
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level3
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level4
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level5
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level6
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level7
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level8
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level9
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">Dear Colleagues,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">I think the proposed approach of allowing markup convention to be specified in data files could be useful. Moreover, the proposal would provide a mechanism for
formalizing the specification of which items are subject to markup in the first place. Supposedly, that is determined by items’ definitions, but in practice, few, if any, current dictionaries or definitions actually address the topic explicitly.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">Considerations:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">1. To the extent that the proposal envisions data files being enabled to self-specify a particular markup convention from among several choices, it seems to violate
the principle that the meaning of an item should not depend on the value of a different item.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">2. Since the codes for various supported markup conventions would be defined in domain dictionaries, it seems we might be setting ourselves up for future issues
in the event that dictionary maintainers want to support new markup conventions, for then we will need to change existing definitions (which, granted, we have lately afforded ourselves some freedom to do).<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">3. Additionally, the proposal seems to imply that each domain dictionary would need to either specify its own analogue(s) of `_publ.markup_convention`, or else
to explicitly depend on the Core item. I am uncertain whether this is a good or bad thing.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">4. The proposal does not preclude individual items from being defined to have whatever content type is desired for them, as long as the definitions are not flagged
as carrying `Marked-up` data. That’s good, but I can imagine hypothetical cases in which it would be confusing to dictionary authors. For example, if an item were defined to contain HTML markup, it would be necessary for its definition to specify that its
values were NOT `Marked-up`.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">5. Although we call the existing CIF conventions “markup” – and that’s fitting – for the most part they don’t serve the same purpose as Markdown, reStructured
text, etc.. Almost all of our markup is aimed at encoding specific characters, whereas the other markup conventions mentioned are focused on document structure and styling. These are largely orthogonal considerations, so perhaps we should approach them separately.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">6. The discussion accompanying the proposal distinguishes between items that are intended to be machine-actionable and those intended purely for human consumption,
with the assertion that only the latter kind should be subject to markup. I would accept that if it referred to structural markup only, but it is not so clear that such a rule is appropriate for markup that serves to encode characters. Consider, for example,
`_atom_site.label`. As a key data name, it certainly has machine significance, but its values are also meant to identify atoms to humans. Should CIFs, then, be forbidden from using `C</span><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">α`</span><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">
(i.e. `C\a`) as or in atom labels? Forbidding use of markup would prevent literal `C</span><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">α` from being expressed in an atom label in a CIF 1.1 document, but not in a CIF 2.0 document,
so that sets up a pathway wherein markup gets introduced into data values through format transliteration from CIF2 to CIF1. If only the original document were considered valid in such cases, then that would constitute a rather nasty trap to set for ourselves.</span><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">Initial analysis:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">As presented, the proposal’s largest impact would probably be to provide for DDLm dictionaries to specify which items are primarily (or exclusively) intended
for human consumption: those that are defined to have `Marked-up` content, regardless of whether any markup is actually present in their values. Initially, at least, this would establish in which values to interpret the standard CIF markup conventions. That
would be worthwhile.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">I am less certain about the prospects for or usefulness of enabling data files to select alternative markup conventions. Perhaps that could be used to good effect
to support revisions to the markup conventions. Perhaps it would be more broadly applicable. But perhaps we should avoid making any items’ meanings depend on other items’ values.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D">John<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><b><span style="font-size:11.0pt;font-family:"Calibri",sans-serif">From:</span></b><span style="font-size:11.0pt;font-family:"Calibri",sans-serif"> comcifs [mailto:comcifs-bounces@iucr.org]
<b>On Behalf Of </b>James Hester<br>
<b>Sent:</b> Tuesday, September 12, 2017 11:17 PM<br>
<b>To:</b> Discussion list of the IUCr Committee for the Maintenance of the CIF Standard (COMCIFS) <comcifs@iucr.org><br>
<b>Subject:</b> Proposal to regulate markup in CIF files<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt">Dear COMCIFS<o:p></o:p></p>
</div>
<p class="MsoNormal" style="margin-bottom:12.0pt">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.<o:p></o:p></p>
</div>
<p class="MsoNormal">James.<br>
<br>
===============<br clear="all">
<o:p></o:p></p>
<div>
<div>
<div>
<p class="MsoNormal"><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="https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2F2.2.5.3&data=01%7C01%7CJohn.Bollinger%40stjude.org%7Cd89e242461fc4cca53ce08d4fa5e51b9%7C22340fa892264871b677d3b3e377af72%7C0&sdata=K9d03n5YyLsgkcG6xvFJDTSmxV8kRMtapDUqWc4yDMg%3D&reserved=0">
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>
-- <o:p></o:p></p>
<div>
<p class="MsoNormal">T +61 (02) 9717 9907<br>
F +61 (02) 9717 3145<br>
M +61 (04) 0249 4148<o:p></o:p></p>
</div>
</div>
</div>
</div>
</div>
</div>
<br>
<hr>
<font face="Arial" color="Gray" size="2"><br>
Email Disclaimer: www.stjude.org/emaildisclaimer<br>
Consultation Disclaimer: www.stjude.org/consultationdisclaimer<br>
</font>
</body>
</html>