search

sjw82 / SciFi

The greatest Science Fiction/Digital Humanities cross-over independent project in living memory or at least my living memory.
http://empathy.obdurodon.org/
1 stars 0 forks source link

XML Markup Considerations #1

Open sjw82 opened 5 years ago

sjw82 commented 5 years ago

This issue contains: questions for David and Geoff and notes so Sam doesn't forget things

I currently intend to markup for

? (David) With the CBT/DBT elements, I want to delineate between text that offers the opportunity to lead students in whichever exercise and examples of characters in the text doing the exercise, which I'll admit is drastically less common. I would then like to get more specific because in designing a lesson the teacher may be interested in very specific things: for example when discussing cognitive distortions they may only want to focus on all-or-nothing thinking rather than catastrophizing. I'm trying to think of an elegant way to define that. Whats coming to mind it

<empathy opportunity="cogDist" cogdist="catast"

But in my heart of hearts that doesn't feel like the ideal solution.

I am also not as certain about breaking down things like thought challenge and especially dialectics which vary greatly but do not fall into discrete categories. Is it better to leave it unspecified and have teachers pick and choose which examples they want to use considering the limited time I have to do the project or is it better to try and develop/dig deeper to find categories?

? (Geoff) I had previously intended to look for social justice elements but I'm not sure what that would look like markup wise (sort of like annotations within the text except you only have a highlighter). I think that may be better reflected in the questions (effectively the annotations except you only get to write in the margins and reference other highlighted things) and provide the evidence through the axes of investigation, but what do you think? I'm doing Freirean social justice for Amy's class so I don't know if I'll have a clearer idea for a while.

? (Geoff) I'm thinking of leaning away from the message fic focus just because that is more central to our class than it might be for a high school teacher who can ask the class to assume the text has meaning or can have a one day discussion on it rather than rehashing it in every text. Alternatively it could be more a part of the discussion questions, again using the axes as evidence, but I'm not sure how it would look literally projected on the text. Do you think that is going to make the high school discussion plans more robust and zesty or should it be assumed?

djbpitt commented 5 years ago

@sjw82 Great questions! Before I respond, though, here are a couple of GitHub conventions:

  1. When you address someone directly, you can use an "at" sign followed by their GitHub userid (for an example see the beginning of this paragraph, which tags you). Since I don’t think Geoff has a GitHub account, though, that doesn't apply to him.
  2. When you include code snippets inside your text, such as the bits of XML markup in your bulleted list, you should surround them in backticks (typically the backtick key is in the upper left corner of your keyboard). This causes them to formatted in a way that stands out, e.g., <scifi trope= "aliens">. There’s a slightly different markdown convention for blocks of code; the paired backticks are for snippets within running plain text.
  3. In your XML examples you don’t include the closing angle bracket. This is just a prose conversation, so it doesn’t really matter, but it looks odd. Was there a reason that you omitted it?

With respect to your markup question about structures like <empathy opportunity="cogDist" cogdist="catast">, it isn’t unheard of to have a class of attributes that makes sense only if another attribute has a certain value, so that, for example, an attribute called cogdist makes sense only if the value of an attribute called opportunity has the value “cogDist”. (If you do that, though, I would choose either “cogdist” or “cogDist” for both the attribute name and the value; if you use one capitalization in one place and a different one in the other, it’s easy to slip up and use the wrong one.) That type of inter-attribute dependency is a bit awkward, as you say, but it may nonetheless be a good representation of what you want to convey through your markup. There is a way to write a schema that will enforce a rule like that, and we can talk about how to do it at our next meeting.

Whether you want to leave some things unspecified, as you ask above, is really more of a content question than a markup one. With your goals in developing the project in mind, which approach is most consistent with those goals?

sjw82 commented 5 years ago

@djbpitt Thank you for the notes! Upon some reflection, I think going that in depth would heavily restrict planning and make the resulting discussion less flexible. Leaving some things unspecified may be more in line with an educator's needs and my goal is for this to be plausibly useful. I didn't include the closing angle bracket because when I published the issue it would try to apply the markup, making it invisible, and I wasn't sure what else to do to make it clear that I didn't want that to be happening so thank you for clarifying about the backticks.

djbpitt commented 5 years ago

@sjw82 Thanks, Sam, for the quick response. Two thoughts:

  1. With respect to what to leave unspecified, a possible compromise might be to make the heavier markup separable from the rest, so that someone using your materials could refer to it or not. For example, you might have an auxiliary document that outlines certain types of issues and includes pointers into your main text (by which I mean formal pointers, of the sort that could be incorporated into the navigation). That way this other perspective doesn’t intrude into the main markup, but it can be there if someone wants it.
  2. You’ve already figured out the closing angle bracket business, but here’s the back story. The reason the closing angle bracket made your element name disappear is that it is legal to embed real HTML (which has XML-like syntax, with angle brackets) inside markdown. We don’t usually do it, but when you enter something like <scifi> (without backticks), GitHub thinks it’s a real HTML tag, and since tags are supposed to be interpreted, and not shown literally, it doesn’t show it. But because it isn’t a valid HTML tag, it also doesn’t affect the formatting; it just disappears. Wrapping it in backticks tells GitHub that it’s a code snippet, and should be rendered literally.
sjw82 commented 5 years ago

@djbpitt I don't entirely understand what you mean in your first point. My understanding is it would be a secondary document that would have the more complete/detailed xml markup. What would formal pointers be? How would doing this change the way I do my markup?

djbpitt commented 5 years ago

@sjw82 If you decide to leave some of the interpretive markup out for reasons you specify about:

I think going that in depth would heavily restrict planning and make the resulting discussion less flexible. Leaving some things unspecified may be more in line with an educator's needs and my goal is for this to be plausibly useful.

your main XML file, the story itself, would have simpler, less cluttered, and (deliberately) less interpretive markup. But should you want to go into depth without forcing the detail on your users, then yes, the secondary document would contain the detail. But it wouldn't have to contain a separate copy of the story; it would just contain things you might want to say about the story. The trick is that it would include pointers to the sections of the story to which each comment applied, and you could associate the two during processing. For example, the ancillary document might have a bit of markup like:

<p>The great American philosopher Homer Simpson said that <ref target="#p2">sci-fi should
always say something about television and beer</ref>.</p>

The <ref> element has an attribute target that points to something called p2 (the hash mark is a pointer convention; we can talk about when it comes time to implement). Meanwhile, in your main text you might have content like:

<p>Some paragraph.</p>
<p xml:id="p2">Some paragraph about television and beer.</p>
<p>Some other paragraph.</p>

The xml:id attribute serves as the target of the pointer. During processing, you can stitch parts of the two documents together to create a completely different view.

This approach is called stand-off markup because what would logically be markup on the main document is implemented not by wrapping parts of that document in start and end tags, but by putting the markup logic into another document and pointing from there into the main one. In this case, we use the <ref> element with a target attribute as a pointer from the auxiliary document and an xml:id attribute in the main document as the way that the pointer finds its target.