Writing Mathematics with DoenetML

In this section we’ll discuss markup languages, and learn the basics of writing a mathematical document in Doenet.

Markup Languages

Microsoft Word and Google Docs are examples of so-called “What You See is What You Get” (or WYSIWYG, pronounced “whiz-ee-wig”) editors. If you edit a document in Word, you might spend a lot of time adjusting margins, spacing, line breaks and more. If you print a copy of the document, it will look exactly the same as what you see on your screen.

Writing a document with DoenetML is different. DoenetML is a so-called Markup Language, similar to HTML (for webpages) and LaTeX (for PDFs and other documents). Instead of worrying about margins and other formatting issues, you simply write out all of the text and other content in your document, and then let the computer worry about how best to display it on screen. As part of your content, you can add certain commands (or “tags”) which tell the computer, for example:

• “The following text should be displayed as one paragraph,”
• “The following text is a math equation,” or
• “The following lines should appear as a list of bullet points,”

but you have no control over where the line breaks occur, how far the bullet points are indented, and other formatting decisions.

Basic Text in DoenetML

If you’ve created a webpage with HTML, you’ll feel right at home writing in DoenetML. (And if you haven’t, don’t worry — there’s not too much to learn!) Content is always contained between opening and closing tags. Just like HTML, tags are denoted with angle brackets, < and >. The closing tag includes an extra slash.

For example, the following text would create a new paragraph:

     <p>Write the paragraph text here!</p>

Test code here.

Similarly, the <em> tag tells Doenet that the surrounded text should be emphasized, which typically means your web browser will italicize the text.

Below this paragraph, you’ll see an example with one line of code using <p> and <em> tags. To test the code in a live editor, click on the “Test Code” button at the bottom of the example.

In your test editor, you can click on the blank line at the bottom and add a new paragraph, surrounded by <p> and </p>. Then click “update” to see the results. If you get an error, make sure you’ve included both the opening and ending tags,

<p>This is a short paragraph, which includes some <em>emphasized</em> text. Similar to other markup languages, DoenetML ignores    extra    spaces
 
and blank lines.</p>

Test code here.

As demonstrated above, tags can be nested; the text between <p> and </p> includes emphasized text, using the <em> tag. If you nest tags, you must always close the most “recent” tag before closing any others. For example, once you use an <em> inside of a paragraph, you must include the closing </em> before finishing the paragraph with </p>.

In your test editor, try swapping the </em> and </p> tags, and then click “update.” DoenetML will complain that it expected </em>, but found something else instead.

Similar to HTML, tags in DoenetML are case-insensitive. In other words, you could replace any <em> tag above with <EM>, <eM>, or <Em>, and the emphasized text will still render correctly.

Math Expressions in DoenetML

In DoenetML, mathematical expressions are denoted with the <m> tag, and are rendered with MathJax. If an expression or equation is important enough to be centered on a line by itself, use the <me> tag instead.

<p>Consider the function</p>
 
<me>f(x) = x^2-3x-10.</me>
 
<p>Then <m>f(x)=0</m> when <m>x=5</m> or <m>x=-2</m>.</p>

Test code here.

For those familiar with LaTeX, the difference between <m> and <me> is essentially the same as “inline” and “display” mode in LaTeX. Speaking of LaTeX: you can use nearly any valid LaTeX code in <m> and <me> tags. (You can see the full list of commands supported by MathJax; although you can’t embed full text environments in an <m>, essentially any code you would use to typeset mathematics should work.) See below for some examples.

<me>x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}</me>
 
<me>F(x) = \int_a^x f(t) \, dt</me>
 
<me>| \angle ABC | = 30^\circ</me>

Test code here.

The <m> and <me> tags do not recognize strings such as “sqrt” or “sin” as mathematical functions. To render those functions correctly, use the appropriate LaTeX code:

<me>\sqrt{a^2+b^2}</me>
 
<me>\sin{(a+b)}</me>

Test code here.

A full LaTeX introduction is beyond the scope of this tutorial. If you’re not familiar with LaTeX, we highly encourage you to search online for an introduction to typing mathematics in LaTeX, such as this guide from Overleaf.

Lists and other HTML Tags

Many of the basic HTML tags for formatting text carry over to DoenetML. The code sample below demonstrates paragraphs, lists, and alert (bold) text.

<p>You've already seen paragraphs and <em>emphasized</em> text.  Although DoenetML does not have a tag for bold text, it does have a tag for <alert>alert text</alert>.</p>
  
<p>Lists come in two flavors: ordered and unordered.</p>
 
<ol>
  <li>Ordered lists</li>
  <li>have numered items.</li>
</ol>
 
<p>For comparison:</p>
  
<ul>
  <li>The items in an unordered list are</li>
  <li>displayed in the order they appear in the</li>
  <li>code, but with bullet points, not numbers.</li>
</ul>

Test code here.

Lists can be nexted as well, but be sure the second list is entirely contained between a pair of <li> and </li> tags in the “parent” list. See the editor below. Try turning one or both of the lists into an ordered list in the test editor and click update to see the results.

Comments

Occasionally you might want to “comment out” part of your document, i.e. prevent it from being processed by Doenet and displayed on screen. (Perhaps something isn’t working correctly, or you’re working on a long document and only want a portion of it to render on screen.). DoenetML uses the same comment tag as HTML; anything between <!-- and --> will be ignored:

    <!-- this code will be ignored by Doenet -->

You can see a DoenetML comment in action in the following sample:

<!-- <p>This paragraph will be ignored by Doenet</p> -->
 
<p>This text will be displayed.</p>

Test code here.

For Experienced HTML Users Only

(If that doesn’t describe you, feel free to skip right over this section!)

If you’ve written a lot of HTML in your life, you’ll feel comfortable with the structure of a DoenetML document — but you might find that some of the tags you’re used to using don’t work in DoenetML, including:

<b>: use <alert> instead.

<i>: use <em> instead.

<code>: use <c> instead.

<a href="https://doenet.org">link text</a>: Use <ref uri="https://doenet.org">link text</ref> instead. Make sure to include https:// at the beginning of the link.

<hr/>: will cause an error.

<h1> through <h6>: will cause an error. Instead, you can create headers by including the appropriate text within <section> tags. This will create an automatically numbered section in your document (or subsection, if you nest the <section> tags). If you wish to give the section a specific name instead, use the <title> within the section.

A later section of this tutorial will discuss the creation of long documents with chapters and sections.

<div> and <span>: will not cause errors, but are essentially ignored with respect to formatting. Web developers commonly use these tags when adjusting the styles of certain elements on the page (i.e. CSS code), but DoenetML will not give you access to these options. If you try to include a style=“css-code” attribute in a <div>, <span>, or other element, DoenetML will return an error.

Next Steps

Now that you know the basics of DoenetML, the next section will explain how to create an account on doenet.org, so that you can start to create your own documents.

At that point you’ll be able to use Doenet to create webpages full of beautifully rendered mathematics. That’s useful, to be sure, but isn’t much different than directly using HTML and MathJax. Hence the following sections will show you how to unleash the true power of Doenet, with interactive questions and answers, graphical elements, and more!