Lucifers,
The issue of standalone Markdown documentation files has already been discussed:
https://issues.apache.org/jira/browse/CLOWNFISH-26
I'd like to get this feature into 0.5.0, mainly to provide documentation of
the Clownfish header language as POD and HTML. The main problem is that we
don't have a way to tell which parcel a Markdown document belongs to. We
decided to solve this by reworking the layout of our core source directories,
but this is a major change for a later release.
It's possible to work-around this limitation by
* requiring links from Markdown documents to classes to
explicitly add the name of the parcel.
* changing the directory structure of the HTML docs to use
fully-qualified class names instead of parcel/struct_sym.
Here's an initial implementation for POD:
https://github.com/nwellnhof/lucy-clownfish/commits/standalone_docs
https://github.com/nwellnhof/lucy/commits/standalone_docs
The generated POD can be reviewed here:
https://github.com/nwellnhof/lucy/tree/generated_pod/perl/lib/Lucy/Docs
I added a new class CFCDocument for Markdown files. This is needed to simplify
linking between these files. I decided to use the same link syntax as for classes:
[](cfish:Tutorial)
This means that a couple of documentation files had to be renamed to avoid
names clashes (Lucy::Docs::Tutorial::FieldType vs. Lucy::Plan::FieldType, for
example).
We also lost the feature to link to Perl packages that aren't Clownfish
classes. This was used for `Lucy::Simple`, `LucyX::Remote::ClusterSearcher`,
and `Parse::RecDescent`. Maybe we could a add a syntax for linking to
arbitrary classes of the host language.
The generated POD also lost the NAME section and DESCRIPTION header. I don't
think this is a problem.
To adapt the Lucy tutorial and cookbook to other host languages, some parts of
the documentation will have to be reworded or moved to comments in
language-specific code blocks.
Nick
