Elisa Beshero-Bondar
@epyllia https://newtfire.org
Balisage: The Markup Conference 2020-07-28
Link to these slides: https://bit.ly/codeWrite
Class capped at 25 or less (multiple disciplines)
Writing designed to help students learn course topics
Writing geared to learning conventions in the field
Writing must involve informal and formal stages
Class = “discourse community”, students and faculty share evaluation, feedback
See: “Features of a Writing Intensive Course” Penn State Learning (2020)
Format
Structure
Flow
Historically, women have had a tough time when it comes to writing novels and combatting prejudices and sexism. Many female authors have had to publish their novels with a male pseudonym or as an anonymous author. When writing Frankenstein, Mary shelley wrote it among her friends to see who could write the best horror story and she did not tag it with her name. The famous story was left anonymous so her friends wouldn't have a prejudice view when reading it. The story ended up being her most famous book and she was a female writer, who wrote a horror story about a male creator and a frightening, male creature.
Now let's look at some early student markup of recipes
<recipe type="allAges" name="sourdoughIngredients">
<measurement>1 1/4 cups</measurement> (<amount>160 grams</amount>)
<ingredient>white bread flour</ingredient>, plus more for dusting
<measurement>1/4 cup</measurement> (<amount>38 grams</amount>)
<ingredient>stone-ground whole-wheat flour</ingredient>
<measurement>1/4 cup</measurement> (<amount>32 grams</amount>)
<ingredient>stone-ground whole rye flour</ingredient>
<measurement>1/2 teaspoon</measurement>
<ingredient>instant yeast or bread machine yeast</ingredient>
<measurement>1 teaspoon</measurement>
<ingredient>table salt</ingredient>
<measurement>1/4 cup</measurement> (<amount>55 grams</amount>)
<ingredient>dry fermented cider</ingredient>
<measurement>1/2 cup</measurement> (<amount>120 grams</amount>)
<ingredient>lukewarm water</ingredient> (<temperature>80 degrees</temperature>),
plus an optional 1 tablespoon recipe></recipe>
<!--jgb: You may substitute a Pilserner beer for the dry fermented cider. -->
<recipe type="bread" name="country loaf (pain de campagne)">
<measurement type="cup">1 1/4 cups (<measurement type="gram">160 grams</measurement>)</measurement>
<!-- sd: is this a good/okay way to do measurement types? it seems weird but i don't really know -->
<ingredient type="dry">white bread flour</ingredient>, plus more for dusting
<measurement type="cup">1/4 cup (<measurement type="gram">38 grams</measurement>)</measurement>
<ingredient type="dry">stone-ground whole-wheat flour</ingredient>
<measurement type="cup">1/4 cup (<measurement type="gram">32 grams</measurement>)</measurement>
<ingredient type="dry">stone-ground whole rye flour</ingredient>
<measurement type="tsp">1/2 teaspoon</measurement>
<ingredient type="dry">instant yeast or bread machine yeast</ingredient>
<measurement type="tsp">1 teaspoon</measurement>
<ingredient type="dry">table salt</ingredient>
<measurement type="cup">1/4 cup (<measurement type="gram">55 grams</measurement>)</measurement>
<ingredient type="wet">dry fermented cider</ingredient> (may substitute Pilsener beer; see
headnote)
<measurement type="cup">1/2 cup (<measurement type="gram">120 grams</measurement>)</measurement>
<ingredient type="wet">lukewarm water</ingredient> (<temp>80 degrees</temp>),
plus an <measurement type="tsp">optional 1 tablespoon </measurement>
DIRECTIONS
<step n="1"><equipment type="utensil">Whisk</equipment> together the flours, yeast and salt in a
<equipment type="bakeware">mixing bowl</equipment></step>.
<step n="2">Combine the cider and water in a
<equipment type="bakeware">liquid measuring cup</equipment></step>.
<step n="3">Add the liquid to the flour mixture; use a <equipment type="utensil">spatula</equipment>
or <equipment type="utensil">bench scraper</equipment> or your hand
moistened with water to blend them for about a minute</step>.
The dough should be shaggy yet cohesive.
<step n="4">Cover the bowl with a <equipment type="cloth">towel</equipment>;
let the dough rest for <time>20 minutes</time></step>.
<!-- MORE CODE for the recipe steps -->
</recipe>
Student schema writing = project management experience
Better than writing to the prof's rubric!
datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
start = root
#bb_1/22/20: root is the root element
root = element root{intro, step+}
#bb_1/22/20: step is one of our 'highest' content objects on the hierarchy
step = element step{num, (exp|act|obj|desc|text)+}
#amp: This would be better as mixed content!
#amp: So, it would look like this: step = element step{num, mixed{exp | act | obj | desc)+}}
#bb_1/22/20: intro is a misc element
intro = element intro{text}
#bb_1/22/20: other important places in the hierarchy
exp = element exp{(type|act|obj|desc|text)*} #exp = explanation
desc = element desc{(type|act|obj|text)*} #desc = description
#amp: This is the same as before: these two would be better written with mixed content!
So: exp = element exp{mixed{(type | act | obj | desc)*}}
#desc = element desc{mixed{(type | act | obj)*}}
act = element act{type, text} #act = action
obj = element obj{type, text} #obj = object
#bb_1/22/20: attributes
num = attribute num{xsd:int}
type = attribute type{text} #types:
#comp = computer
#conc = concept
#rel = relate
#adj = adjective
#spec = specific
#unspec = unspecific
#amp: My first comment is about comments! I'm glad to see you using comments
not only to leave notes to the instructors, but also to give information about decisions
that you're making while coding.
This is so helpful when it comes to projects that you're going to share publicly,
because it allows others to see these choices and better understand your code.
So, great work with that!
#amp: Another thing that I like with your schema is the organization!
You have clearly designated sections for your elements and attributes that make your code really clear.
#amp: For the future, I would try working more with the other repetition indicators,
as well as with datatypes! In this specific assignment, you could code for the date of the
assignment, and use xsd:date or xsd:YearMonth (or both!) to give even more metadata in
your xml. Overall, this is a well-organized, simple schema that you'll be able to develop
into a more complex schema if you were to continue with it (and with future projects!)
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="01-22_SCHEMA_rngEx02.rnc" type="application/relax-ng-compact-syntax"?>
<root>
<intro> Make sure you do the following: </intro>
<step num="1"> 1) <act type="spec">Save</act> your <obj type="comp">Relax NG file</obj>
<desc type="rel">with the <obj type="comp">.rnc extension</obj> at the
<obj type="conc">end</obj></desc> and <act type="unspec">work with it</act> in the
<desc type="adj">same</desc> <obj type="comp">file directory</obj>
<desc type="rel">with your <obj type="comp">.xml file</obj>.</desc>
</step>
<step num="2"> 2) <act type="spec">Associate</act> your <obj type="comp">.rnc schema</obj>
<desc type="rel">with your <obj type="comp">.xml file.</obj></desc>
<exp>(You are <desc type="rel">finished</desc> with this <obj type="conc">exercise</obj> if
your <obj type="comp">XML</obj> is <desc type="rel"><act type="spec">associated</act>
with your schema</desc> and <desc type="adj">both</desc>
<obj type="comp">files</obj> have <act type="spec">come out</act>
<desc type="adj">"green"</desc> in <obj type="comp">oXygen</obj>.)</exp>
</step>
<step num="3"> 3) <act type="spec">Upload</act>
<desc type="adj">BOTH</desc>
<obj type="comp">files</obj> here. We <act type="unspec">need to see</act> your <desc
type="rel"><obj type="comp">.xml file</obj> and your <obj type="comp">.rnc
file</obj>.</desc>
</step>
</root>
<!-- bb_1/22/20: I wanted to keep it simple for once, so I literally
used the assignment as a text. Sue me.-->
(//p[descendant::placeName => distinct-values() => count() gt 2])[last()]
(//p[count(distinct-values(descendant::placeName)) gt 2])[last()]
XPath 2
XPath 3
vs.
(so much easier to teach and read!)
From the XML Slack, 11 July 2020
“you want my data; you go to my website or load my CD and download or copy both the data of interest and any associated files (e.g., documentation or specifications like a TEI ODD, a METS profile, or the Balisage tag library); based on your knowledge of my data that comes from either the documents themselves or from the associated files (or both), you either change my data to suit your system or change your system to suit my data as needed. Human intervention, but not direct communication, is required.”
— Bauman, Syd. “Interchange vs. Interoperability.” Presented at Balisage: The Markup Conference 2011, Montréal, Canada, August 2 - 5, 2011. In Proceedings of Balisage: The Markup Conference 2011. vol. 7 (2011). https://doi.org/10.4242/BalisageVol7.Bauman01.
Source: Adam Rule et al., “Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks” PLOS Biology (July 25, 2019).
Comparison of 8 versions of a charter for a Welsh Collegiate Church and School founded in 1541
closed issues from Fall 2019 Brecon GitHub repository
SVG Graph made by Alyssa Argento with XSLT processing TEI XML critical apparatus markup
Link to these slides: https://bit.ly/codeWrite
Questions and comments welcome!