markdown markup

In the mdml docs, is it possible to lose the

markdown four-space indents for code blocks?

These start and end markers are rendered literally with John Gruber's
markdown processor, and have no effect on their content, so what you
get in the HTML is the two ~~~~~~~~~~~ markup strings, with nothing in
between.  Pandoc seems to grind away at them for a looooong time
before interpreting them as a nested series of strikeout spans (huh?),
and in the browser, for some reason nothing displays after the first
~~~~~~~~~{.xml} line.  Don't know what the deal is there, but it's
definitely not happy with it, and the pandoc HTML output, while
syntactically correct, is pretty hard on the eyes, so I haven't looked
further.

Four-space indenting of a code block encloses it in PRE tags in
standard markdown.  It works with all markdown parsers, requires no
extensions, and can be styled with CSS to produce indenting in the
output, if that's needed for prettier presentation.  The docs will be
more accessible if we can go that route in formatting the examples.

Frank

Please try:

$ pandoc -s -c screen.css -H header.html csl-spec.mdml > csl-spec.html

Bruce

Er:

$ pandoc --toc -s -c screen.css -H header.html specification.mdml >
specification.html

Bruce

In the mdml docs, is it possible to lose the

markdown four-space indents for code blocks?

These start and end markers are rendered literally with John Gruber's
markdown processor, and have no effect on their content, so what you
get in the HTML is the two ~~~~~~~~~~~ markup strings, with nothing in
between.  Pandoc seems to grind away at them for a looooong time
before interpreting them as a nested series of strikeout spans (huh?),
and in the browser, for some reason nothing displays after the first
~~~~~~~~~{.xml} line.  Don't know what the deal is there, but it's
definitely not happy with it, and the pandoc HTML output, while
syntactically correct, is pretty hard on the eyes, so I haven't looked
further.

Four-space indenting of a code block encloses it in PRE tags in
standard markdown.  It works with all markdown parsers, requires no
extensions, and can be styled with CSS to produce indenting in the
output, if that's needed for prettier presentation.  The docs will be
more accessible if we can go that route in formatting the examples.

Please try:

$ pandoc -s -c screen.css -H header.html csl-spec.mdml > csl-spec.html

Thanks. It’s still not happy, though. That runs faster and the
document doesn’t actually disappear in the browser, but all of the
examples are reduced to a single line, with a strikeout running
through it.

Frank

Odd; I’ve never seen that.

specification.html (83.9 KB)

Please try:

$ pandoc -s -c screen.css -H header.html csl-spec.mdml > csl-spec.html

Er:

$ pandoc --toc -s -c screen.css -H header.html specification.mdml >
specification.html

Okay. With this doc, I get very nice styling on the standard
markdown markup, but again it takes a veeeery long time for processing
to complete, and the browser displays nothing beyond a fragment of the
first ~~~~~~~~~{.xml} marker. Whatever it’s meant to do, pandoc
doesn’t like it.

What’s wrong with using the standard markup syntax?

This is only for the benefit of the spec author(s). When we’re done,
it will be published as HTML.

Pandoc offers the follow features that I consider valuable here:

  • customizable headers
  • syntax highlighting
  • automatic table of contents

I am not aware of any other markdown processor that offers this, using
the standard syntax. Are you?

Bruce

Why make the developer jump through all those hoops just to get
correctly formatted documentation? Markdown is supposed to make
things easy, right?

This is only for the benefit of the spec author(s). When we’re done,
it will be published as HTML.

Pandoc offers the follow features that I consider valuable here:

  • customizable headers
  • syntax highlighting
  • automatic table of contents

I am not aware of any other markdown processor that offers this, using
the standard syntax. Are you?

Yes, actually. Maruku: http://maruku.rubyforge.org/maruku.html

Both ruby and maruku are straight package installs in Ubuntu. We’ve
been using maruku to convert the source for our faculty website for
two years now, with no problems. http://gsl-nagoya-u.net/ Don’t know
how widely maruku is bundled in other systems, but it’s certainly less
complicated to install than the process you describe for pandoc, and
for us, at least, it’s been a tool that just works.

(The pandoc I used was a straight Ubuntu package install.)

Frank

Why make the developer jump through all those hoops just to get
correctly formatted documentation? Markdown is supposed to make
things easy, right?

This is only for the benefit of the spec author(s). When we’re done,
it will be published as HTML.

Pandoc offers the follow features that I consider valuable here:

  • customizable headers
  • syntax highlighting
  • automatic table of contents

I am not aware of any other markdown processor that offers this, using
the standard syntax. Are you?

Yes, actually. Maruku: http://maruku.rubyforge.org/maruku.html

Both ruby and maruku are straight package installs in Ubuntu. We’ve
been using maruku to convert the source for our faculty website for
two years now, with no problems. http://gsl-nagoya-u.net/ Don’t know
how widely maruku is bundled in other systems, but it’s certainly less
complicated to install than the process you describe for pandoc, and
for us, at least, it’s been a tool that just works.

(The pandoc I used was a straight Ubuntu package install.)

Maruku also requires a hint of the syntax to be highlighted, so known
qualntity.lstrictly speaking it doesn’t qualify as an answer. Also,
I’m not particularly pressing this as a replacement for pandoc; you
have that running, and if it’s meant mainly as a web doc and you’ll
handle the grinding, there’s nothing to complain about. But just for
info, maruku is out there.