Examples formatting (Proposal one of ???)

[ladylazarus3]

Hi folks,
In followup to our July 29th meeting, this issue is a result of examples formatting work done in collaboration with Iris and Amy T. and is a formal proposal to the editorial group. Obviously, formatting is an area where individual opinions may not fully align and i hope that this proposal will lay some groundwork to come to a compromise and solution that will work for individual preference, DCRM suite precedence, and (most importantly) web accessibility in mind. i'm really grateful to both Amy T. and Iris in this work. As we know, Iris was incredibly involved with the examples team for the RBMS Policy Statements.

This may be the first in a series of proposals. i would like to compile the feedback, close the issue, redeploy examples and revise documentation and then come back again to reach a closer consensus. In so doing, i hope to keep the formatting deliberation process iterative and relevant.

Below are two versions of examples formatting. The "Before" represents examples formatting as they currently stand. They represent a mere starting point for a discussion. The "After" represents those same examples after broader consultation with Iris and Amy T. As background, the how to guidance reminds us that:

"When in doubt on examples formatting, take a look at a previously published DCRM manual for formatting guidance keeping in mind that precedence may have to be slightly modified in a web environment to accommodate accessibility concerns for screen readers, etc. In other words, don't rely on a font or color to solely convey information about the example you are trying to include in the DCRMR text."

The following examples are currently included in the how-to guidance (BEFORE formatting examples)

Example: London : printed for George Eversden, at the Mayden-head in St. Pauls-Church yard, 1657

---

Example: Sadopolis : Chez Justin Valcourt ... à l'enseigne de la Vertumalheureuse, an 0000 [i.e. Brussels : Jules Gay, 1866]

Note on publication statement: Corrected imprint from: Pia, P. Livres de l'Enfer

---

Example: London : publish’d Feby. 27th. 1799 by J. Harris, Sweetings Alley, Cornhill, [February 27, 1799]

(Comment: The date of publication has not been transposed because it is a grammatically inseparable element)

---

This formatting to approximates the examples after consultation with Iris and Amy T. (AFTER formatting examples):

Example:
London : printed for George Eversden, at the Mayden-head in St. Pauls-Church yard, 1657

---

Example: Sadopolis : Chez Justin Valcourt ... à l'enseigne de la Vertumalheureuse, an 0000 [i.e. Brussels : Jules Gay, 1866] Note on publication statement: Corrected imprint from: Pia, P. Livres de l'Enfer

---

Example:
London : publish’d Feby. 27th. 1799 by J. Harris, Sweetings Alley, Cornhill, [February 27, 1799]
(Comment: The date of publication has not been transposed because it is a grammatically inseparable element)

---

To see these formatted examples in further DCRMR context, the current deployment of the Date of publication has all the examples formatted according to the "AFTER" examples formatting guidance developed with Iris and Amy T. Slight differences may be due to the CSS of the DCRMR web page. The CSS can also be modified, and i've tweaked it significantly to get us this far. The CSS can be tweaked again.

i'm adding a list of my own PROS, CONS, and FURTHER IMPROVEMENTS(?) below.

PROS:

• the comments, notes and elements are closer together, but still give an appropriate amount of white space for the eye to rest. A reader can easily tell where one example starts and another begins.
• the word "example" on a different line helps set up what is to follow with white space

CONS:

• the use of different levels of indentation in block-quotes automatically adds a "hard line-break", therefore, we can't approximate the various levels of indentation of examples, notes, and comments.

FURTHER IMPROVEMENTS(?):

• we could potentially convey further meaning and teach names of elements by using them within the examples themselves. This would particularly help when examples are repeated in an entity and note instructions on various pages. This is shown below:

Example:
Publication statement: London : printed for George Eversden, at the Mayden-head in St. Pauls-Church yard, 1657

---

Example: Publication statement: Sadopolis : Chez Justin Valcourt ... à l'enseigne de la Vertumalheureuse, an 0000 [i.e. Brussels : Jules Gay, 1866] Note on publication statement: Corrected imprint from: Pia, P. Livres de l'Enfer

---

Example:
Publication statement: London : publish’d Feby. 27th. 1799 by J. Harris, Sweetings Alley, Cornhill, [February 27, 1799]
(Comment: The date of publication has not been transposed because it is a grammatically inseparable element)

---

Thank you very much in advance for your own Pros, Cons, and suggestions for further improvements on examples formatting. i'm hoping with a broader discussion among the editorial members, that we can find something that everyone is (almost) happy with and still conforms to the needs of a web environment. Thanks for your time,

kalan

[flapka]

I appreciate the explorations and improvements suggested here. My two cents:

1. I like when the formatting conveys example blocks, and your "after" formatting moves in that direction. I'd be happier still if the blocks included a little more indentation and a variant background tone. (Do subtle background tones, with high contrast -- as in this Wikipedia example -- meet accessibility guidelines?) If a background tone is undesirable, could we have that bar at left of the type that appears in kalan's message above?

2. I like it when the words of the examples proper -- the Courier New bits -- have greater weight than the word "Example" and the element names. Right now it's the other way around.

3. If, within examples, element names are formatted in an unobtrusive manner, I'd support either:

• display all element names whenever an example shows more than one element (preference); or
• display element names in all contexts

[elizhobart]

Thanks, kalan! I especially like the reduced white space to bring the pieces of text closer together. Like Francis, I'd like to see more indentation to better visually set these blocks apart. I personally would prefer not to display the element names in all contexts. In most cases, it will be clear and this would add many additional words. My preference would be to display element names when an example shows more than one element.

[mjmascaro]

Thanks, kalan. I too like the reduced white space. Like Francis, I would prefer the example text to have more visual weight than the element label and comment. A little more indentation would be nice (but if it comes down to increase indentation would increase white space between lines, I prefer the sacrificing the indentation.)

As to displaying elements, I have the same preference as Elizabeth of displaying them in examples that show more than one element and not otherwise.

[ladylazarus3]

@flapka @mjmascaro @elizhobart: Thank you all so much for your generous comments. i have made some changes to the formatting incorporating the following changes based on your feedback and would ask you to comment once again to make sure the changes reflect what you had in mind and give an opportunity to make further comments:

1. i added a light grey background tone to the example blocks. We are using the "contrast" skin for the Minimal Mistakes Jekyll theme and this light grey is included in that accessibility-designed theme. We can even make it lighter if wanted.
2. i have increased the weight of the Courier font so it is heavier than the serif font labels.
3. i have added element names to all examples containing more than one element.

Further questions based off the current deployment and formatting of the Date of publication. Also as a reminder, you may have to do a Ctrl+F5 to dump your cached version of the webpage before seeing all the changes (i did):

Q1. Do we still need the horizontal rules to separate examples now that they have their own colored blocks? (see 4.205.4.7 vs. the examples in 4.205.4.6). i feel like horizontal rules are no longer necessary now that the example block is on a light grey background.

Q2. Do we want the word "Example:" contained within the colored block or just above it? (see 4.205.5.1). N.B. that hard break adds a LOT of white space and we can't really tweak that without tweaking it everywhere. Personally, i like "Example" contained within the block. We could further play with indentation and spacing (see 4.205.4.2).

Q3. Do we still like the comment caption to show in italics, e.g. (Comment: blah blah blah)? Or that just waaaay too much fonty goodness for one block to handle? (see 4.205.4.3).

[io-uk]

Thanks very much, Kalan, for incorporating the changes and giving us further options to choose from. I don't think we need the horizontal rules if we have the background tone. Would it be possible to make the Courier font a size bigger rather than just heavier? I am not sure the further indentation in 4.205.4.2 quite works because it seems to add this white box, which looks a bit odd. I think I would keep the comment caption to show in italics as then you realise straight away that this is something different and it doesn't just refer to another element in the record.

[jess-grz]

@ladylazarus3 This looks beautiful. Thanks for taking the time to work through a number of scenarios and refining as needed. I agree that:

• we only need to display element names in examples if there is more than one element

• "Example:" works better contained within the block

• we no longer need the horizontal rules

• the Courier font would be more readable a size bigger

• "Comment:" reads better in italics.

[ladylazarus3]

@jess-grz Thank you for the additional feedback and i really appreciate the beautiful comment. :)

i have added element names where there is more than one element, i have placed "Example:" back in the block, i have removed the horizontal rules, the font is a size bigger, and left "Comment:" in italics. Again, you can see the changes on Date of publication.

We can certainly change the Examples font to Helvetica (per Francis' recent comment in issue #54. If we want to try it on for size. :) i just want everyone happy with the examples and get a consensus so i can go back and make everything consistent.

Thanks for your continued discussion and interest in this GitHub issue, i really, really appreciate everyone's input.

kalan

[mjmascaro]

Another situation where we may wish to include the element name in the examples. When the example is for an element that is the not the rule instruction. This came up in the instructions for edition statements that are grammatically inseparable part of other transcribed elements. (https://docs.google.com/document/d/1fpj-4fm49I21_VZy9wdAofmHv5ebvXUVgW5YNaVTLwc/edit#bookmark=id.r6oows9t9w6a) In this case the examples are edition info being transcribed as part of the title proper or other elements.

[io-uk]

Thank you very much, Kalan, for your ongoing work on this. I think this slightly bigger font size works well. Francis's suggestion might work well, too. Could we try it without the bold emphasis?

[ladylazarus3]

Thank you both @mjmascaro and @io-uk for this continued discussion on examples formatting. It is super appreciated and i agree with the point about element labels and rule instructions.

i've deployed the sans serif, normal-weight Helvetica font, and folks can see the changes here.

Any other thoughts or tweaks on examples formatting? i'm happy to do it-- better to do it now than later. Thanks again sincerely for all the input, folks. kalan

[deborahjleslie]

Not sure whether to make this comment here or on https://github.com/rbms-bsc/DCRMR/issues/54 -- should they be merged or redirected?

The font used in example boxes should be comparable in size and weight to that used in instructions. Not necessarily the same, but within the same range.

Devoting a whole line to the word "Example:" within the example box takes up too much real estate. Their placement and content along with the distinctive visual parameters you've established are enough to identify them.

[ladylazarus3]

Hi there, i adjusted the comparable size and weight of the font used in the instructions and took out the "Example:" line while incorporating the feedback on the Fonts Github issue as well. the most recent example screen cap are on #54.

Happy to make more adjustments and tweaks and very grateful for the continued discussion. kalan

[ladylazarus3]

Hey there, Somewhat related to the fonts thread in #54. Is there group consensus about sources in examples?

i'm working on a different branch today, please don't let the fonts be a distraction.
kalan

[elizhobart]

I'd say put the word "source" in the same font as everything in the left column. The source citation I think may be better in a slightly large size, but maybe italicize to make it clear that it's not part of the example?

[ladylazarus3]

Hi @elizhobart ,

Thanks! here is the updated screenshot. i put "source" in the small capitals. In order to get the small capitals effect using blockquotes, i really had to make the blockquote font smaller while keeping the <CITE> </CITE> font larger.

We can play around with the side of the small capitals to get the balance right, or we can format the source in the <CITE> </CITE> font.

i've included the css in the screencaps so folks can get an idea of what is going on behind the scenes.

kalan

[mjmascaro]

I have a broader question about whether to include the source of the examples in the final text or not. In the RBMS PS drafts, the sources were tracked in the comments for internal editorial purposes (particularly the hopes of being able to link to images of title pages.) I can certainly see the value of publishing the sources, but do have some reservations about linking to individual OCLC numbers, since the linked records may or may not fully conform to DCRMR.

[ladylazarus3]

@mjmascaro, yes, in full transparency, this was my not-so-sneaky way of pushing the conversation in this direction. :)

[flapka]

I agree that we shouldn't link to anything external because the external resource is not static; it may be revised so that it no longer illustrates our example.

By contrast, I'd be content with linking to an "Examples to accompany ..." resource that conformed with DCRMR.

[elizhobart]

I definitely agree that we won't want to link to anything external and hesitate to add OCLC numbers, for the reason Michelle mentioned. I'm personally content to leave sources out of DCRMR itself but track internally.

Linking to an eventual "Examples to accompany" sounds like a great idea. It may be a while yet before that resource exists, however.

[ladylazarus3]

This last comment sparked a thought. Once way to share our example sources might be to add bibliographic citations for examples to a DCRMR bibliography or works cited page (see pg 203 of DCRM(B) pdf between glossary and index). i don't know if adding example sources would be part of the Minimal Viable Product (MVP), but it seems like this would: a) keep links to external sources in one single spot for easier maintenance (this thought makes me ecstatically happy) b) give DCRMR users that really, really want to do a little extra digging a reliable trail of breadcrumbs c) expedite a compilation of citations prior to a future "examples to accompany" release d) save valuable real estate on the various "Entity pages" themselves

[rarebkcat]

Hey, y'all--

Right now, Examples are being formatted as a table, following the conversation in #54 , and I strongly believe that's not the appropriate solution to a formatting question for a few reasons.

1. The content isn't appropriate to the use of a table. the W3C Accessibility Tutorials / Tables / Tables Concepts states:

   Data tables are used to organize data with a logical relationship in grids. Accessible tables need HTML markup that indicates header cells and data cells and defines their relationship. Assistive technologies use this information to provide context to users.

This isn't data organized in a grid; this is marked up text. The formatting carries meaning for people interacting with the text visually, but the text itself carries meaning for people interacting with the text as text. The text ought to be marked up appropriately for the kind of meaning it's conveying.

2. It doesn't work on a small screen. I'm currently using a Surface as my main device, and the "Example" "Comment" "ElementName" text gets rather small. (And, yes, I have looked up cataloging rules on my phone, my iPad, and the Surface on the fly in the stacks or someone else's office or when out and about before. It seems odd, I know, but it does happen.)

3. Table formatting is fiddly and kind of obnoxious to implement. In same cases we can't avoid it, because we do have tables, but I don't think it should be introduced for information that isn't tabular in nature.

I know we all care deeply about DCRMR and what it's going to look like. Many, many, many hours have gone into it, and we want it to be as polished as possible. However, I would like to advocate for keeping things, especially re: formatting, relatively simple for now. We need an accessibility review, but that's going to be further down the line. Additionally, public review is inevitably going to kick up a lot of things we never considered.

The less complicated and involved things are, the easier it is to standardize them now (there's going to be a lot of hand-coding and hand-reading to do this) and to change them later, especially if it involves hard mark-up, like putting things into tables, instead of or alongside CSS tweaks. I think questions like whether we include Source citations are substantive and a question that needs answering, but I think we need to be cautious about getting too into the details on formatting at this juncture, beyond gaining consistency in content and consistency in mark-up.

-Amy

[mjmascaro]

Amy brings up some good points regarding table formatting and needing to step back a bit before getting too into the detail on formatting, which I agree with.

Circling back to the question of source citations for examples. How to best keep track of the source of examples long term has been concern in the back of my mind, especially as GitHub evolves into the text of record over the Google Docs. For that reason, kalan's idea of a centralized work cited page appeals to me. Though, I do not have a full understand of how complex that would be to implement at this point.

[elizhobart]

I think we've gotten a little too in the weeds on formatting. For now, our goal should chiefly be to get formatting clear and consistent. As Amy notes, public review will generate a lot of feedback on both content and appearance. We should avoid getting too wedded to any particular appearance right now, as everything is subject to change.

That said, I am going to ask that we nix tables for examples. As Amy notes, tables raise significant issues for accessibility and will be harder to undo in the long run.

For examples formatting, I would suggest beginning with the word "Example," indenting, using Courier and size as discussed, and using a background color. In the vast majority of cases, "Example: text" will be all we need. We can label additional lines as needed.

I do like the idea of having a page for sources, but planning and building this page will take more time. I think this might be a good longer term goal, but not a goal for the MVP release.

[deborahjleslie]

My understanding is that the example sources were for the benefit of DCRMR editors. I agree that they should not be in the text.

[rarebkcat]

For the sake of consistency, I propose we encode examples as follows:

>Example:
><CITE>Example text here</CITE>

When there are multiple elements and comments:

>Example:
>ElementName1: <CITE>Element text here</CITE>
>ElementName2: <CITE>Element text here</CITE>
>(*Comment*: Comment text here.)
>(*Source of information reads*: something something something.)

The leading "example" makes sure that the text itself, not just the formatting, tells readers what this is. The use of the > tells the computer to block quote the text (providing the contrasting color background). By wrapping the example text in the <CITE>, the formatting of the text in between the CITE tags can be manipulated via the CSS; kalan's currently set the font in the CITE tags to Courier. The asterisks puts "comment" or "source of information reads" in italics. The parenthesis and italics are consistent with DCRM(B); additionally, it's currently the prevalent form, making it relatively easier to pull things into alignment.

(Later, we can add or subtract the italics via a Find/Replace all. We can't do that with the parentheses, but since it's the prevalent form and it's commentary, I think it's okay.)

(Fun fact: a peculiar thing about working in the blocks of text marked by the > is you need to put two spaces at the end of each line to have a line break. So, when typing, it's

>Example: SPACE SPACE
>ElementName1: <CITE>Element text here</CITE> SPACE SPACE
>ElementName2: <CITE>Element text here</CITE> SPACE SPACE
>(*Comment*: Comment text here.) SPACE SPACE
>(*Source of information reads*: something something something.) SPACE SPACE

If you just hit enter, it doesn't insert the line break. Ask us how we know. XD)

[elizhobart]

This looks good to me, @rarebkcat. Since this discussion has run quite long now and we'll need a path forward for our keepers to proceed, let's format examples this way. I'd also like to continue to have the entire example block indented, since that will be visually familiar to users from DCRM(B). @ladylazarus3, can you move forward with this as is, or do you need any further decisions from us?

[rarebkcat]

The use of the > at the beginning of the line also makes the indentation -- basically, we're encoding it as a blockquote, and the indentation is part of how that displays.

[elizhobart]

Thanks, @rarebkcat! My knowledge of Markdown is still very much in the research and development phase...

[ladylazarus3]

Hi folks, Yup @rarebkcat has it. the " > " for block quotes adds the indentation to the display. Amy's suggestions above reflect an approach that is practical for keepers to implement. We can add Amy's examples guidance to the official DCRMR Wiki documentation and proceed with retrospectively ensuring examples compliance although most examples should be fairly close (i've already reformatted maaany of them).

With that, do folks feel like we can close this issue for now? thanks again so much to all for contributions and for the discussion. kalan

[elizhobart]

Thanks to both @ladylazarus3 and @rarebkcat for your work on this! Yes, I think we're ready to close this issue.