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