From andrea.censi at dis.uniroma1.it  Sun Jun 10 05:06:06 2007
From: andrea.censi at dis.uniroma1.it (Andrea Censi)
Date: Sun, 10 Jun 2007 11:06:06 +0200 (CEST)
Subject: [Maruku-users] On extensions
In-Reply-To: <20070609222754.GA21619@cygnus>
References: <20070609222754.GA21619@cygnus>
Message-ID: <50041.83.211.5.223.1181466366.squirrel@posta.dis.uniroma1.it>


Aggelos Orfanakos wrote:
> Hello,
>
> I was thinking the other day: it would be really cool if Maruku
> supported plugins with hooks etc. (preprocess, postprocess, custom
> headers etc.). This way, plugins would be developed and the most useful
> ones could later be incorporated in the core.

Some hooks are already provided for parsing. For example, the parsing mode
for LateX math is provided as a plugin. The code is included by doing

    require 'maruku/ext/math'

In general, Ruby's open classes makes it very simple to add functionality.
In fact, the math 'plugin' add new internal elements (the 'equation'), the
code to render it to Latex and to HTML, and code for parsing it.

For example, this is the hook for parsing an equation:

	MaRuKu::In::Markdown::register_block_extension(
		:regexp  => EquationStart,
		:handler => lambda { |doc, src, con|
        ....

and this is for parsing "see \eqref(myeq)":

	# This adds support for \eqref
	RegEqrefLatex = /\\eqref\{(\w+)\}/
	RegEqPar = /\(eq:(\w+)\)/
	RegEqref = Regexp::union(RegEqrefLatex, RegEqPar)

	MaRuKu::In::Markdown::register_span_extension(
		:chars => [?\\, ?(],
		:regexp => RegEqref,
		:handler => lambda { |doc, src, con|
        ....

(see maruku/ext/math/parsing.rb)

> What do you think of this as an idea? Would it be hard to implement?

As you can see, some functionality is already present. I'd rather document
the existing one, than adding any other code. In fact, I think that the
current system covers all the needs.

As for things that *can* be strictly separated from Maruku (like
pre-process, transencoding, and post-process), they *should* be separated.

Best,
-- 
Andrea Censi

http://www.dis.uniroma1.it/~censi



From andrea.censi at dis.uniroma1.it  Tue Jun 12 05:20:52 2007
From: andrea.censi at dis.uniroma1.it (Andrea Censi)
Date: Tue, 12 Jun 2007 11:20:52 +0200 (CEST)
Subject: [Maruku-users] Maruku, webgen and ANSI output
Message-ID: <53762.83.211.5.223.1181640052.squirrel@posta.dis.uniroma1.it>

> All
> plugin documentation is/will be written in Markdown/Maruku and the
> user can show the documentation for a plugin on the command line.

Nice idea.

> And
> it would be super cool if Maruku could convert the documentation to
> something console friendly like ANSI (with colors, bold, underlining,
> etc.) Otherwise the documentation is just a big junk of text ;-)

May I suggest another (with less fun, but more efficient) way? Why don't
you use a conversion like the following:

   (Markdown) -> Maruku -> (HTML) ->  ???  -> (ANSI console)

where '???' is a tool that -- probably -- already exists?

Or, if '???' does not exist, it is very easy to write, and also useful
indipendently from maruku. You just walk the HTML tree, and output the
right ANSI codes before and after `<strong>`, etc. The only non-trivial
thing is taking care of line breaks. Plus, if one wants to be super-cool,
he could add some basic CSS support.

> Could you point out some places I have to look at to start writing
> such an output generator for Maruku?

Only if you tell me why don't you like the previous idea. ;-)

>ps. Generating PDFs from Markuku source currently requires LaTeX.
>However, Maruku generates an internal representation of the Maruku
>document, or am I wrong?

Right. That was a very good design decision.

> If so, it should be possible to use
> PDF::Writer to directly generate a PDF from Maruku source - any ideas?

I suppose it would be possible. I didn't know PDF::Writer. Because I was
proficient in LaTeX, I went that way.

(if you don't know LaTeX) Keep in mind that LaTeX is a very high-level
language. It has tables, bulleted-lists, sections. It supports
cross-referencing in PDF files (so internal and external links works).

I'm skimming through the PDF::writer manual. If you want to use
Maruku+PDF::Writer for technical documentation, maybe an interesting
thing (a first experiment), would be to translate

    (Markdown) --> Maruku  -->  (Techbook) -->  PDF::Writer --> (PDF)

where Techbook is a mini-format used by the PDF::Writer authors
themselves. (see chapter 10 of the manual).

My perception is the following: using PDF::Writer for Maruku would give
slightly inferior results in quality with respect to LaTeX, but would be
extremely fast, and more portable (not everyone has a LaTeX installation).

Plus, you are not the first to ask something similar. You see, a lot of
people want to convert Markdown to PDF dynamically ("save this page as
PDF"), and LaTeX is too slow for that. So, it would be certainly useful.

The killer app is to have a Markdown -> PDF export, AND having non-trivial
control over the appearance of the resulting document. For example, define
in a configuration file (using CSS maybe?) the spacing between elements,
colors, etc. But I don't have any idea of how to do this (except
implementing it from scratch).

So, to sum up: using PDF::Writer for writing PDFs would certainly be
useful, Maruku's architecture supports it nicely, but, unless one use a
trick like going through Techbook, it's a good amount of work (probably it
is more work than to write the HTML or LaTeX outputs).

-- 
Andrea Censi

http://www.dis.uniroma1.it/~censi