[racket] Linking to docs for Planet2 packages

On Tue, Feb 26, 2013 at 11:14:05PM -0500, Greg Hendershott wrote:
> 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"
> branch).

As far as I know, the big problem with most documentation file formats 
is that when small changes are made in the text (like adding a word).
the file changes drastically.  Even a properly laid-out paragraph in 
plain old ASCII text will change its layout completely.  Since most 
revision control systems treat a file as a string of lines, the result 
is that it considers the entire paragraph to have changed.  Nost word 
processors are even worse in this respect.  OpenOffice and LibreOffice
compress the entire file, and even LibreOffice's uncompressed .fodt file 
format doesn't contain ASCII line breaks.

If your HTML were to have lots of physical line breaks ar locations
that don't change drastically from revision to revision, you might 
find it quite reasonable to check it into git, and that git would update 
it reasonably.

But if the HTML were to be machine-generated, you might have to alter 
the generating program to produce line breaks at consistent places, such 
as after every punctuation mark that's now followed by a space.  
A browser would ignore these line breaks anyway.

What's left is to get github to *not* put some kind of HTML quoting 
around the page for the benefit of the client browser.

> 
> 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.

lumiera uses asciidoc instead, because it has toolchain support that 
takes it all the way to opendoc (is that tthe right word?)

I googled
   asciidoc to opendoc
https://wincent.com/wiki/Setting_up_the_Git_documentation_build_chain_on_Mac_OS_X_Leopard 
suggests to me that git docuumentatin itself might be sourced as 
asciidoc.  If that's true, asciidoc might be the preferred source cormat 
for documentation with git, since the git developers will have to deal 
with it themselves.  But if it's machine-generated asciidoc, make sure 
the line breaks remain consistent between revisions.

Unless git has special facilities to deal with errant line breaks.  If 
it doesn't, maybe it should.

> 
> 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
> >
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users