support rst directives for meta-data blocks #235

jgm opened this Issue Jul 9, 2011 · 2 comments

1 participant

jgm commented Jul 9, 2011
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
   rst2html > 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

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

Google Code Info:
Issue #: 92
Created On: 2010-02-23T11:03:09.000Z
Closed On: 
jgm commented Jul 9, 2011

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:

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?

Google Code Info:
Created On: 2010-02-23T16:52:26.000Z

@jgm jgm was assigned Jul 9, 2011
jgm commented Jul 9, 2011

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 :-)

Google Code Info:
Created On: 2010-02-23T17:19:50.000Z

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment