A few days ago, after RC1 was put up for a vote to release, I started
working on [LUCENENET-438] by cleaning up the documentation.  The current
state of the documentation is pretty bad, there are many unconverted
remnants of javadoc comments (ie, @link, @see, etc..).  I wanted to do this
simply to get our documentation up to a more readable level.

I had expected this to take quite a long time, but with the magic of
regular expressions and find and replace, I'm nearly done with the
conversion, this all on the heels of the RC2 that was just put up to vote.
 I will probably wind up finishing the cleanup of the documentation
comments before Monday.  I would have said something earlier had I known it
wouldn't take me long and I likely wouldn't have made a vote on releasing
RC2.

So, if no one is opposed to it, we may consider to wait on RC2, regenerate
new documentation after I push the changes to SVN, and package it for
another RC (Sorry, Prescott!!).  It might be nice to have those
documentation issues fixed.  Like I said before, I hadn't really expected
to finish it so quickly, and hadn't even though it could be ready in time
for 2.9.4 release.
Thanks,
Christopher

I dont mind

Sent from my Windows Phone
________________________________
From: Christopher Currens
Sent: 11/4/2011 5:08 PM
To: [EMAIL PROTECTED]
Subject: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation

A few days ago, after RC1 was put up for a vote to release, I started
working on [LUCENENET-438] by cleaning up the documentation.  The current
state of the documentation is pretty bad, there are many unconverted
remnants of javadoc comments (ie, @link, @see, etc..).  I wanted to do this
simply to get our documentation up to a more readable level.

I had expected this to take quite a long time, but with the magic of
regular expressions and find and replace, I'm nearly done with the
conversion, this all on the heels of the RC2 that was just put up to vote.
 I will probably wind up finishing the cleanup of the documentation
comments before Monday.  I would have said something earlier had I known it
wouldn't take me long and I likely wouldn't have made a vote on releasing
RC2.

So, if no one is opposed to it, we may consider to wait on RC2, regenerate
new documentation after I push the changes to SVN, and package it for
another RC (Sorry, Prescott!!).  It might be nice to have those
documentation issues fixed.  Like I said before, I hadn't really expected
to finish it so quickly, and hadn't even though it could be ready in time
for 2.9.4 release.
Thanks,
Christopher

I've committed the changes to the xml documentation to the repo.

I built the documentation, but I wasn't sure how Michael packaged the
documentation in [LUCENENET-452].  If someone could either rebuild the
documentation or let me know how it was done for the release, then we can
open it up for another vote to release it.
Thanks,
Christopher

On Fri, Nov 4, 2011 at 8:55 PM, Prescott Nasser <[EMAIL PROTECTED]>wrote:

> I dont mind
>
> Sent from my Windows Phone
> ________________________________
> From: Christopher Currens
> Sent: 11/4/2011 5:08 PM
> To: [EMAIL PROTECTED]
> Subject: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation
>
> A few days ago, after RC1 was put up for a vote to release, I started
> working on [LUCENENET-438] by cleaning up the documentation.  The current
> state of the documentation is pretty bad, there are many unconverted
> remnants of javadoc comments (ie, @link, @see, etc..).  I wanted to do this
> simply to get our documentation up to a more readable level.
>
> I had expected this to take quite a long time, but with the magic of
> regular expressions and find and replace, I'm nearly done with the
> conversion, this all on the heels of the RC2 that was just put up to vote.
>  I will probably wind up finishing the cleanup of the documentation
> comments before Monday.  I would have said something earlier had I known it
> wouldn't take me long and I likely wouldn't have made a vote on releasing
> RC2.
>
> So, if no one is opposed to it, we may consider to wait on RC2, regenerate
> new documentation after I push the changes to SVN, and package it for
> another RC (Sorry, Prescott!!).  It might be nice to have those
> documentation issues fixed.  Like I said before, I hadn't really expected
> to finish it so quickly, and hadn't even though it could be ready in time
> for 2.9.4 release.
>
>
> Thanks,
> Christopher
>

I can rebuild it, but the trick is replacing the version of it in svn so
that it does not cause svnsync and cms to choke. Last time I just pushed it
into branch/site/docs.  However, that is not publicly visible for the
incubation website, so Prescott had to do an svn move.

I'm not quite sure how to go about it this time around. I would push it to
jira, but it caps uploads at 10 mb.  And I definitely don't want to cause
infra any grief.  Thoughts/Suggestions on how to proceed ?
On Sun, Nov 6, 2011 at 1:28 AM, Christopher Currens <[EMAIL PROTECTED]
> wrote:

> I've committed the changes to the xml documentation to the repo.
>
> I built the documentation, but I wasn't sure how Michael packaged the
> documentation in [LUCENENET-452].  If someone could either rebuild the
> documentation or let me know how it was done for the release, then we can
> open it up for another vote to release it.
>
>
> Thanks,
> Christopher
>
> On Fri, Nov 4, 2011 at 8:55 PM, Prescott Nasser <[EMAIL PROTECTED]
> >wrote:
>
> > I dont mind
> >
> > Sent from my Windows Phone
> > ________________________________
> > From: Christopher Currens
> > Sent: 11/4/2011 5:08 PM
> > To: [EMAIL PROTECTED]
> > Subject: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation
> >
> > A few days ago, after RC1 was put up for a vote to release, I started
> > working on [LUCENENET-438] by cleaning up the documentation.  The current
> > state of the documentation is pretty bad, there are many unconverted
> > remnants of javadoc comments (ie, @link, @see, etc..).  I wanted to do
> this
> > simply to get our documentation up to a more readable level.
> >
> > I had expected this to take quite a long time, but with the magic of
> > regular expressions and find and replace, I'm nearly done with the
> > conversion, this all on the heels of the RC2 that was just put up to
> vote.
> >  I will probably wind up finishing the cleanup of the documentation
> > comments before Monday.  I would have said something earlier had I known
> it
> > wouldn't take me long and I likely wouldn't have made a vote on releasing
> > RC2.
> >
> > So, if no one is opposed to it, we may consider to wait on RC2,
> regenerate
> > new documentation after I push the changes to SVN, and package it for
> > another RC (Sorry, Prescott!!).  It might be nice to have those
> > documentation issues fixed.  Like I said before, I hadn't really expected
> > to finish it so quickly, and hadn't even though it could be ready in time
> > for 2.9.4 release.
> >
> >
> > Thanks,
> > Christopher
> >
>

On 2011-11-07, Michael Herndon wrote:

> I can rebuild it, but the trick is replacing the version of it in svn so
> that it does not cause svnsync and cms to choke. Last time I just pushed it
> into branch/site/docs.  However, that is not publicly visible for the
> incubation website, so Prescott had to do an svn move.

When I recommended to do the svn move I didn't realize we were talking
about that many files.  I simply didn't check, sorry.

> I'm not quite sure how to go about it this time around. I would push it to
> jira, but it caps uploads at 10 mb.

Then it still had to go to svn in some way.

Personally I'm not a friend of generated documents in svn but I'm in a
minority here.

With svnpubsub being your only option I think the only thing you can do
is split the commit into smaller chunks, committing 100 or 200 files at
a time.  Maybe infra has better ideas than that, I don't.

Stefan

@Stefan.

I wouldn't worry about the taking the blame, you've done plenty to help out
and there is no way to catch everything. We'll learn as we go.

As svnpub is the only option and since we can't run the binary version that
uses ASP.NET, we'll need to probably take your suggestion commit the
smaller chunks of html then.

I'll do it manually this time and see if I can't write a script that
automates it in the future.

@Chris, thanks for the fixes to the build scripts this weekend.

- Michael
On Mon, Nov 7, 2011 at 9:20 AM, Stefan Bodewig <[EMAIL PROTECTED]> wrote:

> On 2011-11-07, Michael Herndon wrote:
>
> > I can rebuild it, but the trick is replacing the version of it in svn so
> > that it does not cause svnsync and cms to choke. Last time I just pushed
> it
> > into branch/site/docs.  However, that is not publicly visible for the
> > incubation website, so Prescott had to do an svn move.
>
> When I recommended to do the svn move I didn't realize we were talking
> about that many files.  I simply didn't check, sorry.
>
> > I'm not quite sure how to go about it this time around. I would push it
> to
> > jira, but it caps uploads at 10 mb.
>
> Then it still had to go to svn in some way.
>
> Personally I'm not a friend of generated documents in svn but I'm in a
> minority here.
>
> With svnpubsub being your only option I think the only thing you can do
> is split the commit into smaller chunks, committing 100 or 200 files at
> a time.  Maybe infra has better ideas than that, I don't.
>
> Stefan
>

I don't understand why we have the rendered html in the docs.  I don't mind
having the .chm rendered and put in the repo, but the entire HTML
documentation spans 8,000 files and over 100mb.  The CHM comes in at around
15mb.

I don't think it's necessary to have both in the repo, but if the consensus
is to keep them both, I think we should bundle the HTML docs in a zip,
instead of being added as loose files, at least in trunk.  I think it's
kinda silly the way it is now, and SVN does better at handling 1 large file
versus 8,000 smaller ones.

On Mon, Nov 7, 2011 at 6:53 AM, Michael Herndon <[EMAIL PROTECTED]
> wrote:

> @Stefan.
>
> I wouldn't worry about the taking the blame, you've done plenty to help out
> and there is no way to catch everything. We'll learn as we go.
>
> As svnpub is the only option and since we can't run the binary version that
> uses ASP.NET, we'll need to probably take your suggestion commit the
> smaller chunks of html then.
>
> I'll do it manually this time and see if I can't write a script that
> automates it in the future.
>
> @Chris, thanks for the fixes to the build scripts this weekend.
>
> - Michael
>
>
> On Mon, Nov 7, 2011 at 9:20 AM, Stefan Bodewig <[EMAIL PROTECTED]> wrote:
>
> > On 2011-11-07, Michael Herndon wrote:
> >
> > > I can rebuild it, but the trick is replacing the version of it in svn
> so
> > > that it does not cause svnsync and cms to choke. Last time I just
> pushed
> > it
> > > into branch/site/docs.  However, that is not publicly visible for the
> > > incubation website, so Prescott had to do an svn move.
> >
> > When I recommended to do the svn move I didn't realize we were talking
> > about that many files.  I simply didn't check, sorry.
> >
> > > I'm not quite sure how to go about it this time around. I would push it
> > to
> > > jira, but it caps uploads at 10 mb.
> >
> > Then it still had to go to svn in some way.
> >
> > Personally I'm not a friend of generated documents in svn but I'm in a
> > minority here.
> >
> > With svnpubsub being your only option I think the only thing you can do
> > is split the commit into smaller chunks, committing 100 or 200 files at
> > a time.  Maybe infra has better ideas than that, I don't.
> >
> > Stefan
> >
>

My intention is to link it to the website, so we have browsable documentation

 

----------------------------------------
> Date: Mon, 7 Nov 2011 19:26:23 -0800
> From: [EMAIL PROTECTED]
> To: [EMAIL PROTECTED]
> Subject: Re: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation
>
> I don't understand why we have the rendered html in the docs. I don't mind
> having the .chm rendered and put in the repo, but the entire HTML
> documentation spans 8,000 files and over 100mb. The CHM comes in at around
> 15mb.
>
> I don't think it's necessary to have both in the repo, but if the consensus
> is to keep them both, I think we should bundle the HTML docs in a zip,
> instead of being added as loose files, at least in trunk. I think it's
> kinda silly the way it is now, and SVN does better at handling 1 large file
> versus 8,000 smaller ones.
>
> On Mon, Nov 7, 2011 at 6:53 AM, Michael Herndon <[EMAIL PROTECTED]
> > wrote:
>
> > @Stefan.
> >
> > I wouldn't worry about the taking the blame, you've done plenty to help out
> > and there is no way to catch everything. We'll learn as we go.
> >
> > As svnpub is the only option and since we can't run the binary version that
> > uses ASP.NET, we'll need to probably take your suggestion commit the
> > smaller chunks of html then.
> >
> > I'll do it manually this time and see if I can't write a script that
> > automates it in the future.
> >
> > @Chris, thanks for the fixes to the build scripts this weekend.
> >
> > - Michael
> >
> >
> > On Mon, Nov 7, 2011 at 9:20 AM, Stefan Bodewig <[EMAIL PROTECTED]> wrote:
> >
> > > On 2011-11-07, Michael Herndon wrote:
> > >
> > > > I can rebuild it, but the trick is replacing the version of it in svn
> > so
> > > > that it does not cause svnsync and cms to choke. Last time I just
> > pushed
> > > it
> > > > into branch/site/docs. However, that is not publicly visible for the
> > > > incubation website, so Prescott had to do an svn move.
> > >
> > > When I recommended to do the svn move I didn't realize we were talking
> > > about that many files. I simply didn't check, sorry.
> > >
> > > > I'm not quite sure how to go about it this time around. I would push it
> > > to
> > > > jira, but it caps uploads at 10 mb.
> > >
> > > Then it still had to go to svn in some way.
> > >
> > > Personally I'm not a friend of generated documents in svn but I'm in a
> > > minority here.
> > >
> > > With svnpubsub being your only option I think the only thing you can do
> > > is split the commit into smaller chunks, committing 100 or 200 files at
> > > a time. Maybe infra has better ideas than that, I don't.
> > >
> > > Stefan
> > >
> >    

I noticed that we have a bit of documentation in the 'site' directory of
the, and the trunk directory.  Which one are we using to link to the
website, the one in trunk or the site folder?  I feel that maybe we could
still keep the docs in trunk zipped for each release and tag, then extract
that to the site directory when we want to release documentation.  At least
then it would keep our SVN uncluttered.  To be honest, though, I don't
really know how documentation is stored in other projects, so I'll admit
I'm not even 100% sure if that's a plausible solution.
On Mon, Nov 7, 2011 at 11:55 PM, Prescott Nasser <[EMAIL PROTECTED]>wrote:

>
> My intention is to link it to the website, so we have browsable
> documentation
>
>
>
>
>
> ----------------------------------------
> > Date: Mon, 7 Nov 2011 19:26:23 -0800
> > From: [EMAIL PROTECTED]
> > To: [EMAIL PROTECTED]
> > Subject: Re: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation
> >
> > I don't understand why we have the rendered html in the docs. I don't
> mind
> > having the .chm rendered and put in the repo, but the entire HTML
> > documentation spans 8,000 files and over 100mb. The CHM comes in at
> around
> > 15mb.
> >
> > I don't think it's necessary to have both in the repo, but if the
> consensus
> > is to keep them both, I think we should bundle the HTML docs in a zip,
> > instead of being added as loose files, at least in trunk. I think it's
> > kinda silly the way it is now, and SVN does better at handling 1 large
> file
> > versus 8,000 smaller ones.
> >
> > On Mon, Nov 7, 2011 at 6:53 AM, Michael Herndon <
> [EMAIL PROTECTED]
> > > wrote:
> >
> > > @Stefan.
> > >
> > > I wouldn't worry about the taking the blame, you've done plenty to
> help out
> > > and there is no way to catch everything. We'll learn as we go.
> > >
> > > As svnpub is the only option and since we can't run the binary version
> that
> > > uses ASP.NET, we'll need to probably take your suggestion commit the
> > > smaller chunks of html then.
> > >
> > > I'll do it manually this time and see if I can't write a script that
> > > automates it in the future.
> > >
> > > @Chris, thanks for the fixes to the build scripts this weekend.
> > >
> > > - Michael
> > >
> > >
> > > On Mon, Nov 7, 2011 at 9:20 AM, Stefan Bodewig <[EMAIL PROTECTED]>
> wrote:
> > >
> > > > On 2011-11-07, Michael Herndon wrote:
> > > >
> > > > > I can rebuild it, but the trick is replacing the version of it in
> svn
> > > so
> > > > > that it does not cause svnsync and cms to choke. Last time I just
> > > pushed
> > > > it
> > > > > into branch/site/docs. However, that is not publicly visible for
> the
> > > > > incubation website, so Prescott had to do an svn move.
> > > >
> > > > When I recommended to do the svn move I didn't realize we were
> talking
> > > > about that many files. I simply didn't check, sorry.
> > > >
> > > > > I'm not quite sure how to go about it this time around. I would
> push it
> > > > to
> > > > > jira, but it caps uploads at 10 mb.
> > > >
> > > > Then it still had to go to svn in some way.
> > > >
> > > > Personally I'm not a friend of generated documents in svn but I'm in
> a
> > > > minority here.
> > > >
> > > > With svnpubsub being your only option I think the only thing you can
> do
> > > > is split the commit into smaller chunks, committing 100 or 200 files
> at
> > > > a time. Maybe infra has better ideas than that, I don't.
> > > >
> > > > Stefan
> > > >
> > >
>

Well the issue is that Apache's homegrown site CMS system (which our
site is based off of) uses SVN to store/deploy the file for the
site... So deployable artifacts for the site need to be in SVN, in a
particular directory structure under the site directory, so that they
can be picked up by the CMS.

Then there's the documentation we want to deploy with the DLL,
including XML docs, and CHM, which are stored near the codebase. I
believe, but I could be wrong, that it's possible to update your site
deployment script and do something like.. store the website docs in a
zip file in SVN, then unpack upon deployment, thus reducing the
clutter in SVN. Not sure how to go about that off the top of my head
though.

-T
On Tue, Nov 8, 2011 at 10:55 AM, Christopher Currens
<[EMAIL PROTECTED]> wrote:
> I noticed that we have a bit of documentation in the 'site' directory of
> the, and the trunk directory.  Which one are we using to link to the
> website, the one in trunk or the site folder?  I feel that maybe we could
> still keep the docs in trunk zipped for each release and tag, then extract
> that to the site directory when we want to release documentation.  At least
> then it would keep our SVN uncluttered.  To be honest, though, I don't
> really know how documentation is stored in other projects, so I'll admit
> I'm not even 100% sure if that's a plausible solution.
>
>
> On Mon, Nov 7, 2011 at 11:55 PM, Prescott Nasser <[EMAIL PROTECTED]>wrote:
>
>>
>> My intention is to link it to the website, so we have browsable
>> documentation
>>
>>
>>
>>
>>
>> ----------------------------------------
>> > Date: Mon, 7 Nov 2011 19:26:23 -0800
>> > From: [EMAIL PROTECTED]
>> > To: [EMAIL PROTECTED]
>> > Subject: Re: [Lucene.Net] Lucene.Net-2.9.4-incubator-RC2 Documentation
>> >
>> > I don't understand why we have the rendered html in the docs. I don't
>> mind
>> > having the .chm rendered and put in the repo, but the entire HTML
>> > documentation spans 8,000 files and over 100mb. The CHM comes in at
>> around
>> > 15mb.
>> >
>> > I don't think it's necessary to have both in the repo, but if the
>> consensus
>> > is to keep them both, I think we should bundle the HTML docs in a zip,
>> > instead of being added as loose files, at least in trunk. I think it's
>> > kinda silly the way it is now, and SVN does better at handling 1 large
>> file
>> > versus 8,000 smaller ones.
>> >
>> > On Mon, Nov 7, 2011 at 6:53 AM, Michael Herndon <
>> [EMAIL PROTECTED]
>> > > wrote:
>> >
>> > > @Stefan.
>> > >
>> > > I wouldn't worry about the taking the blame, you've done plenty to
>> help out
>> > > and there is no way to catch everything. We'll learn as we go.
>> > >
>> > > As svnpub is the only option and since we can't run the binary version
>> that
>> > > uses ASP.NET, we'll need to probably take your suggestion commit the
>> > > smaller chunks of html then.
>> > >
>> > > I'll do it manually this time and see if I can't write a script that
>> > > automates it in the future.
>> > >
>> > > @Chris, thanks for the fixes to the build scripts this weekend.
>> > >
>> > > - Michael
>> > >
>> > >
>> > > On Mon, Nov 7, 2011 at 9:20 AM, Stefan Bodewig <[EMAIL PROTECTED]>
>> wrote:
>> > >
>> > > > On 2011-11-07, Michael Herndon wrote:
>> > > >
>> > > > > I can rebuild it, but the trick is replacing the version of it in
>> svn
>> > > so
>> > > > > that it does not cause svnsync and cms to choke. Last time I just
>> > > pushed
>> > > > it
>> > > > > into branch/site/docs. However, that is not publicly visible for
>> the
>> > > > > incubation website, so Prescott had to do an svn move.
>> > > >
>> > > > When I recommended to do the svn move I didn't realize we were
>> talking
>> > > > about that many files. I simply didn't check, sorry.
>> > > >
>> > > > > I'm not quite sure how to go about it this time around. I would
>> push it
>> > > > to
>> > > > > jira, but it caps uploads at 10 mb.
>> > > >
>> > > > Then it still had to go to svn in some way.