# Hemingway [![Build Status](https://travis-ci.org/griffinmyers/hemingway.png?branch=master)](https://travis-ci.org/griffinmyers/hemingway) Hemingway can translate a very rigid subset of LaTeX commands into HTML markup that can then be styled at the user's whim. The parser was created using Treetop, so it might be useful to consult the [Treetop Documentation](http://treetop.rubyforge.org/syntactic_recognition.html) to learn more about the inner workings. Throughout you'll notice this character: `\\`. This is the string represntation of the `\` character. So if your latex is coming from a file you would just write `\emph{wookies}`, and if it were programatically coming from a string you would write `\\emph{wookies}` ## Installation Add this line to your application's Gemfile: ```ruby gem 'hemingway' ``` And then execute: $ bundle Or install it yourself as: $ gem install hemingway ## Usage First, instantiate the parser. ```ruby parser = Hemingway::Parser.new ``` Next, chuck some Latex markup into it. ```ruby result = parser.parse("do, or do not, there is no \\emph{try}") ``` Finally, convert the result to html markup. ```ruby markup = result.html ``` If something goes really wrong, the parse method will return `nil`. If that's the case, you can say something like ```ruby parser.failure_reason ``` to figure out what happened. `Hemingway::Parser` is a delegator for a Treetop parser, so check out the [Treetop Documentation](http://treetop.rubyforge.org/syntactic_recognition.html) to see what other useful methods you can use in case of something going wrong. ## Supported Syntax Here is a breakdown of supported latex and its markup equivalent. In most examples, I only show the interesting bits of conversion. Note that at the top level, everything is wrapped in ```html
``` but I'm omitting that detail from the examples for brevity. Throughout this, the `:` operator simply says the LHS maps to the RHS. ###### Newlines Delimits paragraphs ```html wookie\n\nbreakfast :

wookie>

breakfast

``` ###### Tags Adds inline styling ```html That’s no moon, \\emph{it’s a space station.} : That’s no moon, it’s a space station. \\textbf{The Force} : The Force \\texttt{R2-D2} : R2-D2 \\textsc{Death Star} : Death Star ``` Or some vertical padding ```html \\vspace{5mm} :
``` ###### Maths Adds math symbols ```html $\\Gamma$" : Γ $\\Delta$" : Δ $\\Theta$" : Θ $\\Lambda$" : Λ $\\Xi$" : Ξ $\\Pi$" : Π $\\Sigma$" : Σ $\\Upsilon$" : Υ $\\Phi$" : Φ $\\Psi$" : Ψ $\\Omega$" : Ω $\\alpha$" : α $\\beta$" : β $\\gamma$" : γ $\\delta$" : δ $\\epsilon$" : ε $\\zeta$" : ζ $\\eta$" : η $\\theta$" : θ $\\iota$" : ι $\\kappa$" : κ $\\lambda$" : λ $\\mu$" : μ $\\nu$" : ν $\\xi$" : ξ $\\pi$" : π $\\rho$" : ρ $\\varsigma$" : ς $\\sigma$" : σ $\\tau$" : τ $\\upsilon$" : υ $\\phi$" : φ $\\chi$" : χ $\\psi$" : ψ $\\omega$" : ω ``` One can also exponentiate something by using math mode: ```html December 7$^{th}$ :

December 7th

``` ###### Special Characters ```html \\# : # \\$ : $ \\% : % \\& : & \\_ : _ \\{ : { \\} : } ``` ###### Blocks You can make lists with `itemize`, `description`, or `enumerate`. ```html \\begin{itemize}\\item Wookie \\item Jedi \\end{itemize} : \\begin{enumerate} \\item Frodo \\item Sam \\end{enumerate} :
  1. Frodo
  2. Sam
\\begin{description} \\item Ginger-Nut \\item Turkey \\end{description} :
Ginger-Nut
Turkey
``` Add labels to a list with `\item[label]`: ```html \\begin{itemize}\\item[bros] before hoes \\item \\n [chicks] before dicks \\end{itemize} : \\begin{description} \\item [Frodo] Intrepid Adventurer \\item [Sam] Faithful Companion \\end{description} :
Frodo
Intrepid Adventurer
Sam
Faithful Companion
``` Go ahead, nest lists in all sorts of interesting ways. No reason you couldn't chuck some empahsized text in a label either. Enter in preformatted text: ```html \\begin{verbatim} don't we \n \n all wish \n \n for a little sleep? \\end{verbatim}") : 
don't  we  \n \n all wish \n \n   for a little sleep?
``` ###### Footnotes Putting in a bunch of footnotes inline with your content is an awesome idea. All footnotes within an entry will be yanked out, linked with an anchor tag, and placed after all paragraphs in the entry. Naturally you can put just about whatever you want in a footnote (save another footnote). I might have made a bad assumption here and used the `` tag for the footnote number because it assumes formatting, something I've been trying to avoid. If you'd like that assumption removed, you're just a pull request away. For example this latex markup: > So we met up with Han and saw his ship, The Millennium Falcon\\footnote{a total piece of junk}. I had no idea how that thing was supposed to get us to Alderaan\\footnote{location of the \\emph{hidden rebel base}}. > On board we found homely accommodations including a Dejarik\\footnote{much like chess} set that I indulged in with Chewbacca\\footnote{Han's carpety first mate}. Renders to this html: ```html

So we met up with Han and saw his ship, The Millenium Falcon1. I had no idea how that thing was supposed to get us to Alderaan2.

On board we found homely accommodations including a Dejarik3 set that I indulged in with Chewbacca4.

1a total piece of junk
2location of the hidden rebel base
3much like chess
4Han's carpety first mate
``` And looks like this:

So we met up with Han and saw his ship, The Millennium Falcon1. I had no idea how that thing was supposed to get us to Alderaan2.

On board we found homely accommodations including a Dejarik3 set that I indulged in with Chewbacca4.

1a total piece of junk
2location of the hidden rebel base
3much like chess
4Han's carpety first mate
I've added a timestamp onto footnote hrefs and ids to make the unique incase you are parsing multiple entries on a given HTML document. ###### Block Quotes Pretty standard. You can put anything in there except a footnote. That seemed excessive. ```html \\begin{quote} Have you guys ever heard the song \\emph{Blow} by \\emph{MILF}? \\end{quote} ``` maps to ```html

Have you guys ever heard the song Blow by MILF?

``` ###### Centering Text ```html \\begin{center} Dromiceiomimus \\end{center} :
Dromiceiomimus
``` ###### Inline Right Justification ```html The love, \\hfill Will ``` maps to ```html The love, Will ``` ###### Horizontal Rules ```html \\neatline :
``` ###### Accents ```html Charm\'{e}e de vous voir. Je suis tr\`{e} contente de vous voir. : Charmée de vous voir. Je suis trè contente de vous voir. ``` ###### Overrides Some characters need a little help. ```html --- : "—" `` : "“" '' : "”" ``` ## Contributing 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Write and run tests (`script/test`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request