Home → Problems (v2) →

Suggestions for Pro Features

• Edit

chuck

31 Dec, 2015 07:22 PM

Hi there,

We have been using MultiMarkdown for the past couple years to produce user documentation for the software produced by The Omni Group. Our primary authoring tool has been BBEdit, and we use the mmd command-line utility to convert to HTML and then produce in-app documentation and EPUB for distribution on the iBooks Store.

We started using the MultiMarkdown Composer v3.0 beta a few weeks ago, and can already see the promise it holds, but there are some features I wouldn't mind seeing added, potentially as Pro-level features. Here's my list:

Native EPUB3 Export In the current MMDC3 beta, when you export to ePub, the OPF file specifies EPUB Version 2 and refers to an NCX file for generating the TOC. While this provides backwards compatibility for older readers, there are lots of things that publishers (big and small) can benefit from with the EPUB3 format. For example, EPUB3 lets you specify a date/time string for creation of and modifications to an EPUB. You can also specify version numbers in the OPF header. I guess what might be helpful when exporting to ePub, would be the ability to choose between EPUB2/3 (i.e., OPF + NCX) or just straight up EPUB3 (OPF + nav file for TOC). In addition to that, it would be great to have an OPF metadata editor that appears when you first create a new document and is also available as a HUD. This would allow the user to enter basic information about their document/book at the start, and then go back and further tweak that later as the project evolves.

Multi-File Projects I have been using BBEdit to author MMD. In BBEdit, you can create a Project (File > New > Project), which creates a .bbprojectd folder/directory in which you can have multiple text files. This is great for working on a book, where you have separate MMD files for each chapter. When you open a Project file in BBEdit, the files for that project show up in a sidebar, and you can switch between the different files and add other resources such as images and CSS, to keep everything in one place. Would love to see this level of support brought to MMDCv3 as a Pro feature.

Bundled CSS Support In the MMD header, I can specify a custom style sheet, which is great, but when I export to EPUB, that CSS doesn't get bundled with the book. This forces me to crack open the bundle, edit the OPF file, and then add the CSS manually. Why? Images referenced in the MMD file are included; why not the CSS? It would be great if, when exporting to EPUB, that MMDC3 could include the user-specified CSS, just as it does with image files.

Speaking of Image Files... Would it be possible to, when exporting to EPUB, run the images through a compression algorithm, such as TinyPNG (tinypng.com)?

Process MMD within HTML When Exporting I use TextExpander to drop in HTML bits for things not covered by MMD. This is just the basic HTML tagging structure (say, for example, a <div> item such as a note or sidebar that gets styled and presented differently), but then I fill in the content as regular MMD. In the latest beta (3.0b41), all of that is just ignored.

Thanks for listening; please keep up the great work. Happy to discuss further if you'd like.

Chuck Toporek
Documentation Wrangler, The Omni Group • Seattle
[email blocked]

1. Support Staff 1 Posted by Fletcher on 02 Jan, 2016 01:48 PM

   

   Chuck,

   Thanks for writing in (and it's great to hear that my software is used
   at Omni!!!! I use at least one of your products almost every day!)

   EPUB3 -- When I last messed around with EPUB, v3 was not out, or at
   least not well supported. I do need to look back at it, especially
   since MathML is (at least sometimes) supported in v3. Not sure about
   the EPUB-specific HUD -- the way to do that might be a template for your
   source document that prefills metadata at the top (e.g. TextExpander).
   We'll see.

   Multi-File Projects -- I've got something for this on the back burner
   that I want to get back to for the Pro version.

   EPUB/CSS -- this can be done.

   Image compression -- this is probably outside the scope of what I'll be
   doing.

   MMD within HTML -- can you send me an example of what doesn't work? MMD
   works within HTML elements with the 'markdown="1"' attribute.

   Fletcher

   • Edit

2. 2 Posted by chuck on 25 Jan, 2016 06:49 PM

   

   Hi Fletcher,

   Apologies for the delayed response; we've been rolling updates and I was on vacation for a bit after the New Year.

   Happy to have a separate conversation with you about EPUB3, if you'd like. We've been relying heavily on that for our docs, particularly the bits needed to deliver our books through the iBooks Store. There are a few additional things you need to do to the OPF file for iBooks, and we rely on the bookid (in lieu of an ISBN) paired with metadata timestamps to deliver updates.

   Here's the blob of mixed MMD/HTML that I mentioned earlier:

   Tip
   If you press **Control-Command-0** (that's a zero, not a capital O), OmniGraffle resizes the Canvas view so that the entire diagram fits in the window. This comes in handy for trying out the Layout Types in the popup menu, because OmniGraffle redraws and rescales the objects on the canvas for you. You can just select a Layout Type, adjust the object spreads, and then kick back and watch the drawing engine do its thing.

   If you did not have **Auto layout** turned on in the Diagram Layout inspector, you would need to click **Lay Out Now** in the inspector to see the changes you've made.

   I've attached a screenshot of what this looks like in MMDC (b42), and how it appears in an Exported EPUB. It looks like the MMD tool sees the HTML block and skips past any MMD within the block.

   Thanks,
   Chuck

   • mmdwhtml.png 178 KB
   • mmdwhtml_ibooks.png 92.5 KB
   • Edit

3. Fletcher closed this discussion on 19 Sep, 2017 05:48 AM.