On Mon, Sep 26, 2011 at 12:46 AM, Ivan Raikov <ivan.g.raikov@gmail.com> wrote:
>
> Hello,
>
>  I agree with your general points about documentation, but given the
> proliferation of documentation formats, I am not sure that it would be
> wise to require a specific format, such as Markdown. Chicken Scheme and
> Racket already have their own extensive documentation systems, and
> converting their documentation to a different format would be
> non-trivial. Allowing documentation in plain text or HTML to be bundled
> with each package might lower the threshold of participation a bit.

I agree with you. Most any format should work. Sorry, didn't mean to
imply otherwise. As long as some html can be generated from it such
that the resulting html could be used for that snowball's page on the
snowfort site. If the README is plain text, then that text can be
wrapped in <pre> tags for use on the snowball's page.

(Apologies for continuing the use of the Snow terminology, even though
a name hasn't been chosen yet. The terminology just happens to be
handy.)

Getting html from the README could mean that the person doing the
uploading generates the html on their own machine. Or else their
README is in a format that the upload tool knows about so it can
generate the html at upload-time (README.mkdn, README.rst, README.ltx,
README.texi, etc.).

To be clear though: I'm only suggesting a minor requirement for a
README -- the content of which would serve as the main (and brief)
overview content on that snowball's snowfort page.

(Aside: My guess would be that many contributors will also write full
manuals (using their doc format of choice), and that eventually such
manuals will be viewable at the snowfort. But there's time for that
after the snowfort is built and fortified with some snowballs. :) )

---John

_______________________________________________
Scheme-reports mailing list
Scheme-reports@scheme-reports.org
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports