[Pyblosxom-devel] New syntax for metadata?

[chombee <ch...@la...>]

Maybe a suggestion for 2.0? Or, this could perhaps be implemented as a
plugin first as a test and then maybe integrated into 2.0 later.

Pyblosxom's entry metadata is a neat feature but in my humble opinion
the syntax is a little ugly and non-standard.  Here's an example of what
I'm talking about:

    This is my first post
    #mood bored
    #music The Doors - Greatest Hits Vol 1

    This is the beginning of the body of my post...

The most standard, recognisable use of words beginning with a # like
that is as tags in twitter, identica etc., not as key: value pairs. It's
also very limited. Metadata keys cannot contain spaces, and metadata
values can only be one line long. I'd suggest an alternative syntax:

    This is my first post
    mood: bored
    music: The Doors - Greatest Hits Vol 1

    This is the beginning of the body of my post...

I think this both looks nicer and looks more like key: value pairs, and
it's a more standard and familiar syntax. It's YAML syntax, in fact.
Also, it remains easy for pyblosxom to parse and it won't make writing
posts any more complicated for the user.

If the second line of the file contains a : character then it's
considered a metadata line, and any lines immediately following it that
also contain a : are metadata too. The first line after the title that
does not contain a : marks the beginning of the body. This could be an
empty line (which would disambiguate things if you wanted the first line
of content to contain a : character).

To parse it just split each metadata line at the first : character to
get the key and value, so keys can contain spaces (but they can't
contain : characters).

Based on YAML syntax you could extend this idea to allow multi-line and
structured metadata blocks. In fact, you could use PyYAML to parse the
metadata block once pyblosxom's parser has identified the block and
split it out from the rest of the file contents. PyYAML would return a
dictionary to pyblosxom, just as pyblosxom currently parses metadata
blocks as dictionaries. Parsing the metadata block as YAML would allow
you to do lots of things, though admittedly it might make the
implementation a little more complicated.

Lists, either on multiple lines or on one:

    This is my first post
    key:
     - value 1
     - value 2
    another key: [value 1, value 2]

    This is the body...

I can see lists being useful for plugins that implemented tags.

(The multi-line list is delimited by indentation.)

Nested structure:

    This is my first post
    key:
      key: value
      key: value
      key: value
    key:
      key: value

    This is the body...

(Again indentation denotes structure here, following YAML syntax.)

Multi-line values:

    This is my first post
    key:
      blah blah blah blah blah blah
      blah blah blah blah blah blah
      blah blah blah blah blah blah

      blah blah blah blah blah blah
      blah blah blah blah blah blah

    This is the body...

I can see multi-line support being useful for plugins that implement
entry summaries, for example.

(Again, indentation delimits the multi-line value. In this case the
first empty line of the file and several other lines that do not contain
: characters are part of a metadata value and do not mark the beginning
of the entry's body, and this is unambiguous because indentation is
used.)

PyYAML will parse values 'true' and 'false' as python booleans, integer
values as integers, floating point values as floats, YAML lists as
python lists, YAML mappings as python dictionaries, even timestamp
strings in various formats as standard python datetime objects (e.g. for
storing publication times in metadata).

Note that because of the way PyBlosxom would identify the metadata block
(by looking for lines containing : characters) before passing it to YAML
for parsing, I believe the top-level object in the YAML document would
always be a YAML mapping, which PyYAML would parse to a python
dictionary. So it's a slightly restricted YAML that I'm suggesting. I
believe YAML documents generally may have a list as the top-level
object. Simply looking for lines that contain :'s is probably not enough
to guarantee that you've found a YAML document whose top-level object is
a mapping, it would probably be slightly trickier in practice.