Differences between revisions 21 and 34 (spanning 13 versions)
⇤ ← Revision 21 as of 2013-06-29 06:00:29 →
Size: 4601
Editor: rbeezer
Comment:
← Revision 34 as of 2014-04-30 17:24:35 → ⇥
Size: 7251
Editor: rbeezer
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
A specification for XML tags and stylesheets to create usable output. ~+'''This page is frozen, as of September 2013 '''+~

Please go to the [[http://mathbook.pugetsound.edu|MathBook XML]] site for current progress.

This page reports progress initiated with a [[http://www.shuttleworthfoundation.org/grantees/2013/rob-beezer/|Shuttleworth Flash Grant]], and sustained with support from [[http://utmost.aimath.org|National Science Foundation under Grant No. DUE-1022574]].

= Frozen Content (September 2013) =

A specification for XML tags and stylesheets to create mathematical content that yields usable output.
Line 16: Line 24:
  1. XSLT 1.0 compatible: ideally the only required tool is xsltproc   1. XSLT 1.0 compatible: ideally the only semi-unusual required tool is xsltproc
Line 20: Line 28:
  1. HTML web pages, enhanced with !MathJax, Sage Cell server, knowls
  1. LaTeX input to create PDFs and print with {{{pdflatex}}}
  1. HTML for in-browser previewing
  1. Doctesting of Sage code examples		   1. HTML web pages, enhanced with !MathJax, Sage Cell server, knowls for web browsing
  1. LaTeX input as precursor of PDF output via {{{pdflatex}}} for print
  1. Doctesting of Sage code examples for quality assurance
  1. Sage Worksheets (Sage Notebook, Sage Math Cloud)
Line 25: Line 33:
  1. Maybe a !DocBook representation for conversion to other outputs   1. Maybe a !DocBook representation for conversion to other outputs and future-proofing
Line 32: Line 40:
  * Late-August 2013: usable, with more to do

== Examples (Updated 2013/08/23) ==

  1. A short sample article: [[http://buzzard.ups.edu/mathbook/calculus-article.xml|XML Source-Author Format]] <[[http://buzzard.ups.edu/mathbook/calculus-article.html|HTML Output]]> <[[http://buzzard.ups.edu/mathbook/calculus-article.pdf|PDF Output]]>
  1. A skeletal mock book: [[http://buzzard.ups.edu/mathbook/graph-theory-book.xml|XML Source-Author Format]] <[[http://buzzard.ups.edu/mathbook/book/graph-theory-book.html|HTML Output]]> <[[http://buzzard.ups.edu/mathbook/graph-theory-book.pdf|PDF Output]]>
Line 37: Line 51:
[[http://www.beezers.org/blog/bb/2013/06/shuttleworth-flash-grant/|June 14|, 2013]]
[[http://www.beezers.org/blog/bb/2013/06/the-case-for-an-xml-application/|June 27, 2013]]
[[http://www.beezers.org/blog/bb/2013/06/an-xml-application-for-mathematics/|June 28, 2013]]
[[http://www.beezers.org/blog/bb/2013/08/summer-progress-on-mathbook-xml/|August 23, 2013]]
Line 39: Line 58:
 * Article structure with numbered sections (subsections will be easy)
 * Numbered theorems
 * Sage input/output: live Sage cells in HTML, styled in LaTeX
 * Bibliography + citations: knowls in HTML version
 * Math: normal LaTeX for PDF, !MathJax in HTML, macros in source '''once'''		  * Article structure with numbered sections and subsections
 * Book structure with preface, numbered chapters, sections and subsections
 * Mathematics: normal LaTeX for PDF, !MathJax in HTML, macros in source '''only once'''
 * Numbered theorems and definitions, with cross-references, even in !MathJax displays
 * Sage input/output: live Sage cells in HTML, styled as text for LaTeX
 * Figures, with numbering and cross-references
 * Basic raster images
 * Bibliography + citations: as knowls in HTML version
 * Navigation (previous/up/next) in HTML (needs just a bit of work)
 * Basic CSS for HTML version
Line 45: Line 69:
== Files and Commands, the nitty-gritty ==
Line 46: Line 71:
== Files and Examples == Updated: August 23, 2013
Line 48: Line 73:
Updated: June 28, 2013 Prerequisites: {{{xsltproc}}} is in most Linux distributions and on Mac OS as a command-line executable. Information on Windows availablity would be helpful - please write. You'll need TeX to run {{{pdflatex}}}. You can author if you also have a text editor and a browser - that is all you need.
Line 50: Line 75:

Easiest: it would be nice if you could view the source file (calculus-article.xml) by opening it in a web browser with the stylesheet (article-html.xsl) in the same directory. This did work on some browsers, and not on others. I've added enough nontrivial features now that this is not working in Firefox.

Easy: Look at the [[http://buzzard.ups.edu/mathbook/calculus-article.html|XHTML Output]]. !MathJax does the math, Sage Cell Server does the code, knowls do the citations. Use the following command and files below to create XHTML output and view in your browser by opening the output file. 		HTML output: !MathJax does the math, Sage Cell Server does the code, knowls do the citations. Use the following command and files below to create (X)HTML output and view in your browser by opening the output file.
Line 55: Line 77:
xsltproc article-html.xsl calculus-article.xml > calculus-article.html xsltproc mathbook-html.xsl calculus-article.xml > calculus-article.html
Line 58: Line 80:
Alternate: Look at the [[http://buzzard.ups.edu/mathbook/calculus-article.pdf|PDF Output]], which comes from the same source. Issue the following to produce. PDF: Same XML source file. Use a different XSLT file to process. View PDF as you please. Issue the following to produce.
Line 61: Line 83:
xsltproc article-latex.xsl calculus-article.xml > calculus-article.tex xsltproc mathbook-latex.xsl calculus-article.xml > calculus-article.tex
Line 65: Line 87:
More: repeat above with the mock book, {{{graph-theory-book.xml}}}, linked above.
Line 67: Line 91:
Files: Use your browser to save these files locally, do not simply click on them. If you are an author, the only file you need to understand is the first one, the XML source. Files: Use your browser to save these files locally, do not simply click on them. The XSL files can be scary - not critical for an author to understand them. You'll want the CSS to render any HTML you produce.
Line 69: Line 93:
  1. [[http://buzzard.ups.edu/mathbook/calculus-article.xml|Example XML source document]]
  1. [[http://buzzard.ups.edu/mathbook/article-latex.xsl|XSL transform to LaTeX]]
  1. [[http://buzzard.ups.edu/mathbook/article-html.xsl|XSL transform to XHTML]]
  1. [[http://buzzard.ups.edu/mathbook/freebsd-docbook.css|FreeBSD documentation CSS]]
  1. [[http://buzzard.ups.edu/mathbook/mathbook.css|MathBook CSS]]		   1. [[http://buzzard.ups.edu/mathbook/xsl/mathbook-html.xsl|XSL transform to HTML]]
  1. [[http://buzzard.ups.edu/mathbook/xsl/mathbook-latex.xsl|XSL transform to LaTeX]]
  1. [[http://buzzard.ups.edu/mathbook/xsl/mathbook.css|MathBook CSS]]
Line 75: Line 97:
== The AQ (Asked Questions) ==
Line 76: Line 99:
== To Do ==   1. I can't seem to get a matrix into my document.<<BR>>
  It's math so put it inside `<m>` or `<me>` or `<md>` tags and use LaTeX syntax (amsmath package supported). But the ampersand is one of two troublesome special characters in XML, so you need to escape it. Like so
  {{{
<me>\begin{bmatrix} 1 &amp; 2 \\ 3 &amp; 4 \end{bmatrix}</me>
  }}}
  Or you can wrap the whole thing as a CDATA section (which will cause all markup to be ignored). This might be preferable for a big matrix.
  {{{
<me><![CDATA[\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}]]></me>
  }}}
  1. I have a "less than" in my math which is causing problems.<<BR>>
  The other nasty special character. Use `\lt` instead of `<`.
Line 78: Line 111:
 * Cross-references
 * Index for book structure
 * Options for numbering sections, theorem-like structures		 == To Do (unprioritized) ==

 * Further improve cross-references
 * Table of Contents in HTML as sidebar
 * Index (for book structure)
 * Options for numbering sections, theorem-like structures (hard)
Line 82: Line 118:
 * Doctesting framework for Sage code  * Doctesting framework for Sage code (easy)
Line 84: Line 120:
 * HTML chunking (one HTML file per section, chapter, etc)  * Customize level of HTML chunking (one HTML file per section, chapter, etc)
Line 87: Line 123:
 * Figures
 * Tables
 * Exercises
 * Margin paragraphs

MathBook: An XML Application

This page is frozen, as of September 2013

Please go to the MathBook XML site for current progress.

This page reports progress initiated with a Shuttleworth Flash Grant, and sustained with support from National Science Foundation under Grant No. DUE-1022574.

Frozen Content (September 2013)

A specification for XML tags and stylesheets to create mathematical content that yields usable output.

Shuttleworth Funded

Rob Beezer, [email protected]

Design Goals:

  1. Simple for authors to use - no more complicated logically than LaTeX
  2. Capture the structure of writing about mathematics and Sage
  3. Processing into a variety of formats
  4. A limited number of rational tags, with simple names
  5. Minimal use of external shell scripts
  6. XSLT 1.0 compatible: ideally the only semi-unusual required tool is xsltproc

Output Formats:

  1. HTML web pages, enhanced with MathJax, Sage Cell server, knowls for web browsing

  2. LaTeX input as precursor of PDF output via pdflatex for print

  3. Doctesting of Sage code examples for quality assurance
  4. Sage Worksheets (Sage Notebook, Sage Math Cloud)
  5. E-Books, once technically feasible

  6. Maybe a DocBook representation for conversion to other outputs and future-proofing

Project Status:

  • Funding: Shuttleworth Foundation Flash Grant, National Science Foundation UTMOST Grant
  • Late-June 2013: Good basic functionality for HTML, LaTeX output
  • Mid-June 2013: initiated, not mature or stable
  • Late-August 2013: usable, with more to do

Examples (Updated 2013/08/23)

  1. A short sample article: XML Source-Author Format <HTML Output> <PDF Output>

  2. A skeletal mock book: XML Source-Author Format <HTML Output> <PDF Output>

Commentary

High-level commentary is recorded on my blog.

June 14 June 27, 2013 June 28, 2013 August 23, 2013

Implemented Features

  • Article structure with numbered sections and subsections
  • Book structure with preface, numbered chapters, sections and subsections

  • Mathematics: normal LaTeX for PDF, MathJax in HTML, macros in source only once

  • Numbered theorems and definitions, with cross-references, even in MathJax displays

  • Sage input/output: live Sage cells in HTML, styled as text for LaTeX
  • Figures, with numbering and cross-references
  • Basic raster images
  • Bibliography + citations: as knowls in HTML version
  • Navigation (previous/up/next) in HTML (needs just a bit of work)
  • Basic CSS for HTML version

Files and Commands, the nitty-gritty

Updated: August 23, 2013

Prerequisites: xsltproc is in most Linux distributions and on Mac OS as a command-line executable. Information on Windows availablity would be helpful - please write. You'll need TeX to run pdflatex. You can author if you also have a text editor and a browser - that is all you need.

HTML output: MathJax does the math, Sage Cell Server does the code, knowls do the citations. Use the following command and files below to create (X)HTML output and view in your browser by opening the output file. 

xsltproc mathbook-html.xsl calculus-article.xml > calculus-article.html

PDF: Same XML source file. Use a different XSLT file to process. View PDF as you please. Issue the following to produce. 

xsltproc mathbook-latex.xsl calculus-article.xml > calculus-article.tex
pdflatex calculus-article.tex

More: repeat above with the mock book, graph-theory-book.xml, linked above.

Advanced: create a Sage Cloud worksheet from the same source. I have this working in the lab. Posted soon.

Files: Use your browser to save these files locally, do not simply click on them. The XSL files can be scary - not critical for an author to understand them. You'll want the CSS to render any HTML you produce.

  1. XSL transform to HTML

  2. XSL transform to LaTeX

  3. MathBook CSS

The AQ (Asked Questions)

  1. I can't seem to get a matrix into my document.
    It's math so put it inside <m> or <me> or <md> tags and use LaTeX syntax (amsmath package supported). But the ampersand is one of two troublesome special characters in XML, so you need to escape it. Like so 

    <me>\begin{bmatrix} 1 &amp; 2 \\ 3 &amp; 4 \end{bmatrix}</me>
    Or you can wrap the whole thing as a CDATA section (which will cause all markup to be ignored). This might be preferable for a big matrix. 
    <me><![CDATA[\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}]]></me>

  2. I have a "less than" in my math which is causing problems.
    The other nasty special character. Use \lt instead of <.

To Do (unprioritized)

  • Further improve cross-references
  • Table of Contents in HTML as sidebar
  • Index (for book structure)
  • Options for numbering sections, theorem-like structures (hard)
  • Improved CSS for HTML
  • Doctesting framework for Sage code (easy)
  • Sage notebook, Sage Math Cloud output formats
  • Customize level of HTML chunking (one HTML file per section, chapter, etc)
  • Customization options (layers, HTML head insertions)
  • LaTeX spacing hints
  • Figures
  • Tables
  • Exercises
  • Margin paragraphs

Other Projects

  • tbook looks very much like what I am imagining. I have hacked a bit of it to work with the xsltproc processor with mixed success. Only 80 elements. But for a very short article, I have found cross-references broken and manufacturing a bibliography begins with BibTeX, so that requires some research (and shell scripts). Maybe some examples later.

  • DocBook is big, complicated and full of features. But the emphasis is on technical documentation and support for mathematics and academic publishing is very lacking. The extensive structure is intimidating if you just have small project.

mathbook (last edited 2014-04-30 17:24:35 by rbeezer)