On 01/12/2014 07:08, Marvin Humphrey wrote:
The W3C validator reports a few problems with some of the generated HTML -- it
might be nice to clean those up.
One thing is a missing <title>. I originally planned to allow custom HTML
headers and footers for the generated docs but this would require a simple
templating system to create useful titles. I think I'll defer this feature for
now.
The other is a missing charset declaration. This raises the question whether
we want to allow UTF-8 in our docucomments. This isn't a problem for HTML and
POD. For man pages, UTF-8 support is system-dependent. My guess is that most
modern systems support UTF-8. If this turns out to be a problem, we can also
escape non-ASCII characters.
To be honest, I'm not thrilled with what we're putting out there as the public
API for either Clownfish or Lucy -- there are a number of things marked
"public" which really shouldn't be. The subset of the API published in the
Perl docs is what I would consider canonical.
I only uploaded the HTML documentation for review. I also have no plans to
publish C API documentation for Lucy. But I really want to get started with
defining and publishing the Clownfish C API.
Question: does CommonMark support conditional inclusion of code blocks?
It would be nice to put things such as the Lucy tutorial into core, but
providing host-specific code samples poses a challenge.
CommonMark supports the "fenced" code blocks of GitHub Flavored Markdown that
allow to add an "info string":
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
It also allows to use tildes to be used instead of backticks:
http://spec.commonmark.org/0.12/#fenced-code-blocks
The HTML renderer uses the first word of the info string to add a class like
"language-ruby". The info string is also available in the parsed syntax tree,
so it's easy to remove the code blocks we're not interested in.
Nick
