We write technical and academic documents, and are not happy with typical content management systems.
The MMS is a wrapper around LaTeX to make these things easier. Document parsers/translators often don't produce good output without a ton of tweaking. Markdown is a pain for techncial documents ("A * B * C" comes out as "A B C", for example). The solution here is to specify a short list of elements to mark section heads, citations, and so on, and expand those to the appropriate TeX or HTML as needed.
To compile the LaTeX and do the conversions using the script here, you will need one machine with LaTeX and basic POSIX compliance.
It is easiest to set up POSIX compliance via a package management system. Linux users know their package manager; Mac users can use MacPorts or Fink; Windows users can use Cygwin. Each of these package managers will set up a full TeX environment in a few clicks, not to mention thousands of other programs, libraries, language compilers, and games. You will need:
Are you a Github user? Github offers a simple means to host web pages, so if you have a github repository set up, the MMS has a hook to post to it.
We use m4 to convert certain blobs of text to LaTeX-formatted blobs of HTML-formatted blobs, depending on the output type. Anything that is not plain text or math has an associated m4 command.
Both LaTeX and HTML largely ignore the white space in your text file, so feel free to tab-indent whenever it's useful to you.
Math is standard TeX math. We use MathJax to render it in HTML on not-too-old browsers.
Both the LaTeX and HTML headers specify an encoding of UTF-8. On anything but Windows, this is the default; on Windows, please follow the custom of over 80% of the web and save as UTF-8.
This section is a demo of the various commands, and doesn't make much sense as prose. But you can compare the source for this manual to the PDF or HTML output to see how the commands work.
There are Chapter, Section, Subsection, and Paragraph commands. If you need more depth than that you're probably trying too hard. The Paragraph is sometimes useful for marking a list of ideas within a section.
Emphasis, probably italic
Here are links to one extant use of the MMS and its source, and another use of the MMS and its source.
The MMS was developed for a distant spinoff of a modeling textbook (klemens:modeling). It was also used for documenting A survey processing system.
The second argument to Citep is text for the HTML version; BibTeX autogenerates the right text for the PDF.
The content of the citations goes into a BibTeX database. See the sample bib file, or ask your search engine for hundreds of tutorials.1
This figure shows some of the many Markdown cheat sheets you won't be using.
As noted above, you will need a working copy of LaTeX, and a basic POSIX environment to compile the document from m4 to PDF or HTML.
Copy the makefile from this project directory (i.e., the manual subdirectory of the MMS) to your project directory. It has to be named makefile or Makefile. Open the makefile in your text editor and read the notes on setting the configuration variables.
When you are ready to compile the document, type make to generate the PDF, make html to generate the HTML, and make html push to generate the HTML and push it to Github.
It relies on a lot of search-and-replace via sed, m4 for the above fixes, and a few other hacks. The bibliography is generated via BibTeX and then a sed script converts it to HTML.
1. Footnotes are also available,
although, outside of law reviews, editors typically discourage them. Click the footnote
number to get back to where you were in the text.
[klemens:modeling] Ben Klemens. with Data: Tools and Techniques for Statistical Computing. Princeton University Press, 2008.
[klemens:tea] Ben Klemens. Tea for survey processing. In of the Conference of European Statisticians UNECE12.
[UNECE12] of the Conference of European Statisticians, Work Session on Statistical Data Editing, September 2012. United Nations Economic Commission for Europe.