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