You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Jean T. Anderson" <jt...@bristowhill.com> on 2005/05/11 02:15:23 UTC

[doc] Proposal to move 10.0 doc files from derby/site to derby/docs

I realized last week that the DITA docs can't be used to replace the 
files that were originally contributed. We need a permanent solution for 
the original files for the reasons outlined in 
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200505.mbox/%3c4280D846.70901@bristowhill.com%3e 
.

I propose moving the files out of derby/site and into some location 
under derby/docs, create a mini forrest site, copy the results of the 
forrest build to incubator.apache.org/derby/docs/10.0, then link to it 
from the derby web site just like we do for the 10.1 DITA docs.

Here's a protype site with a first shot of what it would look like:

http://incubator.apache.org/derby/docs/10.0/


1) What difference will end users encounter?

a) Since the original files will no longer be integrated with the 
current web site, users won't see "Home" and "Community" tabs on each 
page; instead, they'll see a tab that takes them to the main derby site. 
To see the difference, compare this old page with the proposed new:

http://incubator.apache.org/derby/manuals/develop/develop15.html
http://incubator.apache.org/derby/docs/10.0/manuals/develop/develop15.html

b) Old email and Jira entries that reference the old location will break 
because of the addition of the "docs/10.0" path in the URL.

After the files are moved (and that change propagated to 
www.apache.org), I can try to add symbolic links to the main site that 
make the old URLs work again. However, this might require assistance 
from infrastructure.

2) What are the actual steps to implement this change?

a) Initialize a new forrest site under 
svn.apache.org/repos/asf/incubator/derby/docs/trunk/10.0

b) svn move the subdirectories from 
derby/site/trunk/src/documentation/content/xdocs/manuals to 
derby/docs/trunk/10.0/src/documentation/content/xdocs/manuals

c) Update the 10.0 doc links in 
derby/site/trunk/src/documentation/content/xdocs/site.xml to point to 
http://incubator.apache.org/derby/docs/10.0 files instead of to 
locations relative to the site source. (This is what we currently do 
with the 10.1 DITA-generated docs.)

d) Create symbolic links on minotaur.apache.org between the old location 
and the new so URLs in old email and Jira entries will still work.

3) Who will do this?

Jean will, with svn coordination with Andrew.

Comments?

I'm posting a much shorter version of this (minus the technical details) 
to derby-user.

If there's no opposition to this strategy (and no better proposal 
offered) by Friday, May 13, I'll go ahead and implement this change. I'm 
opting for a lazy approach because history shows that [doc] topics often 
don't get active attention.

regards,

  -jean

Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs [Last call for objections]

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Just keep in mind that derby/docs/branches/10.0 just has doc source. The 
pages built from that source are not committed to the svn repo. --This 
is how other apache projects handle forrest-generated stuff.

  -jean


Andrew McIntyre wrote:
> On 5/14/05, Jean T. Anderson <jt...@bristowhill.com> wrote:
> 
>>This change is in place and the web site changes are live on
>>incubator.apache.org/derby . From my poking, it seems stable. Please
>>report any problems.
> 
> 
> Now that we have a real 10.0 doc branch, should I remove the doc set
> that's included in the 10.0 code branch? Or should I update it with a
> build from the 10.0 doc branch? The 10.0 branch isn't seeing much
> action, but I suppose it might be useful to have a set of docs checked
> in somewhere in case there happens to be a need to make a 10.0 release
> sometime in the future.
> 
> Anyone have an opinion on this?
> 
> andrew


Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs [Last call for objections]

Posted by Andrew McIntyre <mc...@gmail.com>.
On 5/14/05, Jean T. Anderson <jt...@bristowhill.com> wrote:
> This change is in place and the web site changes are live on
> incubator.apache.org/derby . From my poking, it seems stable. Please
> report any problems.

Now that we have a real 10.0 doc branch, should I remove the doc set
that's included in the 10.0 code branch? Or should I update it with a
build from the 10.0 doc branch? The 10.0 branch isn't seeing much
action, but I suppose it might be useful to have a set of docs checked
in somewhere in case there happens to be a need to make a 10.0 release
sometime in the future.

Anyone have an opinion on this?

andrew

Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs [Last call for objections]

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
> Later today I intend to work on moving the 10.0 docs from derby/site to 
> derby/docs with Andrew's modifications.
> 
> If anybody objects, please speak up now.

This change is in place and the web site changes are live on 
incubator.apache.org/derby . From my poking, it seems stable. Please 
report any problems.

  -jean

Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs [Last call for objections]

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Later today I intend to work on moving the 10.0 docs from derby/site to 
derby/docs with Andrew's modifications.

If anybody objects, please speak up now.

  -jean


Andrew McIntyre wrote:
> Just a couple of comments...
> 
> On 5/10/05, Jean T. Anderson <jt...@bristowhill.com> wrote:
> 
>>a) Since the original files will no longer be integrated with the
>>current web site, users won't see "Home" and "Community" tabs on each
>>page; instead, they'll see a tab that takes them to the main derby site.
> 
> 
> Looks good, better than my hack job with the doc set that went out
> with the 10.0.2.1 release. :-)
> 
> 
>>2) What are the actual steps to implement this change?
>>
>>a) Initialize a new forrest site under
>>svn.apache.org/repos/asf/incubator/derby/docs/trunk/10.0
> 
> 
> This should be svn.apache.org/repos/asf/incubator/derby/docs/branches/10.0
> to keep it separate from the DITA source.
> 
> 
>>b) svn move the subdirectories from
>>derby/site/trunk/src/documentation/content/xdocs/manuals to
>>derby/docs/trunk/10.0/src/documentation/content/xdocs/manuals
> 
> 
> As above, into docs/branches instead of docs/trunk.
> 
> 
>>d) Create symbolic links on minotaur.apache.org between the old location
>>and the new so URLs in old email and Jira entries will still work.
> 
> 
> I'm curious if these links will be properly synced over to
> www.apache.org. I'm guessing that they will, as long as rsync's link
> options are turned on for the sync, but we'll see.
> 
> andrew


Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> I'm curious if these links will be properly synced over to
> www.apache.org. I'm guessing that they will, as long as rsync's link
> options are turned on for the sync, but we'll see.

I expect this to might require an infra-human in the loop on 
www.apache.org to physically remove the old directories and create the 
links.

  -jean

Re: [doc] Proposal to move 10.0 doc files from derby/site to derby/docs

Posted by Andrew McIntyre <mc...@gmail.com>.
Just a couple of comments...

On 5/10/05, Jean T. Anderson <jt...@bristowhill.com> wrote:
> a) Since the original files will no longer be integrated with the
> current web site, users won't see "Home" and "Community" tabs on each
> page; instead, they'll see a tab that takes them to the main derby site.

Looks good, better than my hack job with the doc set that went out
with the 10.0.2.1 release. :-)

> 2) What are the actual steps to implement this change?
> 
> a) Initialize a new forrest site under
> svn.apache.org/repos/asf/incubator/derby/docs/trunk/10.0

This should be svn.apache.org/repos/asf/incubator/derby/docs/branches/10.0
to keep it separate from the DITA source.

> b) svn move the subdirectories from
> derby/site/trunk/src/documentation/content/xdocs/manuals to
> derby/docs/trunk/10.0/src/documentation/content/xdocs/manuals

As above, into docs/branches instead of docs/trunk.

> d) Create symbolic links on minotaur.apache.org between the old location
> and the new so URLs in old email and Jira entries will still work.

I'm curious if these links will be properly synced over to
www.apache.org. I'm guessing that they will, as long as rsync's link
options are turned on for the sync, but we'll see.

andrew