-
Notifications
You must be signed in to change notification settings - Fork 55
Answers to common questions about MultiMarkdown. Contributions welcome!
On the Mac, you can choose from using an installer to install the program and required library for you, or you can compile it yourself from scratch. If you know what that means, follow the instructions below in the Linux section. Otherwise, definitely go for the installer!
Go to the downloads page to get the installer.
The easiest way to get peg-multimarkdown running on Windows is to download the
precompiled binary from the downloads page. There's a bat file you can run
that will move the included dll files, the executable, and a couple of
convenience scripts to C:\WINDOWS\system32. If there's an easy way to make a
proper installer, I am open to the idea, but only if it's pretty easy to do
(preferably from the command line!). Also, if I should be installing these
files somewhere else, please let me know.
If you want to compile this yourself, you do it in the same way that you would install peg-markdown for Windows. The instructions are on the peg-multimarkdown wiki. I was able to compile for Windows fairly easily using Ubuntu linux following those instructions. I have not tried to actually compile on a Windows machine.
(For those who are interested, I actually created an EC2 instance on Amazon and installed the necessary software to compile. It was pretty easy and probably cost me $0.02...)
Once you have the binary compiled, you can use the windows-installer branch
and the make installer command to package the files in the
windows_installer directory into a zip file for use as a make-shift
installation package.
The easiest way is probably to compile it yourself. You need to have glib2
installed. For example, on ubuntu:
sudo apt-get install libglib2.0-dev
For other linux distributions, you will need to do something similar.
On Mac OS X, please note that you will need to install the Developer Tools. You then need to install a few libraries. I used homebrew:
brew install pkg-config glib gettext
You can also use fink or something similar (though this caused some machine architecture incompatibilities):
fink install glib2-shlibs glib2-dev
Once you have the libraries installed, you can either download the source from peg-multimarkdown, or (preferentially) you can use git:
git clone git://github.com/fletcher/peg-multimarkdown.git
Then, simply run make to compile the source. You can also run some test
commands to verify that everything is working properly. Of note, it is normal
to fail one test in the Markdown tests, but the others should pass. You can
then install the binary wherever you like.
make
make test
make mmdtest
make latextest
If you're on a Mac, and want to make your own installer, you can run make installer if you use the mac-installer branch of the github project. Then
open the Make OS X Installer file and build the installer using the
PackageMaker application.
The syntax of MultiMarkdown can be a challenge for beginners especially when it comes to using Table and Link syntax. The challenge comes in understanding how it looks after the conversion.
For Mac users, you can download a free program NValt http://brettterpstra.com/code/ that contains a preview mode. Thus, you can enter your markdown with a dynamic preview window to show how the formatting appears. I've found this useful until I was comfortable with the syntax.
Note also that MultiMarkdown can also be installed to MarsEdit http://red-sweater.com/marsedit/ which also has a preview mode. This is even more effective for for bloggers as it will handle inline image upload to most popular blog software and display the interpreted output of your MMD syntax.
--I don't know of any Windows software that does the same--
For absolute beginners to Markdown, you may want to try http://peg.gd/ which provides a web site for writing in Markdown syntax and display. You can also save the pages for forwarding to other people.
For the reverse requirement, you can visit http://heckyesmarkdown.com/ which will attempt to take a given HTML Page and convert it into Markdown, usually with good accuracy.
There are a number of programs available for use on the iPhone and iPad that support regular Markdown, but not MultiMarkdown.
Elements is a iPhone / iPad app that also has a markdown preview mode. Second Gear has also made MarkdownMail which is simpler, but also very usable for learning Markdown.
Textastic is a syntax highlighting text editor for the iPad that includes a preview mode for Markdown. It will even preview MathJax equations if you include the proper metadata!
Now that MultiMarkdown is available in C (as of version 3.0), I would like to work on modifying it to work with iOS.
divide and conquer
latest version?
-
is error reported
- github issues
- discussion list
-
verify syntax is correct
-
make sure starting with plain text file (from Scriv, etc)
-
test command line to look for error messages
-
check output
-
recursive halving
-
how to submit error report
- need minimal example
- your output
- expected output
- best way is github
-
Join the MultiMarkdown Discussion Group on Google Groups. You can ask questions of other MMD users and contribute to discussions of MMD's future.
-
Try searching on Fletcher's website
XSLT
Latex Input files
- How do I submit a feature request
- my philosophy on new features
- avoiding feature-bloat
- can it be done with existing setup
- how does raw source look
- how many people will use it
flow chart?
- Difference between MMD 2 and MMD 3
- xslt vs not
- repeated metadata doesn't overwrite
- metadata and Latex
github
RTF
google docs
mac - textutil
xslt
OPML
linking to images
(figure-1 and figure--1 incompatibility)
Difference in footnotes
What is a PEG
mmd_merge
Ideas for development:
-
multimarkdown support in github wiki (gollum/sinatra)
-
embedd support for cross-platform xslt processing libxslt
-
editing the multimarkdown library code to be iOS compatible - replace GString and GSList with Cocoa variants.
-
memory leaks
-
RTF export --- I will probably not develop this myself, but am willing to include it if someone else contributes. Instead, I will work on OpenDocument support, and then you can convert from OpenDocument to RTF if necessary.
Anything placed in an HTML comment will be passed along unaltered - this can include raw LaTeX code. For example:
This is raw LaTeX: <!-- e^{i \cdot \pi} = -1 -->
will generate:
This is raw LaTeX: e^{i \cdot \pi} = -1
This is still a "beta" feature and is not perfect. Please let me know when you have trouble.
First - the vast majority of the time, this is not really a MMD problem, but rather a LaTeX problem, or (honestly) user error. Very occasionally, there are instances where MMD produces invalid LaTeX output when given unusual input, but these are rare.
First, if you are having problems with a more "complicated" MMD tool (such as
the TextMate bundle, or the Drag and Drop versions), use the command line
approach when you are really having difficulties. See if your document will
compile to HTML using the MultiMarkdown.pl utility. Once you've got that
working, try moving on to LaTeX, and then a PDF (if that's your goal).
If that doesn't work, you need to track down the source of the error. The best approach is similar to the old program Conflict Catcher. Keep dividing your document into halves, and test each half. One half will likely compile without complaint, and the other won't. Take the problem half, and repeat this process until you are able to find the paragraph, sentence, word that causes the error.
Using a real text editor (e.g. TextMate), examine the trouble section and make sure to view the invisible characters, and look for something odd. If you can't do that, you can also delete the faulty sentence and retype it (don't copy and paste --- you'll simply replicate the problem).
If none of that fixes your problem, post the problem section to the MultiMarkdown Discussion List and you will likely find out what you're doing wrong. Or perhaps you found an error and I will fix it. ;)
You are using an automated tool to create "complete" content. The tool is
adding the format: complete metadata for you, but you don't have any other
metadata in your document.
Start your document with a blank line to indicate that there is no more metadata.
Because that's what I use, and because Platypus made it really easy to create a GUI for a shell script.
Anyone is welcome to create something similar for any OS they choose.
Several users have written with suggestions for additional syntax for tables in order to allow cells to span multiple rows, to allow the MMD source for a single table row to span multiple text rows, etc.
My concern here is that the table should be easily understood in plain text, without too much markup. Ideally, there would be no markup, but it's just too complicated to have MMD figure out what the layout means.
I welcome suggestions, but I plan to be somewhat strict on this one.... And remember, for complex tables you can always enter the raw HTML.
This is less likely to happen, but it seems that adding some sort of basic syntax to manage forms would be pretty easy, and not very intrusive. Something like:
Please check all that apply:
[ ] Option A
[ ] Option B
[ ] Option C
Please choose one of the following:
( ) Option A
( ) Option B
( ) Option C
Please enter your first name:
[_______________________]
The idea would be to allow you to easily enter the necessary fields for a form, but not have to be concerned with the HTML nonsense.... As always, input welcome.