On Mon, Nov 24, 2014 at 8:49 AM, Nick Wellnhofer <[email protected]> wrote:
> It would be nice to support standalone documentation files that work across
> all host languages.
Clearly, what we want to support is standalone markdown files. We just need
to figure out the details.
> The problem with a plain .md file is you can't tell which parcel the
> documentation file belongs to. This piece of information is needed to
> organize the C documentation and for the custom URI scheme. But it should be
> easy to add this metadata with a `@parcel Lucy` directive, similar to the
> `@param` syntax for function documentation.
It should be possible to know a file's parcel given:
* where it lives in the file system
* the contents of a .cfp parcel file living above it
For example:
# cookbook.md belongs to whatever parcel is spelled out in foo.cfp
foo/foo.cfp
foo/docs/cookbook.md
We've discussed this before but haven't worked out the details. Shall we
proceed?
> Another approach is to use some kind of "distribution" identifier that is
> unique across a single build and can be used for multiple parcels.
The Clownfish parcel is deliberately an atomic unit of installation --
and thus also versioning.
Other systems have botched this badly -- e.g. Perl/CPAN by tying versioning to
the package/namespace rather than the distro. This makes it very hard to
reason about version requirements and the consequences of installing a
particular unit of distribution.
We should do everything we can to avoid repeating such mistakes.
Marvin Humphrey
