MMD and good long-document solutions for HTML and PDF?

[tra...@gmail.com]

Forum,

Overall noob to MMD -- I appreciate your reply in advance, even if just a link to "check this out…"

Desire:  To create a long (100-page) manual (images, citations, and equations) that could both be published to the web and to a PDF (for offline download). Would be ideal if links to footnotes and sections/chapters worked, particular on web.  Since the document is big, also would prefer to publish multiple HTML pages, not one long one. Content creator is capable/technical, but still need simple solution for others on small non-profit team.  Sort of have a single MMD document in mind, especially since sections and figures would be correctly/dynamically numbered (ie. eBook theme below).

Examined:

- mmd CMS (but no PDF and not sure about "easy" publishing overall)

- Marked for making the PDF.  Formats chapters well (using eBook theme) and auto-numbers figures and sections. Great!

- HTML export from MMDC or Marked.  No way to have multiple webpages.  Was hoping for a simple feature to Marked that allows H1 or <hr> to indicate a new HTML file.

- nvALT - looked at this for plain text website, but also likely not going to be a create solution.  PDF?

- Tried Marked's version of MMD merge to make multiple MMD files into a single PDF.  Not sure if it really changes things from a single PDF, other than modular editing.  Also not sure about how to make cross-ref links; and still only get one HTML file.  (might have missed something here.)

The manual gets updated relatively frequently, so we'd like something where edits were easy to push out to both HTML or PDF.

I think if there was a way to do a great HTML solution, we'd either hand-make the PDF and/or realize that we don't need PDF and just provide the HTML for offline use.

I feel that there could be some great 'flag' or tool that would force '---' to be a new HTML page, and handle on the internal and x-page links, but that is likely pushing MMD out of its "simple" zone.

Thanks again in advance,

Travis

[Sherwood Botsford]

I use a combo of template toolkit +  the perl version of MMD for creating web pages.  TT2 has an include facility.  So it should be possible to create a separate file for each html page, then create a master TT2 file that includes all of the files one after another to pipe into PDF.

A printed version of the HTML file is less useful than you'd think because it lacks page numbers, or the page numbers will vary according to how it was printed.  (Screen size, browser used, OS used all affect how it's paged.)  Ideally you need a system that has working hyper links in the online version, and working page references/footnotes/end notes in the printed version.

In passing:  At a level probably more than Fletcher wants to put into MMD there is a serious need for a package that can make good printed manuals and good online versions using a common source tree.  Probably text + markup is NOT the way to go with this, as it would require too many extensions to MMD.  However some of the spirit of MMD could be useful if the markup were used as keyboard shortcuts and an alternative to constant mousing about.

FWIW  the two packages that were formerly used for this for large documentation projects were FrameMaker and Interleaf.  FM is not well supported (is it at all?) by adobe, and apparently has just awful code and some interesting bugs.  FM allowed you to assign HTML tags to their onboard paragraph and character styles.  It was clunky at the best of times. I don't know the present status of Interleaf right now, but at one time it was a markup language not much more friendly than TeX.  Both packages were unreasonably expensive.  I have used the FM version that Adobe released as a beta for Linux.  I quite liked it, as the equation editor was built in, had good keyboard shortcuts to all the mousing about. I preferred it to MS Word, as it handled numbering much more neatly.  It did not have the quality of typography as *TeX, but it was a lot easier to use, and for multi-column layout was much easier to learn.  (E.g. putting 4 columns of algebra drills on a single page.)  I've not used Interleaf, but the people I knew who did spoke about a learning cliff, as opposed to a learning curbe.

Respectfully,

Sherwood of Sherwood's Forests

Sherwood Botsford
Sherwood's Forests --  http://Sherwoods-Forests.com
780-848-2548
50042 Range Rd 31
Warburg, Alberta T0C 2T0

--
You received this message because you are subscribed to the Google Groups "MultiMarkdown Discussion List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to multimarkdow...@googlegroups.com.
To post to this group, send email to multim...@googlegroups.com.
Visit this group at http://groups.google.com/group/multimarkdown.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[TJ Luoma]

On 1 Jul 2013, at 10:14, tra...@gmail.com wrote:

> I feel that there could be some great 'flag' or tool that would force
> '---' to be a new HTML page, and handle on the internal and x-page
> links, but that is likely pushing MMD out of its "simple" zone.

I can't comment on the rest of this, but it seems to be that this could
be accomplished via CSS, setting "page break after" for "<hr />"

Then it's just a matter of finding an HTML-to-PDF conversion tool which
properly supports it.

TjL

[Sherwood Botsford]

Different meaning of 'page' here.  New HTML page means output stops going to foo_02.html and starts going to foo_03.html.  Page break means stop writing on page 17 and start at the top of page 18.  

The CSS solution could be used to force pagination within the print version of a single html document.  It could not be used to force the creation of a new html document.

Respectfully,

Sherwood of Sherwood's Forests

Sherwood Botsford
Sherwood's Forests --  http://Sherwoods-Forests.com
780-848-2548
50042 Range Rd 31
Warburg, Alberta T0C 2T0

--
You received this message because you are subscribed to the Google Groups "MultiMarkdown Discussion List" group.

To unsubscribe from this group and stop receiving emails from it, send an email to multimarkdown+unsubscribe@googlegroups.com.

[tra...@gmail.com]

Actually, the mention of CSS prompts me to write a bit about what I have found, and been impressed with, in my search:

Marked.app includes a 'style' (CSS) called 'eBook' and does some pretty cool stuff with CSS (that I didn't know possible).  

1) It does help with printing and section breaks, putting new sections and chapters on different pages (I think this is CSS and not a Marked.app feature in #3).

2) It uses CSS 'counters' to number Sections, Chapters, Figures and Tables.  Very LaTeX liked and works very well.  Figure 3-1 is the first image in Chapter 3.  Perfect.

3) Marked.app includes an feature that forces <H1> and <H2> as Page Breaks (and optionally to interpret '---' <hr> as a page break).  

So...

Pros: auto numbering, easy markup, flexible, ability to export to HTML, and reasonably formatted (page breaks) PDF.  CSS is flexible so can tweak style readily.

Cons: Single file/page HTML; links (e.g., footnotes) broken in PDF. No page numbers in PDF.

Discovering that Marked.app and the eBooks style got me so close, I was hoping that there was an app like Marked that would interpret '---' or <hr> and force new *.html files, and handle linking.  That isn't a small task, but it seems reasonably straight-forward for app/script to do (especially since Marked.app demonstrated some proof of it working already).  And it would be a bonus that MMD wouldn't have to be updated since this would be handled by a separate app.

T

On Monday, July 1, 2013 2:44:55 PM UTC-4, Sherwood Botsford wrote:

Different meaning of 'page' here.  New HTML page means output stops going to foo_02.html and starts going to foo_03.html.  Page break means stop writing on page 17 and start at the top of page 18.  

The CSS solution could be used to force pagination within the print version of a single html document.  It could not be used to force the creation of a new html document.

Respectfully,

Sherwood of Sherwood's Forests

Sherwood Botsford
Sherwood's Forests --  http://Sherwoods-Forests.com
780-848-2548
50042 Range Rd 31
Warburg, Alberta T0C 2T0

On 1 July 2013 12:06, TJ Luoma <luo...@gmail.com> wrote:

On 1 Jul 2013, at 10:14, tra...@gmail.com wrote:

I feel that there could be some great 'flag' or tool that would force '---' to be a new HTML page, and handle on the internal and x-page links, but that is likely pushing MMD out of its "simple" zone.

I can't comment on the rest of this, but it seems to be that this could be accomplished via CSS, setting "page break after" for "<hr />"

Then it's just a matter of finding an HTML-to-PDF conversion tool which properly supports it.

TjL

--
You received this message because you are subscribed to the Google Groups "MultiMarkdown Discussion List" group.

To unsubscribe from this group and stop receiving emails from it, send an email to multimarkdow...@googlegroups.com.

[TJ Luoma]

On 1 Jul 2013, at 14:44, Sherwood Botsford wrote:

> Different meaning of 'page' here. New HTML page means output stops going
> to foo_02.html and starts going to foo_03.html.

That's a new file, not a new page.

TjL

[Jeff McNeill]

Try Pandoc. I have a similar workflow and need ebook, pdf, and php-markdown-extra-compliant code in one place. Either MultiMarkdown Composer or Sublime Text 2 for the editor, Pandoc for the robust converter (Marked is also fine for quick conversions). With the exception of some LaTeX code to mark up specific fonts for PDF output (I have Thai script in some documents), everything else works great across all converted formats.

[tra...@gmail.com]

Jeff,

Thanks for the recommendation.  I've heard of pandoc and will more deeply at it.

To help me understand your workflow, could you describe how you markup your doc to get it in separate HTML files?  I generally understand ebook and PDF (used LateX before), but the workflow to export a large MMD document as a structured, reasonable sized, and linked website still has me perplexed.  Thanks.

T

[Philip Davis]

Several people in this discussion thread have mentioned using the "eBook" theme in Marked. I have the latest version (1.4.3) of Marked and can't find this theme. I did some searches and poked around on the Marked website and Knowledge Base with no luck. Can someone point me to a link to obtain it? 

Thanks!

[Jeff McNeill]

Hello,

Pandoc can create an ePub document from a single Markdown document and generate unique HTML files for each chapter (marked up as H1) (see ePub format for more about the structure). However, I am unclear if this can be done separately as Markdown to HTML. I've looked and can't find that option (though it could exist). The simple approach would be to have each HTML page as a separate Markdown file, and access the files in some way so it is easy to traverse them (such as Sublime Text or MultiMarkdown Composer or Scrivener).

For me, I use Wordpress as the content management for the web, and I can copy and paste the markdown text into separate web pages, and use the php-markdown-extra plugin which takes care of all the formatting I need.

Hope this helps.

Sincerely,
--

Jeff McNeill 

http://jeffmcneill.com 

+66 80 673 1438

--
You received this message because you are subscribed to a topic in the Google Groups "MultiMarkdown Discussion List" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/multimarkdown/1Yb1G1HfYjI/unsubscribe.
To unsubscribe from this group and all its topics, send an email to multimarkdow...@googlegroups.com.

[Kris Shaffer]

Travis et al.,

I do something similar with my course materials, and the workflow may be helpful to you.

I have an online "textbook" (really just prosey lecture notes) hosted on GitHub. GitHub uses Jekyll and Maruku (*not* MMD) to convert markdown files to html, using html template files and css stylesheets. I use a very simple theme (you can fork the basic template from github.com/kshaffer/GHbook and see it in action at kris.shaffermusic.com/musicianshipResources). Each "chapter" is a separate markdown file, and GitHub automatically uses Jekyll to generate a separate html page for each in the final website. The index page is a TOC (just use .html instead of .md to link to files). MultiMarkDown-CMS follows a similar process, using different tools.

​To make a PDF version of such a website, I manually concatenated those markdown files and adjusted headers appropriately. However, I imagine that one could easily start with a markdown file for each page's content, and separate files that contains the GitHub-friendly and LaTeX-friendly headers. A simple shell script should be able to produce a single markdown file from all of those to run through LaTeX for a PDF, and another would append the content to the GitHub headers to make the markdown pages for the website. That would allow one to use a single set of markdown source files and spit out both PDF and multi-page website versions. I haven't done so yet, but I'll be writing said scripts later this summer or early this fall (unless someone beats me to it and shares them!).

​In theory, this should allow the same source files to be used for epub creation. 

​I hope that helps, and I look forward to hearing what you settle on.

​Best, 

Kris Shaffer, Ph.D.
Instructor of Music Theory
University of Colorado–Boulder
kris.shaffermusic.com
Twitter: @krisshaffer

You received this message because you are subscribed to the Google Groups "MultiMarkdown Discussion List" group.

To unsubscribe from this group and stop receiving emails from it, send an email to multimarkdow...@googlegroups.com.

[Fletcher T. Penney]

I actually had the same question.

Perhaps they meant my eBook theme that is part of MultiMarkdown Composer?

F-

-- 

Fletcher T. Penney

flet...@fletcherpenney.net 

[tra...@gmail.com]

Yes, sorry.  Thank you for the correction.  It is the eBook theme/style in MMDC.  I was mixing and matching workflows and got confused.

Fletcher, it is great.  I haven't really dug into advanced CSS features but it is pretty cool to have dynamic figure/section/table numbering. For those looking to do similar types of CSS wizardry, I found more info here:

http://www.w3.org/TR/css3-gcpm/

A little off-topic, but might help me craft a possible solution for HTML files: Is there a way to start a counter at an arbitrary number?  I see 'counter-increment' and 'counter-reset', but no 'counter-set'.  I'm wondering if I broke out my chapters/sections into separate HTML files, if I could get the auto numbering to be the same as a single HTML file.  (So file5.html would be Chapter 5, and the CSS counter would start at 5 for that file.)

T

[Fletcher T. Penney]

There is a lot more to CSS 3 and the advanced features than what I included, but I am definitely not an expert.  I just started searching around with Google to see what I could find.

For the browsers that support the advanced page size features, e.g. Chrome, you can do some further cool stuff.

F-

-- 

Fletcher T. Penney

flet...@fletcherpenney.net 

[tra...@gmail.com]

To answer my own question, I came up with the correct search terms and found my answer.  You can start CSS counters at any number using 'counter-reset'.  Syntax is similar to:

counter-reset: counterName -1;

or 

counter-reset: counterName 5;

'counter-reset' is typically called without a value, which implies a '0' (zero).

t

[David Sanson]

Pandoc does not have an option to split a document into multiple HTML files based on headers. But it can convert markdown to texinfo, and texi2html is good at doing just what you want.