[racket] Linking to docs for Planet2 packages

From: Greg Hendershott (greghendershott at gmail.com)
Date: Tue Feb 26 23:14:05 EST 2013

Another option would be to generate Markdown files, which GitHub does
display nicely for a repo's normal branch(es) (not just the "gh-pages"

For a smallish project, it might be OK for all its documentation to be
the repo's README.md. Which you could generate from a README.scrbl
file: Racket 5.3.2 added a --markdown flag to the Scribble
command-line tool.

Or if you prefer a simpler README.md, it could link to one or more
separate Markdown files in the repo.

(This isn't the answer for very big and/or complicated docs. And it
might not even be the long-term answer for smaller ones. But it's an
another option.)

On Tue, Feb 26, 2013 at 8:09 AM, Laurent <laurent.orseau at gmail.com> wrote:
> Just in case this can help, there is githubpreview, and maybe pages.github:
> http://stackoverflow.com/questions/8446218/how-to-see-an-html-page-on-github-as-a-normal-rendered-html-page-to-see-preview
> Haven't tried, but I suppose it's probably not the perfect solution.
> Laurent
> On Tue, Feb 26, 2013 at 1:34 PM, Jay McCarthy <jay.mccarthy at gmail.com>
> wrote:
>> This is one of the items on the list of future work:
>> http://docs.racket-lang.org/planet2/Future_Plans.html#%28part._.Long_.Term%29
>> It's not trivial because (a) the package system only ships source, not
>> compiled things like docs; (b) packages can have many Scribble documents as
>> their documentation; and (c) the main distribution mechanism, Github, is
>> designed for source and not HTML. Obviously it would be trivial to allow
>> package authors to add a link in their package description to docs
>> somewhere, but that wouldn't be very robust and would put a lot of work on
>> them.
>> Jay
>> On Mon, Feb 25, 2013 at 10:39 AM, Michael Wilber <mwilber at uccs.edu> wrote:
>>> Hey there!
>>> Is there any convention for linking to docs from planet2's online list
>>> of packages?
>>> E.g. as a user, it would be nice to have a "Click here to see
>>> documentation" link from, say,
>>> https://pkg.racket-lang.org/info/disassemble that either links to the
>>> scribbled docs in the source or to a URL specified by the package author
>>> in info.rkt or somewhere.
>>> ____________________
>>>   Racket Users list:
>>>   http://lists.racket-lang.org/users
>> --
>> Jay McCarthy <jay at cs.byu.edu>
>> Assistant Professor / Brigham Young University
>> http://faculty.cs.byu.edu/~jay
>> "The glory of God is Intelligence" - D&C 93
>> ____________________
>>   Racket Users list:
>>   http://lists.racket-lang.org/users
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users

Posted on the users mailing list.