Pandoc -- write once, display documentaiton anywhere.

Pandoc is a fantastic tool that converts common markup languages like: LaTeX, markdown, html, groff, mediawiki, in to one another. It also helps you export them to PDF, HTML, docx, rtf, with a single command.

The command for it couldn't be simpler:

pandoc <inputfile> -o <outputfilename>.<output_ext>

My Trial

I am writing a short piece of documentation about an API I built with the requirement that readers be able to:

• access the information on a web page
• save the API as a download or print it for easy reference
• open it on an e-reader (Why kill trees if you don't have to? Unless you're a sadist...)

As an additional requirement, I wanted to be able to quickly and easily edit the original. (This throws LaTeX out: \command{ICan'tremember} \command_toEnd{THATcommand})

Here are the images of what I ended up with, all coming from one source file, and that single command being repeated with different extensions:

Epub Output

The epub output looks great, and reflows nicely. Additionally, handy little links are put in for easy navigation, and a table of contents is created. My only dislike comes with the fact that a blank title page is added (probably because I didn't use the syntax for adding a title). One would assume if the document didn't have that appended, no title page would be added.

HTML

HTML with 20 lines of custom CSS

 The HTML output looked very nice on the surface, and I was very pleasantly surprised that when I opened up the source, all of the tags had attached classes, so building a style-sheet was a breeze!

PDF

PDF -- looks eerily like Pandoc converted it to LaTeX first

The PDF command performed well, links are click-able, and the document had a very nice table of contents. However, it looks like the text was first converted to LaTeX before being exported, due to the general styling (or perhaps this is what PDFs look like by default). Good thing I like it, the text doesn't stretch so far to be unreadable, and the spacing is nice.

Summary

Pandoc is a great little tool for document converstion and export, and makes a wonderful addition to any toolkit.

One of the better features, I imagine, if you have lots of old documentation is being able to convert that to newer representations through it's conversion command:

pandoc -f html -t markdown http://www.fsf.org

It also does tables, math rendering, and automatic citations.

Making a better Find and Replace

I've been questioned several times why I use geany the project is old, lacks tons of features and features to make it easy like eclipse, and isn't built in like vi, or gedit.

The reason I use it is an unparalleled find and replace dialog that simply works as you'd expect it to:

The dialog is simple, a search and replace field where you can replace things over the document, or if you want, you may replace over all open windows, or the selection if you expand the "replace all" tab.

You can also use escape sequences to quickly replace things like tabs or newlines, or turn them off to replace escape sequences in lines of code.

Gedit's replace dialog is a little more sparse, not allowing you to replace the current selection (something that is incredibly useful), like when one block of code has a duplicate variable name but you don't want to replace it over the whole document.





Eclipse is an entirely different story. Unlike a normal find and replace, it isn't brought up with a control + h, but instead a control + f (what is normally just find, control + h just brings up a search dialog) The "Selected Lines" radio button doesn't always work either.



I'd like to suggest a few improvements to all of these dialogs too.

• Show the users all options, but hide complexity by discoloring buttons that don't apply (like
• Use a menu that looks the same for find and replace.
• Kill off the "close" button, everyone knows to do this using the "x" (unless the dialog doesn't have one, in which case it shouldn't be inline with the other buttons)
• Don't use radio buttons for boolean choices, they waste space
• Don't have a simple replace button, it disturbs the workflow.
• Don't have a choice for wrap-around, rather notify the user in an unobtrusive way they've reached the end, such as a red bar that shows at the top of the dialog.
• Allow replacing in all open documents/selected areas
• Get rid of the labels in favor of text that disappears when the user enters something

Here is what I had in mind for find:






And replace: