support rst directives for meta-data blocks

[GoogleCodeExporter]

The metadata blocks that gitit supports (for categories, titles, etc) are
really nice, but they're noise as far as RST is concerned.  To see this try:

   darcs get --lazy http://wiki.darcs.net
   rst2html DiagnosticMessages.page > foo.html
   # this is with docutils

It seems like a simple way to address this (very minor) problem would be to
support metadata blocks embedded in an RST directive
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives

More generally, maybe it would be good if the Pandoc Markdown had some sort
of extension syntax (if it does not already)

Original issue reported on code.google.com by eric....@gmail.com on 23 Feb 2010 at 11:03

[GoogleCodeExporter]

You can get an RST page that will pass muster by exporting it from your gitit:
curl http://localhost:5001/DiagnosticMessages?export&format=rst
or something like that.

I agree, though, that it would be better if the metadata were in a place that 
made 
sense for the format of the page.  For example, in a markdown or HTML page it 
could be embedded in an HTML comment, and in RST in a directive, and in LaTeX 
in 
a latex comment.

The problem is that gitit doesn't know the format of the page until it reads 
the 
metadata.  My solution was to make the metadata constant in format for all 
pages.  I 
don't know if that was the right decision, because it interferes with 
processing gitit 
pages using standard tools -- or at least complicates this, as you must export 
the 
page first.

I suppose I could change things so that, in parsing the page's metadata, pandoc 
ignored (a) a surrounding HTML comment, (b) % at the beginning of a line (LaTeX 
comment), or (c) anything in a RST comment.

So, in markdown or HTML:
<!--
---
title: My Page
format: My format
...
-->

in LaTeX:
% ---
% title: My page
% format: My format
% ...

in RST (using comments):

.. ---
.. title: My Page
.. format: My format
.. ...

I would probably want to make this commentification optional, so existing pages 
would still work. What do you think?

Original comment by fiddloso...@gmail.com on 23 Feb 2010 at 4:52

[GoogleCodeExporter]

Making the commentification optional seems like it would make sense (at least 
as an
initial transition step, with maybe a deprecation phase if you want to keep the 
code
bloat down).

It sounds like you could do this by (a) having gitit parse metadata as you 
suggest
[I'm not sure if you really meant pandoc or gitit in your proposal, but I'll 
guess
gitit] and (b) instead of chopping off the metadata block, passing it to pandoc 
along
with the rest of the text (just in case it's actually meaningful, eg. in the 
case of
the title/author/etc fields in Markdown).

This would mean that you'd get to use RST comments as metadata in LaTeX 
documents,
but then if you do that, whatever happens is your own fault :-)

Original comment by eric....@gmail.com on 23 Feb 2010 at 5:19