Classify asides

[davidfarmer]

We should gather examples of asides, so that we can understand what are the different categories, and how they should be styled.

Post real examples here.

[sklarjk]

This is an aside I would like to have render without a displayed number and without requiring a title (though, yes, I could give it the title "Linguistic note".)

<example>Some common sets are:
<p>
<ul>
<li><m>\Z</m> is the set of all integers <aside>The use of <q>\Z</q> in denoting the set of integers comes from <q>zahlen,</q> the German word for <q>numbers</q>.</aside></li>
<li><m>\Q</m> is the set of all rational numbers</li>
<li><m>\R</m> is the set of all real numbers</li>
<li><m>\C</m> is the set of all complex numbers</li>
<li><p><m>\N</m> is the set of all natural numbers, that is, the set <m>\{0, 1, 2, \ldots\}</m></p></li>
</ul>
</p>
</example>

[davidfarmer]

Without the example appearing in context in a book, I don't know how to understand it or compare it to other ecxamples.

On Tue, 1 Aug 2017, Jessica K. Sklar wrote:

This is an aside I would like to have render without a displayed number and without requiring a title (though, yes, I could give it the title "Linguistic note".)

The use of \Z in denoting the set of integers comes from zahlen, the German word for numbers.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.[AAM6LJJqJjSLzHcUUXMlIdpH3hW8tmYBks5sT2c5gaJpZM4OqDua.gif]

[sklarjk]

Edited.

[davidfarmer]

Sorry to be so pedantic, but what I want to see is a complete HTML page (or PDF or scan).

(Among other reasons, I can see that the sample PTX will not convert to HTML. But more importantly, what matters is the context and the other decisions the Author has made.)

For example, is it obvious to students why we use \Q for the rationals? If that also merits a comment, then probably you would put one aside on the whole list, not two small asides on list items.

Also, serious thought should be put into making those a dl, not a ul.

[sklarjk]

I tried putting them in a

but I didn't want all the text in the left-hand column boldfaced. If there is a way of using

without

, by all means let me know. I don't think it takes much for at least a native English-speaker to figure out \Q for quotient, \R for reals, \C for complex. I do not intend to make other asides there. Here is the HTML. And no, I don't like the warning in the middle of the list either. I'm working on it. https://community.plu.edu/~sklarjk/ptx/ptx/section-2.html On Tue, Aug 1, 2017 at 11:14 AM, davidfarmer wrote: > > Sorry to be so pedantic, but what I want to see is > a complete HTML page (or PDF or scan). > > (Among other reasons, I can see that the sample PTX will not > convert to HTML. But more importantly, what matters is the > context and the other decisions the Author has made.) > > For example, is it obvious to students why we use \Q for the > rationals? If that also merits a comment, then probably > you would put one aside on the whole list, not two small > asides on list items. > > Also, serious thought should be put into making those > a dl, not a ul. > > — > You are receiving this because you commented. > Reply to this email directly, view it on GitHub > , > or mute the thread > > . > -- Dr. Jessica Sklar Chair of Mathematics Pacific Lutheran University

[Alex-Jordan]

<li><m>\Z</m> is the set of all integers <aside>The use of <q>\Z</q> in denoting the set of integers comes from <q>zahlen,</q> the German word for <q>numbers</q>.</aside></li>

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

[sklarjk]

As I noted, I'm working on getting the warning outside of the list.

I originally had these "asides" as footnotes, but Rob didn't like it. So I was trying them as asides, but it turns out no one (including myself) likes that. Most of them are becoming parenthetical comments.

What is the reason for not having footnotes, Rob?

On Aug 1, 2017 11:40 AM, "Alex Jordan" notifications@github.com wrote:

\Z is the set of all integers

The use of \Z in denoting the set of integers comes from zahlen, the German word for numbers.

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/issues/653#issuecomment-319459750, or mute the thread https://github.com/notifications/unsubscribe-auth/AcvBbI6kWMwUEYH3MbDdRTIr9ayilUo9ks5sT3EYgaJpZM4OqDua .

On Aug 1, 2017 11:40 AM, "Alex Jordan" notifications@github.com wrote:

\Z is the set of all integers

The use of \Z in denoting the set of integers comes from zahlen, the German word for numbers.

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/issues/653#issuecomment-319459750, or mute the thread https://github.com/notifications/unsubscribe-auth/AcvBbI6kWMwUEYH3MbDdRTIr9ayilUo9ks5sT3EYgaJpZM4OqDua .

On Aug 1, 2017 11:40 AM, "Alex Jordan" notifications@github.com wrote:

\Z is the set of all integers

The use of \Z in denoting the set of integers comes from zahlen, the German word for numbers.

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/issues/653#issuecomment-319459750, or mute the thread https://github.com/notifications/unsubscribe-auth/AcvBbI6kWMwUEYH3MbDdRTIr9ayilUo9ks5sT3EYgaJpZM4OqDua .

[davidfarmer]

I originally implemented asides for the marginal notes in APEX calculus. I consider those to be associated to "block level" elements, such as a definition, theorem, or example. Even a short aside (like the "zahlen" example) can take 2 or three lines, because the margin is narrow. Another good working model is a picture and brief biography of Euler.

That is still the way I think about asides. My attempt to make asides usable on a narrow screen has invited tag abuse.

I agree with Alex that many short asides can just be put in the main text.

[rbeezer]

On 08/01/2017 11:40 AM, Alex Jordan wrote:

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

There is no structure in the placement of a footnote. Just drop it anywhere. And very dangerous on things that get copied other places, like titles.

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

I sort of hope it does not go anywhere. Then it is a footnote. See above. The presentation in print will take some care.

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

I'm pretty sure a "warning" cannot be placed in a list item. Jess, what does the schema say? Did your source validate against the schema?

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

The first are "figure-like" in the code, I've taken to calling them "captioned". Named lists are in limbo, see previous query that fell on deaf ears.

[sklarjk]

Now I know how my students feel when they come to me with a question about a problem they've been working on and my eyes start to bleed because of all of their notation errors, and I can barely address their question because I'm so horrified with their writing. ;) Sorry for making everyone's eyes bleed. I'm learning.

On Aug 1, 2017 11:40 AM, "Alex Jordan" notifications@github.com wrote:

\Z is the set of all integers

The use of \Z in denoting the set of integers comes from zahlen, the German word for numbers.

In the forum, I mentioned that many places people want to use an aside, it seems fine to me to just wrap parentheses around the content and leave it where it is (as in your line link). Or maybe as a footnote (but Rob has reasons to discourage use of footnotes).

At present, we wouldn't support having an aside within a list. So for this to be an aside at present, you'd write the aside after the p containing the list. Then it would be structurally too far away from the particular list item you would be commenting on. Question for Rob and David: will aside be permitted any old place? Or must it be a child of something structural (chapter, section, etc)?

Your live link also has a warning within an example. I don't think that is supported, nor will ever be. As a numbered block element, it needs to be a child of something structural.

Aside: what is the vocabulary for distinguishing numbered things like table|figure|listing from numbered things like definition|example|warning?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/issues/653#issuecomment-319459750, or mute the thread https://github.com/notifications/unsubscribe-auth/AcvBbI6kWMwUEYH3MbDdRTIr9ayilUo9ks5sT3EYgaJpZM4OqDua .

[rbeezer]

"Real" of a sort. Demonstration of real implementation.

https://edwardtufte.github.io/tufte-css/

[sepvar]

I have an example.

I am trying to write a physics textbook. I have a few fundamental ideas that I want to ensure the students keep in their head when they are introduced to a new idea. To do this, I would like to have

<aside><title>Touchstone</title>
<p>This is connected to <xref provisional="s-noninertial" text="title">non-inertial reference frames</xref>.</p>
</aside>

As a footnote, I don't think students will click to see it and as a remark-like entity I think it would interrupt the text too much. I would season these throughout the text.

Thanks.

Joe

Since you asked for a compile-able text:

<?xml version="1.0" encoding="UTF-8"?>
<mathbook xml:lang="en-US">
    <docinfo>
        <rename element="biographical" lang="en-US">Touchstone</rename>
        <cross-references text="global" />
    </docinfo>
    <book xml:id="public-example">
        <title>Physics Connected</title>
    <chapter><title>Reference Frames</title>
        <section xml:id="s-inertial"><title>Inertial Reference Frames</title>
        <p>details</p>
        </section>
        <section xml:id="s-noninertial"><title>Non-inertial Reference Frames</title>
        <p>details</p>
        </section>
    </chapter>
    <chapter><title>Orbits</title>
        <p>Look!  You're in freefall!</p>
                <aside><title>Touchstone</title><p>This connects to the ideas of <xref ref="s-noninertial" text="title">non-inertial reference frames</xref>.</p></aside>
    </chapter>
    </book>
</mathbook>

[mitchkeller]

Here's something I converted from an invalid footnote (contains two me's) in Bogart to an aside. To me, this is a pretty good use of an aside. It's not essential to continuing the discussion, and in looking at the HTML rendering, I'm not 100% certain where in the source the <aside> lives. I'm fine with that.

And now for a bunch of scans of marginalia from my book collection. Calculus books have a strong tendency to use that space for small figures, but they do insert some other content out there that seems to be aside-like.

This is from the only precalculus text that I have on the shelf at home. I think it would be useful to see if those working on developmental projects could give some scans of the types of things that wind up as marginalia to decide what is aside-like and what might need to be a feature but would be of another type.

The one advanced level math text I know of that makes use of marginalia is Diestel's Graph Theory. These do not qualify as asides to me, but his uses would certainly be something that it would be nice to support (and perhaps enable with just a couple of options being set in docinfo, since it's mostly about flagging in the margin where things are defined or where a result references another result or a bib item).

[rbeezer]

A marginal use: small versions of embedded videos that open up really big on another page. I think in many cases (not all) these would be tangentially related to the material, hence with an "aside-like" character.

David worked a long time ago to associate a single video with a division - ie, it was instructional material for that division.

[sepvar]

So, I have finally got a server up and running and posted a working version of my physics textbook.

You can look here (http://physics.thomasmore.edu/ConnectedPhysics/ss-NII.html) to see how I am trying to use the Touchstone aside mentioned above. You may note that for every touchstone, I have a corresponding "Referenced by" in the margin so that readers will know when the material they are currently reading will be referenced later in the book.

I am also using the margins for "Foreshadow: I will use this later at..." as in this page (http://physics.thomasmore.edu/ConnectedPhysics/ss-NIII.html)

Joe

[davidfarmer]

Glad to have working examples of Touchstone asides, because I am about to announce a major change to how asides are displayed!

I will investigate your Touchstone examples before I do that.

On Mon, 4 Sep 2017, Joe Christensen wrote:

So, I have finally got a server up and running and posted a working version of my physics textbook.

You can look here (http://physics.thomasmore.edu/ConnectedPhysics/s-forcewords.html) to see how I am trying to use the Touchstone aside mentioned above. You may note that for every touchstone, I have a corresponding "Referenced by" in the margin so that readers will know when the material they are currently reading will be referenced later in the book.

Joe

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.[AAM6LDFVu8edt3ZNB-airraPiJjyvNzhks5se0u6gaJpZM4OqDua.gif]

[sepvar]

I just remembered that I ended the book with a List of Asides, if that speeds up your looking it over. http://physics.thomasmore.edu/ConnectedPhysics/list-aside.html

Joe

[rbeezer]

@sepvar I like the "Touchstone" very much, and they seem to work well as asides.

The "Referenced By" are rather inventive. I'm not sure we really want a knowl opening in an aside, though it seems to work, though is very skinny.

So...when you make a "forward reference", ie an "xref" to some material later, you want an indication at that forward location that it has been referenced, and from where. Basically, you want to turn the @ref -> @xml:id link around. We can do that automatically by looking through the source, though it may be expensive (lots of processing time), and maybe it is not something we want to automate. Thoughts?

[sepvar]

@rbeezer Before I learned of MathbookXML, I had designed the book in my head according to LaTeX (see attachment) in which I could create a PDF with live links. In that case I had a few problems:

1. I could link directly to a specific paragraph, but depending on how the viewer was viewing the page, I could not guarentee the reader knew to what I was pointing, so I could only reliably link to a specific page.
2. Many people did not know that [alt]-[left arrow] functioned as a "back" button.
3. The concept of knowls did not exist in a LaTeX-created PDF. So I decided I needed a way to indicate A. a margin note that indicated where I was specifically intending the reader to look, and B. how to return to the location I had come from.

I would be happy if the Touchstone/Referenced By opened the knowl in the main page (instead of the margin), but I can't imagine the code that would make that work.

I do not think it is necessarily a good idea for every xref to have an automatic xml:id return, especially with it being computationally expensive. I, personally, have decided (though not yet implemented) to link to a <paragraphs> when I want a knowl and linking to a <section> when I want to jump away. I lke that the knowl has an [in context] that gives the reader the option of jumping away and web-browsers have a "back" button. For me also, I am happy to add a [Referenced by] link whenever I make a Touchstone link so that I am by hand linking forward and backwards as I see fit. I think that is sufficient. (Others might reasonably disagree.)

This is the pre-XML version of my book: ABIP.pdf The XML -> PDF version is not nearly as pretty. :-(

I would like to have investigation and other activities appear in the PDF as colored boxes, but that'd take some effort. I am happy to share my original LaTeX version of my book to help make the XML -> PDF nicer.

[davidfarmer]

I would be happy if the Touchstone/Referenced By opened the knowl in the main page (instead of the margin), but I can't imagine the code that would make that work.

Well, I can imagine that code!

In the new asides code, knowls in asides open in the main body, even if the aside is in the margin. I think I have checked it well enough to make it public soon.

Once we start categorizing asides, maybe not all of them will open in the body, but the touchstone-style will.

[sepvar]

Hi, David. I had a new idea that I am not committed to, but I think I like. Etymology I am trying it in a few places and it seems consistent with the biographical and historical in that it draws in people with an adjacent interest. I already had it in the body of the text in some places, but in others I think I want it as an aside. I haven't quite figured out a standard use. http://physics.thomasmore.edu/ConnectedPhysics/s-forcewords.html http://physics.thomasmore.edu/ConnectedPhysics/sss-netforce.html http://physics.thomasmore.edu/ConnectedPhysics/s-FN.html http://physics.thomasmore.edu/ConnectedPhysics/s-FT.html

I might just rename the "historical" for this. (I have already renamed the biographical.)

(As an aside, I was reading the schema this morning. It looks like it says that I can put an aside inside an aside. Is that right? Why would we need to nest an aside?)

[davidfarmer]

Here is text from a discussion on pretext-dev https://groups.google.com/forum/?hl=en#!topic/pretext-dev/ih66eqSfxVc

Is "etymology" part of the proposed "notation", or is it a new type of "historic"?

---

biographic (about one person) historic (but not biographic) touchstone (brief reference to a ongoing theme or another part of the book) notation (comment/explanation of notation, pronunciation, or usage) scratch (scratchwork, or graphic related to the discussion) reminder (remember this thing from last week or high school)

[unclassified] (an aside that is not in any of the above categories)

Please suggest other possibilities. Could there be a "warning" aside, or by definition must a warning be more important than an aside?

I propose that the following types of asides be born fully visible, with full sized text, not faded, and not partially hidden behind the main text (but still in the margin if the margin is wide enough):

notation scratch

[sepvar]

I was thinking of it as a cross-over between historic and notation, because it doesn't really fit in either; but given six types, I think it would be easy enough to not introduce it and have it be a rename of some other existing type.

I don't think etymology would be as popular as any of those and might not need its own category... unless you hear differently from the community.

Thanks for the pushback.

[davidfarmer]

I expect that historic and notation will have different styling, with notation probably having styling that is more suitable to etymology.

We also need to decide if title on any of these is optional or determined automatically in some way.

If you have an etymology already in use, please post a link (a real example, not a made-up or minimal one) so that it can be taken into account when decisions are made.

Let's also think of possible needs in non-science books, for which etymology, or "publishing history", could be more common.

On Wed, 11 Oct 2017, Joe Christensen wrote:

I was thinking of it as a cross-over between historic and notation, because it doesn't really fit in either; but given six types, I think it would be easy enough to not introduce it and have it be a rename of some other existing type.

I don't think etymology would be as popular as any of those and might not need its own category... unless you hear differently from the community.

Thanks for the pushback.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.[AAM6LGePmuQMlRzrGc8xsulIIAkCXkE9ks5srL8VgaJpZM4OqDua.gif]

[sepvar]

I posted four links previously. Here they are again:

http://physics.thomasmore.edu/ConnectedPhysics/s-forcewords.html http://physics.thomasmore.edu/ConnectedPhysics/sss-netforce.html http://physics.thomasmore.edu/ConnectedPhysics/s-FN.html http://physics.thomasmore.edu/ConnectedPhysics/s-FT.html