Documentation ( was Re: [Mulgara-dev] Re: Bug list and versions)

[Life is hard, and then you die]

On Tue, Nov 21, 2006 at 01:13:12AM +0100, thomas wrote:
> hi,
> 
> i know the ball has been in my field for quite some time now. there are 
> some problems beside lack of time: i liked the idea of mavenization of the 
> docs but i find maven not so easy to understand. i also realized that the 
> head of the docs contains nice meta information which would be a pity to 
> loose, but it's not so easy to transfer meta tags from the head to any 
> prefab solution (wiki, maven etc). i would suggest to go for static html 
> pages with some server side includes (especially the navigation-tree), 
> without maven, but within subversion. including the navigation tree via ssi 
> makes it easy to add new pages. that's basically what already was decided, 
> except dropping the mavenization. as i said i already made some progress 
> with cleaning the html and consolidating the nav-tree into one document. i 
> will finish this as outlined above next week (really, this time...). if you 
> do not edit too many pages in the meantime i can easily fit your 
> modifications into the "new" site within an hour or two ... okay, this plan 
> should work ;-)

Just from personal preference, I like to have the docs as purely
static pages so I can browse them locally without having to actually
start up and run a webserver just to display them. So I'm not
particularly fond of idea of using SSI.


  Cheers,

  Ronald


> --On 20. November 2006 13:51:30 -0600 Paul Gearon <gearon at ieee.org> wrote:
> 
> >You're right.  Something is better than nothing.
> >
> >Also, we will never automatically generate the docs again, so I guess we
> >no
> >longer have this as an argument against modifying the generated files.
> >
> >I'll see if I can schedule the documentation for the difference operator
> >into my "copious spare time".
> >
> >Paul
> >
> >On 11/20/06, David Wood <dwood at softwarememetics.com> wrote:
> >>
> >>On 15 Nov2006, at 15:33, Paul Gearon wrote:
> >>> Everyone thinks it's a bad idea to hand-edit the HTML files,
> >>> meaning that we can't edit the docs.  (That didn't stop me from
> >>> changing "Kowari" to "Mulgara", but that's beside the point!)  :-)
> >>
> >>As much as I dislike the generated HTML, we need documentation that
> >>reflects the state of the project.  Until we get someone (maybe even
> >>me) to port the docs, we should live with them and update them.
> >>
> >>Regards,
> >>Dave
> >>