[hakyll] Writing entries in DocBook

[Pavel Kretov]

Hi all!

I know that pandoc supports converting from and to DocBook and I've just
tried writing a test blog entry in this format and got the following
message:

[ERROR] Hakyll.Web.readPandocWith: I don't know how to read a file
of the type Binary for: posts/2015-03-21-test-docbook.xml (:pure)

How can I make Hakyll recognize this file as DocBook? (It seems common
for DocBook writers to use plain XML extension, but I've tried
".docbook" and ".db" extensions too.)

Another problem with DocBook is "---" metadata section which makes file
not a valid XML any more. Can I somehow put it into the XML comment block?

——— Pavel Kretov.

[Joshua Simmons]

I got bored enough to take a look, this pull request may help but I barely
did anything in the way of testing it, I don't know DocBook in the
slightest and my energy for figuring it out withered:

https://github.com/jaspervdj/hakyll/pull/339

It should add .docbook and .db as possible extensions. AFAIK the ---- thing
should just work (tm).

[Pavel Kretov]

Post by Joshua Simmons
I got bored enough to take a look, this pull request may help but I
barely did anything in the way of testing it, I don't know DocBook in
the slightest and my energy for figuring it out withered.

Thank you a lot for your effort. I've tried you pull request and it
seems to work for me.

I think DocBook is a promising markup format which should be supported
by Hakyll as well as others. In fact, I'm trying to develop a more
lightweight alternative to its cumbersome syntax, something more like
LaTeX.

Post by Joshua Simmons
It should add .docbook and .db as possible extensions.

Sorry for misleading you in my first letter, but we should not add
neither ".db" nor ".docbook" into the list of supported
extensions. Instead, according to Wikipedia, its recommended to use
".dbk" extension. Would you kindly edit your PR?

Post by Joshua Simmons
AFAIK the ---- thing should just work (tm).

Yes, it works. But I'd like to propose an alternative syntax for
metadata section delimiters which wouldn't ruin XML-based markup:

<!---
title: Why I hate XML?
tags: XML, hate, hate, hate
--->

Please note three dashed here (not two as ordinary). I'd also want to
hear Jasper's opinion about that.

――― Pavel Kretov.

[Bruce D'Arcus]

... I'd like to propose an alternative syntax for
<!---
title: Why I hate XML?
tags: XML, hate, hate, hate
--->
Please note three dashed here (not two as ordinary). I'd also want to
hear Jasper's opinion about that.

Maybe I'm missing something, but on first glance, this makes no sense at
all.

XML is a robust, extensible, markup format, and DocBook by default includes
extensive metadata support.

It also has a wide range of tools that support it, including validating and
auto-completing editors.

E.g. if you want lightweight markup, use Markdown. If you want the power,
expressivity, and flexibility of XML, then use it.

Bruce

[Pavel Kretov]

Post by Bruce D'Arcus

... I'd like to propose an alternative syntax for
<!---
title: Why I hate XML?
tags: XML, hate, hate, hate
--->
Please note three dashed here (not two as ordinary). I'd also want
to hear Jasper's opinion about that.

Maybe I'm missing something, but on first glance, this makes no sense
at all.
XML is a robust, extensible, markup format, and DocBook by default
includes extensive metadata support.

I know it does. But all I want from Hakyll at this point is some
preliminary support, nothing more. I know that title, tags or other
metadata can be extracted from the DocBook source at all, but I don't
think I can insist that Hakyll *must* support it. Being able to
duplicate that meta in comment seems to me reasonable for now.

Post by Bruce D'Arcus
It also has a wide range of tools that support it, including
validating and auto-completing editors.

But it still is poor at readability for a human, editing long XML by hand
is a pain and proper tooling just make this pain less.

Post by Bruce D'Arcus
E.g. if you want lightweight markup, use Markdown. If you want the
power, expressivity, and flexibility of XML, then use it.

Your're right here. But to my mind, DocBook is not nailed down to
cumbersome XML representation, it can be put LaTeX-style instead. But
this goes a little bit off-topic this mailing list, please see the
post-scriptum if you feel interested.

――― Pavel Kretov.

P. S.

For example, consider the following code snippet, taken from SVN Red
Book:

<para>You may already have seen <command>svn copy</command> used
to copy one file to another within a working copy. But it can
also be used to do a <firstterm>remote
copy</firstterm>&mdash;a copy that immediately results in a
newly committed repository revision and for which no working
copy is required at all. Just copy one URL to another:</para>

<informalexample>
<screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
http://svn.example.com/repos/calc/branches/my-calc-branch \
-m "Creating a private branch of /calc/trunk."
Committed revision 341.
$
</screen>
</informalexample>

It contains a lot of visual noise for closing tag names, which
particulary makes it hard to wrap such a text in short
lines. Next, I don't know why it contains &mdash instead of plain
typographic M-dash, but it is also a redability hit. And, finally,
content of <screen> tab must start from the very first column which
*totally* ruin the appearance. Instead we could put the same text in a
different layout:

\para:
You may already have seen \command{svn copy} used to copy one file
to another within a working copy. But it can also be used to do
a \firstterm{remote copy}―a copy that immediately results in a
newly committed repository revision and for which no working
copy is required at all. Just copy one URL to another:

\informalexample:
\screen:
$ svn copy http://svn.example.com/repos/calc/trunk \
http://svn.example.com/repos/calc/branches/my-calc-branch \
-m "Creating a private branch of /calc/trunk."
Committed revision 341.
$

Here <tag>...</tag> is converted to \tag{...} or \tag: for
identation-based scope, or even \tag ... \endtag. That's just a rough
idea, though, and I haven't developed every detail yet, but that
markup is intended to be an (more or less) equivalent XML
representation. And it you have read up to this point, tell me please
your opinion about the idea (possibly, in a direct message).

[Joshua Simmons]

Post by Pavel Kretov
Thank you a lot for your effort. I've tried you pull request and it
seems to work for me.

Cool, you're welcome.

Post by Pavel Kretov

Post by Joshua Simmons
It should add .docbook and .db as possible extensions.

Sorry for misleading you in my first letter, but we should not add
neither ".db" nor ".docbook" into the list of supported
extensions. Instead, according to Wikipedia, its recommended to use
".dbk" extension. Would you kindly edit your PR?

Sure, edited.

https://github.com/jaspervdj/hakyll/pull/339

Josh