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 Laura Stewart <sc...@gmail.com> on 2006/10/17 19:22:11 UTC
Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
I am having some difficulties following the setup instructions for
forrest.. should I ask these questions on derby-dev or ??? Is there a
user list for forrest?
On 10/6/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
... (snip)
> Your recommendation sounds good.
>
> The http://db.apache.org/derby/manuals/dita.html link you mention is
> part of the forrest-generated web site. The source for that particular
> file is at
> https://svn.apache.org/repos/asf/db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
> .
>
> Information on how to checkout and build the web site is at
> http://db.apache.org/derby/papers/derby_web.html . Web site instructions
> also need more and better information. For example, they need to explain
> that the files under http://db.apache.org/derby/docs are actually
> generated separately from the web site and the web site simply points to
> those files hopefully achieving an integrated experience for the end user.
>
> -jean
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
On 10/30/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> Just one detail .... guidelines.xml didn't make it into the patch.
> derby1980_1.stat shows a question mark for that file:
>
> Also, you only need to svn diff the src tree, like this from the trunk
> directory:
>
> svn diff src > your_file.diff
>
Oh of course. Silly me :-).
I'll svn add and rebuild the patch from the src tree.
Thanks Jean for look at this!
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> I posted a patch to Derby 1980. The Web page updates are ready for your
> review.
>
Hi, Laura,
Good job!
Just one detail .... guidelines.xml didn't make it into the patch.
derby1980_1.stat shows a question mark for that file:
? src\documentation\content\xdocs\manuals\guidelines.xml
M src\documentation\content\xdocs\manuals\dita.xml
M src\documentation\content\xdocs\site.xml
That question mark means it isn't under svn control. It needs an
'svn add', then 'svn diff' will pick it up in the patch.
Also, you only need to svn diff the src tree, like this from the trunk
directory:
svn diff src > your_file.diff
After applying the patch, I'll build the site, then commit the changes
in the build tree.
thanks for all the hard work on this.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
I posted a patch to Derby 1980. The Web page updates are ready for your review.
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Well, I finally got what I want to work. This will teach me to
copy/paste from HTML (argh). I have an XML editor that I am using
which checks to ensure that it is a well formed XML document and that
there are no tagging errors.
I'll be posting the updates to Jira issue 1980. Since I am adding a
new page, do you think that it would be good to have svn stat?
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> Also, is there a way to force a line break inside of a table in XML
> tagging?
>
> I tried using <br></br> but forrest site is returning errors...
>
hmmmm .... http://forrest.apache.org/dtdx/document-v20.dtdx.html#td
shows that br is allowed in a td. Is that where you were inserting the
line break?
Perhaps if you could post just the snippet that uses it here (with
enough table context), other eyes can spot what forrest wants.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Also, is there a way to force a line break inside of a table in XML tagging?
I tried using <br></br> but forrest site is returning errors...
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> I have inserted a table into one of the xml documents but now I am
> getting some errors when I try forrest site that indicate that some
> attributed (ALIGN and VALGN) are not declared. Is there a list of
> declared attributes that I can see, so that I know what is valid? Can
> the list be added to?
Here are the docs for the forrest dtd (and howto's and faq's are on the
left hand nav of this page):
http://forrest.apache.org/dtdx/document-v20.dtdx.html
'td' doesn't include align and valign:
http://forrest.apache.org/dtdx/document-v20.dtdx.html#td
It might help to check the faqs at the forrest site -- perhaps the issue
of adding to the dtd has come up before.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
I have inserted a table into one of the xml documents but now I am
getting some errors when I try forrest site that indicate that some
attributed (ALIGN and VALGN) are not declared. Is there a list of
declared attributes that I can see, so that I know what is valid? Can
the list be added to?
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> Might be nice if I included the file :-P
>
> On 10/19/06, Laura Stewart <sc...@gmail.com> wrote:
>
>> Huge help Jean ! The CDATA tag is long but worked beautifully !!!
>>
>> Now a few minor irritants :-)
>> I've attached the html page. Please note that the first section title
>> is left justified in the tan bar, but the remaining section titles are
>> not... anyway to fix?
>> Also the table bleeds off to the right... anyway to fix that?
>>
>> Really appreciate you help on this !
The forrest decoration isn't making it into the attachment, so I don't
see what you see. Could you attach the source file instead of the file
forrest has built? (Better yet -- how about opening a Jira issue and
attaching it to that?) Then I'll build it and hopefully see what you see.
thanks,
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Might be nice if I included the file :-P
On 10/19/06, Laura Stewart <sc...@gmail.com> wrote:
> Huge help Jean ! The CDATA tag is long but worked beautifully !!!
>
> Now a few minor irritants :-)
> I've attached the html page. Please note that the first section title
> is left justified in the tan bar, but the remaining section titles are
> not... anyway to fix?
> Also the table bleeds off to the right... anyway to fix that?
>
> Really appreciate you help on this !
>
> --
> Laura Stewart
>
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Huge help Jean ! The CDATA tag is long but worked beautifully !!!
Now a few minor irritants :-)
I've attached the html page. Please note that the first section title
is left justified in the tan bar, but the remaining section titles are
not... anyway to fix?
Also the table bleeds off to the right... anyway to fix that?
Really appreciate you help on this !
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> Another question. In my XML tagging, I am trying to use the <literal>
> tag, but forrest isn't accepting it. Does the tag need to be declared
> somewhere for it to be accepted?
>
> The reason that I am using that tag is so that I can show the DITA
> tagging with the <> symbols, for example
> <prolog><metadata></metadata></prolog>. It is my understanding that
> <literal> will let me do that...unless you can recommend another tag?
<literal> isn't in the forrest dtd -- is that maybe part of dita?
At any rate, forrest has <code> and <source> tags. Here's the docs for
the dtd (and howto's and faq's are on the left hand nav of this page):
http://forrest.apache.org/dtdx/document-v20.dtdx.html
So <code> is inline:
Set the <code>PATH</code> environment variable to include ...
And <source> sets stuff off in a separate block:
<source>mkdir MyDir
cd MyDir
forrest seed
</source>
With the <code> and <source> tags you probably have to use < for <
and > for > . And you can probably avoid that by using CDATA:
<source><![CDATA[Put your text here.]]></source>
I hope this helps.
regards,
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Another question. In my XML tagging, I am trying to use the <literal>
tag, but forrest isn't accepting it. Does the tag need to be declared
somewhere for it to be accepted?
The reason that I am using that tag is so that I can show the DITA
tagging with the <> symbols, for example
<prolog><metadata></metadata></prolog>. It is my understanding that
<literal> will let me do that...unless you can recommend another tag?
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> Well, I sucessfully created a new page off of the Documentation tab.
> It is called "Guidelines". When I perform "forrest site" it creates
> the page just fine. SUCCESS !
congratulations!
> So, one of the things that I would like to have off of this new page
> are 3 sample files that people can use a templates for the different
> topic types.
> How do I accomplish that?
If you want to include the sample as straight text in an xml source
file, perhaps with surrounding text to explain the dita source, you can
include it inside a CDATA block; there's an example under the third
bullet in the "Add your new page to the seed site" section in this page:
http://db.apache.org/derby/papers/derby_web.html#Add+your+new+page+to+the+seed+site
if this won't work, could you describe more what you'd like to do?
cheers,
-jean
> I currently have only one template that is ready to be posted. The
> others I will have next week.
>
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
Well, I sucessfully created a new page off of the Documentation tab.
It is called "Guidelines". When I perform "forrest site" it creates
the page just fine. SUCCESS !
So, one of the things that I would like to have off of this new page
are 3 sample files that people can use a templates for the different
topic types.
How do I accomplish that?
I currently have only one template that is ready to be posted. The
others I will have next week.
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> The Derby instructions mention several editors, which I don't have.
> Do you recommend one over the other?
> Is it okay (albeit not ideal) to edit the XML in wordpad or notepad?
> Or will this cause problems?
Edit it using the tool you like the most, but avoid any editor that will
add formatting characters.
Save as "Text Document" in notepad -- but it doesn't seem to have other
options.
If you use wordpad be sure to explicitly save as a "Text Document" -- I
spot there's also a choice for "Text Document - MS-DOS Format". Does
anyone know what the difference is?
I use vi. I'm already an admitted dinosaur.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
The Derby instructions mention several editors, which I don't have.
Do you recommend one over the other?
Is it okay (albeit not ideal) to edit the XML in wordpad or notepad?
Or will this cause problems?
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
...
Another clarifying note ...
> There's a one-to-one correspondence between a source file and the target.
>
> After checking out the derby web site source on your local system, this
> is the file that explains dita processing:
>
> src/documentation/content/xdocs/manuals/dita.xml
>
> I'm using it as an example because I know you happen to be interested in
> improving it :-) . The static processed (or "skinned" file, in
> forrest-speak) is here:
>
> build/site/manuals/dita.html
Here's the location of that page on the web site:
http://db.apache.org/derby/manuals/dita.html
I updated the information in the page below to hopefully make it easier
to understand which files in a physical subdirectory, such as "manuals"
in the svn repo, might show up on which tab ("Documentation") on the
derby site:
http://db.apache.org/derby/papers/derby_web.html#3.+Modify+files+in+the+src+tree
I say "might show up" because after the web site reorg this last year
there's no longer a one-to-one correspondence between physical
subdirectories on the machine hosting the web site and the web site tabs
themselves.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> I have successfully performed the "forrest seed" command. Following
> the tutorial, I tried changing the sample web pages, but have run into
> problems getting the changes to appear. I'm having difficulties
> figuring out which files control which pages (or parts of pages).
>
> Should I continue to work through the tutorial or start looking at the
> derby files?
I'll let you decide which would be more productive for you, but I'll go
ahead and start discussing the derby web site files because that will
become more relevant. --Anyone who knows better than I do on any of
these details please jump in and add more info or correct.
There's a one-to-one correspondence between a source file and the target.
After checking out the derby web site source on your local system, this
is the file that explains dita processing:
src/documentation/content/xdocs/manuals/dita.xml
I'm using it as an example because I know you happen to be interested in
improving it :-) . The static processed (or "skinned" file, in
forrest-speak) is here:
build/site/manuals/dita.html
Now, let's say you modify that dita.xml source file. When do those
changes become visible?
There are two answers (that I know of):
1) If you "File open" build/site/manuals/dita.html with your browser,
those changes only become visible after you execute 'forrest site' to
rebuild the web site.
By default (and derby uses the default) 'forrest site' outputs static
pages to build/site. The derby web site at http://db.apache.org/derby is
composed of static pages.
2) If you are using the jetty server that comes with forrest to view
pages -- in other words, you did these two steps:
- 'forrest run'
- with your browser open localhost:8888
Then the changes become visible after you refresh your page.
I don't use method #2 so anyone should feel free to dive in and correct
me on those details.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
I have successfully performed the "forrest seed" command. Following
the tutorial, I tried changing the sample web pages, but have run into
problems getting the changes to appear. I'm having difficulties
figuring out which files control which pages (or parts of pages).
Should I continue to work through the tutorial or start looking at the
derby files?
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
...
> I updated
> http://db.apache.org/derby/papers/derby_web.html#Create+a+Forrest+seed+site
>
> and added a link to the forrest install instructions at
> http://forrest.apache.org/docs_0_70/your-project.html#installing
>
> The forrest instructions show how to add environment variables in
> Windows 2000 and XP.
actually, I had forgotten how nice this this forrest tutorial is. I'll
highlight prominently on the derby web site instructions.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> A couple of followup questions.
>
> I should run "forrest seed" in another directory, but in the same
> path? or in an entirely new path?
I suggest that you create a new subdirectory, cd into that subdirectory,
then run 'forrest seed'. I tend to hang onto the seeded directory for a
while because it provides examples of how to do things in forrest.
> The env variables... are they user or system variables. I would like
> to set them permanently instead of having to run the batch file (which
> by the way worked great !).
It's your choice to set the variables in a batch file or update them
permanently in your Windows system.
I updated
http://db.apache.org/derby/papers/derby_web.html#Create+a+Forrest+seed+site
and added a link to the forrest install instructions at
http://forrest.apache.org/docs_0_70/your-project.html#installing
The forrest instructions show how to add environment variables in
Windows 2000 and XP.
I hope that helps,
-jean
> Laura
>
> On 10/17/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>
>> Jean T. Anderson wrote:
>> ...
>> > At any rate, after setting up my environment this way, I was able to
>> run
>> > 'forrest -projecthelp', 'forrest seed', and 'forrest site' in the derby
>> > site directory.
>>
>> I misspoke; don't run 'forrest seed' in the derby site directory. That
>> will generate a new site that overlays the derby web site -- not what
>> you'd want to do. :-)
>>
>> It's ok to run both 'forrest -projecthelp' and 'forrest site' in the
>> derby site directory.
>>
>> -jean
>>
>
>
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
A couple of followup questions.
I should run "forrest seed" in another directory, but in the same
path? or in an entirely new path?
The env variables... are they user or system variables. I would like
to set them permanently instead of having to run the batch file (which
by the way worked great !).
Laura
On 10/17/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> Jean T. Anderson wrote:
> ...
> > At any rate, after setting up my environment this way, I was able to run
> > 'forrest -projecthelp', 'forrest seed', and 'forrest site' in the derby
> > site directory.
>
> I misspoke; don't run 'forrest seed' in the derby site directory. That
> will generate a new site that overlays the derby web site -- not what
> you'd want to do. :-)
>
> It's ok to run both 'forrest -projecthelp' and 'forrest site' in the
> derby site directory.
>
> -jean
>
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
...
> At any rate, after setting up my environment this way, I was able to run
> 'forrest -projecthelp', 'forrest seed', and 'forrest site' in the derby
> site directory.
I misspoke; don't run 'forrest seed' in the derby site directory. That
will generate a new site that overlays the derby web site -- not what
you'd want to do. :-)
It's ok to run both 'forrest -projecthelp' and 'forrest site' in the
derby site directory.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> The instructions on the Derby site say to download forrest (which I
> did) in the following path:
> C:\Authoring\Forrest\apache-forrest-0.7
>
> The next step says to use the forrest seed command.
> Nothing happens, the system doesn't recognize this command.
ah! The derby instructions need to be more explicit and say for that
first step "Install Forrest and configure it according to the Forrest
instructions".
> So I went to the Forrest site.
> http://forrest.apache.org/docs_0_70/your-project.html#installing
> Their instructions are somewhat different. They mention setting an
> environment variable for FORREST_HOME. On Windows, is this a user
> variable or a system variable? I tried adding it (to both) and
> rebooted, but when I try
> the command that they recommend (forrest -projecthelp) I get
> a message indicating that the path/directory is too long (seems odd to me)
> The exact message is:
>
> C:\Authoring\Forrest\apache-forrest-0.7\bin>forrest -projecthelp
> The input line is too long.
> The filename, directory name, or volume label syntax is incorrect.
>
> Apache Forrest. Run 'forrest -projecthelp' to list options
>
> The input line is too long.
>
Here's an f7_env.bat file I just created on Windows XP:
set JAVA_HOME=C:\IBM\Java142
set FORREST_HOME=c:\apache\apache-forrest-0.7
set PATH=%JAVA_HOME%\bin;%FORREST_HOME%\bin;%PATH%
set ANT_OPTS=-Xmx512M
I then executed that file in a DOS shell to set the variables:
C:\jta>f7_env.bat
Incidently, the ANT_OPTS option is specifically for building the derby
web site -- if that isn't set, then you'll likely run out of memory when
you build the web site.
(*Incidently, http://db.apache.org/derby/papers/derby_web.html says to
set ANT_OPTS to -mx512M, and that didn't work for me just now on
Windows. I did a google search and found info to change that to -Xmx512M
. Has anyone else noticed this?)
At any rate, after setting up my environment this way, I was able to run
'forrest -projecthelp', 'forrest seed', and 'forrest site' in the derby
site directory.
> Also the impression that I have from the Forrest site is that you
> download forest to one path but you seed a different path
Yes; you install the product in one place (in my case, I installed
forrest in c:\apache\apache-forrest-0.7), set FORREST_HOME to point to
that location and add FORREST_HOME\bin it to your PATH. Then you run
forrest in another location where there is a web site to build.
'forrest seed' creates a new web site. That step is in the derby
instructions purely to get developers comfortable with running forrest.
'forrest site' is what you run to actually build the derby web site.
> Any help on getting this working will be appreciated...
keep asking questions! If you have that question, most likely others do too.
-jean
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process Improvements)
Posted by Laura Stewart <sc...@gmail.com>.
The instructions on the Derby site say to download forrest (which I
did) in the following path:
C:\Authoring\Forrest\apache-forrest-0.7
The next step says to use the forrest seed command.
Nothing happens, the system doesn't recognize this command.
So I went to the Forrest site.
http://forrest.apache.org/docs_0_70/your-project.html#installing
Their instructions are somewhat different. They mention setting an
environment variable for FORREST_HOME. On Windows, is this a user
variable or a system variable? I tried adding it (to both) and
rebooted, but when I try
the command that they recommend (forrest -projecthelp) I get
a message indicating that the path/directory is too long (seems odd to me)
The exact message is:
C:\Authoring\Forrest\apache-forrest-0.7\bin>forrest -projecthelp
The input line is too long.
The filename, directory name, or volume label syntax is incorrect.
Apache Forrest. Run 'forrest -projecthelp' to list options
The input line is too long.
Also the impression that I have from the Forrest site is that you
download forest to one path but you seed a different path
Any help on getting this working will be appreciated...
--
Laura Stewart
Re: Issues with Forrest/Derby Web site (Was: Re: Proposal - Doc Process
Improvements)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> I am having some difficulties following the setup instructions for
> forrest.. should I ask these questions on derby-dev or ??? Is there a
> user list for forrest?
It may be that some of your questions need to be directed to the forrest
user list, but unless anyone objects I suggest you ask the questions
here. That might help other derby developers likewise get involved with
the web site.
-jean