On Mon, Sep 26, 2011 at 12:46 AM, Ivan Raikov <[email protected]> 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 [email protected] http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports
