Recent style changes across TDWG make some examples hard to understand

[tucotuco]

One example that brought attention to the Material Sample Task Group is https://dwc.tdwg.org/terms/#dwc:preparations.

What is red currently used to be highlighted, making example boundaries easier to recognize.

[peterdesmet]

Would this be acceptable:

Test CSS: add class example to last tr element, with styling:

.example code {
  padding: 0.2rem 0.4rem;
  background-color: #FCF5F9;
  border-radius: 0.2rem;
  }
  .example code a {
    color: #d63384; /* Make sure that links keep the code color */
  }

[stanblum]

I think that looks ok. Just one question/thought: did you include leading and ending spaces around the example value? It looks that way, but I think the more common writing convention would be not to include the spaces around the value, and use ", " (comma space) as the separator in the list of examples.

On Thu, Apr 20, 2023 at 8:07 AM Peter Desmet @.***> wrote:

Would this be acceptable:

[image: Screenshot 2023-04-20 at 17 06 14] https://user-images.githubusercontent.com/600993/233408276-f39be6c7-1ffa-4c21-af61-4ae5f8386fff.png

— Reply to this email directly, view it on GitHub https://github.com/tdwg/dwc/issues/442#issuecomment-1516499137, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACKZUDPJF7M5K6NW5LNHFATXCFGJXANCNFSM6AAAAAAXENCD3A . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[peterdesmet]

No, there are no leading/ending spaces. The examples are separated by “ , “. I added some natural padding so the highlight color doesn’t stick to the letters. Anyone copying the example would not get spaces around it.

In the longer run, I think every new example should get a new line, but that requires updates in the source csv files.

[cboelling]

every new example should get a new line

I second that.

[baskaufs]

One thing we need to consider is that the metadata expressed here is really just a formatted representation of the authoritative metadata for the terms. We have made an effort to ensure that every user who encounters term metadata about a term from any source sees the same thing. That includes the Quick Reference Guide, the List of Terms document (the reference document included in the standard), and RDF metadata made available in several forms (RDF/XML and Turtle). Thus introducing formatting information in the source CSV files will proliferate into all of these serializations. Embedding newline characters may make reading the examples better in the Quick Reference Guide, but it would be a confusing mess for someone who harvested the data as values of RDF triples and it also is messy for people who edit the CSVs by hand (which they do).

We had a discussion about this kind of thing in the Humboldt Extension Task Group and the conclusion was that when examples get complicated to the level where they can't easily be viewed as a single line of text, they need to be pulled out into a user guide or "recipes" document rather than introducing complexity into the standard term metadata fields.

[peterdesmet]

@baskaufs I agree.

Now, if we were using JSON/XML as our source format, we could just list the examples as an array. In CSV, we're more limited. That said, we can use a more consistent separator for individual examples. We currently use ,, ; and sentences ending in a . to separate examples. Sometimes it's even mixed.

Looking in the source files, ; (semicolon+space) would be a very good candidate to separate examples. Across all versions of DwC is currently used 3 times and only to separate examples (here and here). It's not going to mess up RDF (like \n might) and we don't recommend it as a separator in examples (we use | for that).

Some examples

## Example 1 Currently > `StillImage`, `MovingImage`, `Sound`, `PhysicalObject`, `Event`, `Text` Ideally parsed as > `StillImage` > `MovingImage` >`Sound` > `PhysicalObject` > `Event` > `Text` With ; > `StillImage`; `MovingImage`; `Sound`; `PhysicalObject`; `Event`; `Text` ## Example 2 Currently > `1963-03-08T14:07-0600` (8 Mar 1963 at 2:07pm in the time zone six hours earlier than UTC). `2009-02-20T08:40Z` (20 February 2009 8:40am UTC). `2018-08-29T15:19` (3:19pm local time on 29 August 2018). `1809-02-12` (some time during 12 February 1809). `1906-06` (some time in June 1906). `1971` (some time in the year 1971). `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z` (some time during the interval between 1 March 2007 1pm UTC and 11 May 2008 3:30pm UTC). `1900/1909` (some time during the interval between the beginning of the year 1900 and the end of the year 1909). `2007-11-13/15` (some time in the interval between 13 November 2007 and 15 November 2007). Ideally parsed as > `1963-03-08T14:07-0600` (8 Mar 1963 at 2:07pm in the time zone six hours earlier than UTC) > `2009-02-20T08:40Z` (20 February 2009 8:40am UTC) > `2018-08-29T15:19` (3:19pm local time on 29 August 2018) > `1809-02-12` (some time during 12 February 1809) > `1906-06` (some time in June 1906) > `1971` (some time in the year 1971) > `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z` (some time during the interval between 1 March 2007 1pm UTC and 11 May 2008 3:30pm UTC) > `1900/1909` (some time during the interval between the beginning of the year 1900 and the end of the year 1909) > `2007-11-13/15` (some time in the interval between 13 November 2007 and 15 November 2007) With ; > `1963-03-08T14:07-0600` (8 Mar 1963 at 2:07pm in the time zone six hours earlier than UTC); `2009-02-20T08:40Z` (20 February 2009 8:40am UTC); `2018-08-29T15:19` (3:19pm local time on 29 August 2018); `1809-02-12` (some time during 12 February 1809); `1906-06` (some time in June 1906); `1971` (some time in the year 1971); `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z` (some time during the interval between 1 March 2007 1pm UTC and 11 May 2008 3:30pm UTC); `1900/1909` (some time during the interval between the beginning of the year 1900 and the end of the year 1909); `2007-11-13/15` (some time in the interval between 13 November 2007 and 15 November 2007). ## Example 3 Currently > Occurrence example: `Museum of Vertebrate Zoology, UC Berkeley. MVZ Mammal Collection (Arctos). Record ID: http://arctos.database.museum/guid/MVZ:Mamm:165861?seid=101356. Source: http://ipt.vertnet.org:8080/ipt/resource.do?r=mvz_mammal.` Taxon example: `https://www.gbif.org/species/2439608 Source: GBIF Taxonomic Backbone`, Event example: `Rand, K.M., Logerwell, E.A. The first demersal trawl survey of benthic fish and invertebrates in the Beaufort Sea since the late 1970s. Polar Biol 34, 475–488 (2011). https://doi.org/10.1007/s00300-010-0900-2` Ideally parsed as > Occurrence example: `Museum of Vertebrate Zoology, UC Berkeley. MVZ Mammal Collection (Arctos). Record ID: http://arctos.database.museum/guid/MVZ:Mamm:165861?seid=101356. Source: http://ipt.vertnet.org:8080/ipt/resource.do?r=mvz_mammal.` > Taxon example: `https://www.gbif.org/species/2439608 Source: GBIF Taxonomic Backbone` > Event example: `Rand, K.M., Logerwell, E.A. The first demersal trawl survey of benthic fish and invertebrates in the Beaufort Sea since the late 1970s. Polar Biol 34, 475–488 (2011). https://doi.org/10.1007/s00300-010-0900-2` With ; > Occurrence example: `Museum of Vertebrate Zoology, UC Berkeley. MVZ Mammal Collection (Arctos). Record ID: http://arctos.database.museum/guid/MVZ:Mamm:165861?seid=101356. Source: http://ipt.vertnet.org:8080/ipt/resource.do?r=mvz_mammal.`; Taxon example: `https://www.gbif.org/species/2439608 Source: GBIF Taxonomic Backbone`; Event example: `Rand, K.M., Logerwell, E.A. The first demersal trawl survey of benthic fish and invertebrates in the Beaufort Sea since the late 1970s. Polar Biol 34, 475–488 (2011). https://doi.org/10.1007/s00300-010-0900-2` ## Example 4 Currently > `{"heightInMeters":1.5}`, `{"tragusLengthInMeters":0.014, "weightInGrams":120}`, `{"natureOfID":"expert identification", "identificationEvidence":"cytochrome B sequence"}`, `{"relativeHumidity":28, "airTemperatureInCelsius":22, "sampleSizeInKilograms":10}`, `{"aspectHeading":277, "slopeInDegrees":6}`, `{"iucnStatus":"vulnerable", "taxonDistribution":"Neuquén, Argentina"}` Ideally parsed as > `{"heightInMeters":1.5}` > `{"tragusLengthInMeters":0.014, "weightInGrams":120}` > `{"natureOfID":"expert identification", "identificationEvidence":"cytochrome B sequence"}` > `{"relativeHumidity":28, "airTemperatureInCelsius":22, "sampleSizeInKilograms":10}` > `{"aspectHeading":277, "slopeInDegrees":6}` > `{"iucnStatus":"vulnerable", "taxonDistribution":"Neuquén, Argentina"}` With ; > `{"heightInMeters":1.5}`; `{"tragusLengthInMeters":0.014, "weightInGrams":120}`; `{"natureOfID":"expert identification", "identificationEvidence":"cytochrome B sequence"}`; `{"relativeHumidity":28, "airTemperatureInCelsius":22, "sampleSizeInKilograms":10}`; `{"aspectHeading":277, "slopeInDegrees":6}`; `{"iucnStatus":"vulnerable", "taxonDistribution":"Neuquén, Argentina"}` ## Example 5 Currently > A wolf pack on the shore of Kluane Lake in 1988. A virus in a plant leaf in the New York Botanical Garden at 15:29 on 2014-10-23. A fungus in Central Park in the summer of 1929. Ideally parsed as > A wolf pack on the shore of Kluane Lake in 1988. > A virus in a plant leaf in the New York Botanical Garden at 15:29 on 2014-10-23. > A fungus in Central Park in the summer of 1929. With ; > A wolf pack on the shore of Kluane Lake in 1988.; A virus in a plant leaf in the New York Botanical Garden at 15:29 on 2014-10-23.; A fungus in Central Park in the summer of 1929. ## Example 6 Currently > `https://orcid.org/0000-0002-1825-0097` (for an individual); `https://orcid.org/0000-0002-1825-0097 | https://orcid.org/0000-0002-1825-0098` (for a list of people). Ideally parsed as: > `https://orcid.org/0000-0002-1825-0097` (for an individual) > `https://orcid.org/0000-0002-1825-0097 | https://orcid.org/0000-0002-1825-0098` (for a list of people). With ; > [keep as is, maybe remove . at end]

[tucotuco]

@peterdesmet This solution looks very reasonable to me.

[peterdesmet]

@tucotuco I assume you mean the solution using ;? Which could then result in examples being shown on a new line? Not the intermediate styling fix suggested in my first comment?

[baskaufs]

I like the semicolon solution. If semicolons aren't used anywhere else in the term metadata text, it could be used as a formatting clue (similar to the way that backticks are used to indicate codeblock text) for building web pages while still being understandable in a text-only context. I think it also makes sense from the standpoint of how a semicolon is used in English text, so it would be interpreted correctly by someone who wasn't familiar with our formatting conventions.

[tucotuco]

Yes, I meant the semi-colon (;) as example separator solution.

[peterdesmet]

@tucotuco @baskaufs Would you be willing to change this in the source files? Would this require a version update?

[tucotuco]

I don't think these changes require term version changes. Does that seem right to you @baskaufs ?

[baskaufs]

If it's only styling, I think that is correct.

[peterdesmet]

It's only for styling, term_versions.csv would be updated to make use of ;.

[tucotuco]

I've created a pull request with term_versions.csv changes and the deployment of those using build.py. Hoping it is just this easy.

[baskaufs]

When the current public comment period is over, let's make sure that the semicolons get added to the CSV file in rs.tdwg.org, otherwise this change will probably be overwritten when the changes flow through the pipeline.

[peterdesmet]

The change was implemented in #443. Here's a before and after:

Note: I did not implement the change I suggested earlier and <code> will keep the original styling, making it consistent with other TDWG sites and <code> shown inline with text.