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 Jeff Levitt <de...@mylevita.com> on 2005/06/18 09:09:07 UTC
[website] (was "Re: [jira] Commented: (DERBY-310) Document and/or change Derby client code to match behavior with Embedded driver where possible.")
--- "David Van Couvering (JIRA)" wrote:
<snip>
>
> Hm. I am uncomfortable going out with the release
> when the HTML is so clunky. I don't know how hard
> it is to set up a css file, but it seems like if
> we're trying to get people interested in using
> Derby, having docs that look funky does not send out
a good message to interested but hesitant new users.
>
</snip>
So this got me into sort of an investigative mode, and
I took a look at the html that is output by the DITA
toolkit transform. It seems there IS a css file that
these files point to, but they cant find it since its
not in the directory. The name of the file they all
point to is commonltr.css. So, I searched through the
DITA toolkit package, and I found the file in the
DITA-OT1.0.1\resource\ directory. When I copied that
file into the directory with my output html files and
reloaded the output in my browser, suddenly everything
changed formatting. The problem was it didn't change
the one issue you pointed out, which was that the
spacing around a table caption was non-existent, and
the font of those table captions was normal text, so
you couldnt distinguish it from the surrounding text.
Well, after playing with the css file, I finally
figured out how to modify it so that the captions are
bold and are spaced with margins around them. It
looks a lot better and I think you'll be satisfied
with the results.
So what I suggest is that we fix the website to place
the commonltr.css file into each manual's html output
directory. However, we should use my modified one so
that the tables look better. I have attached it to
this email. If this is something we can do, can a
committer do this for us so that the nightly builds
he change?
Re: [website] (was "Re: [jira] Commented: (DERBY-310) Document and/or
change Derby client code to match behavior with Embedded driver where possible.")
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
A quick update that I've been remiss in sending (had trouble finding
this thread).
The DITA team wants to release the Toolkit under the Apache license. As
soon as it's available under the ASL, I'll pull in the files that the
Derby docs need.
-jean
Jean T. Anderson wrote:
> I've discussed this issue with one of the Derby mentors who recommends
> that we ask the author of commonltr.css to license that particular file
> to the ASF under the Apache License.
>
> All that is needed is for the author to post a note to that effect to
> derby-dev.
>
> I'll work with Jeff on this.
>
> -jean
>
> Jean T. Anderson wrote:
>
>> I wasn't reading Jeff's email closely (my apologies).
>>
>> We aren't talking about any xsl stylesheets that DITA uses for the
>> transformation that produce the output files.
>>
>> We're talking about the cascading stylesheets used for display. They
>> don't need to be checked into svn, they just need to be accessible by
>> the html files that comprise the manuals. Jeff proposes putting the
>> stylesheet in each manual's output directory. Physical details: on
>> minotaur, this means copying the stylesheet into each
>> /www/incubator.apache.org/derby/docs/{adminguide, devguide, getstart,
>> ref, tools, tuning} subdirectory.
>>
>> There's probably a precedent for this at Apache that would confirm if
>> this is alright or not. Does anyone know for sure?
>>
>> -jean
>>
>>
>> Jean T. Anderson wrote:
>>
>>> A quick summary (Jeff, correct me if I mangled any meaning) is:
>>>
>>> - A DITA style sheet produces a pleasing format for Dreby manuals
>>> - Jeff's tweak of that style sheet improves the format even more
>>>
>>> The DITA toolkit is under the CPL license, and modifications to any
>>> of these files create derivative works under CPL. I asked
>>> legal-discuss back in March about checking files under a CPL license
>>> into the apache SVN repository, and the answer that came back was a
>>> strong "No"; I sent the status to derby-dev, see:
>>>
>>> http://mail-archives.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c422A393D.40306@bristowhill.com%3e
>>>
>>>
>>> So, these files cannot be checked into svn.
>>>
>>> However, anyone who builds the docs is free to use that style sheet.
>>> One option might be to make the style sheet available for download
>>> from a public site outside apache. --This was an approach Ross
>>> Gardler originally proposed for a DITA plugin for forrest when he
>>> offerred to host it at Burrokeet, see:
>>> http://mail-archives.apache.org/mod_mbox/forrest-dev/200503.mbox/%3c424C7886.3030100@apache.org%3e
>>>
>>>
>>>
>>> Anyhow, let's think about the "right apache way" for us to achieve
>>> what we need -- and Derby mentors on this list should feel REALLY
>>> free to chime in with your sage advice and experience.
>>>
>>> -jean
Re: [website] (was "Re: [jira] Commented: (DERBY-310) Document and/or
change Derby client code to match behavior with Embedded driver where possible.")
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
I've discussed this issue with one of the Derby mentors who recommends
that we ask the author of commonltr.css to license that particular file
to the ASF under the Apache License.
All that is needed is for the author to post a note to that effect to
derby-dev.
I'll work with Jeff on this.
-jean
Jean T. Anderson wrote:
> I wasn't reading Jeff's email closely (my apologies).
>
> We aren't talking about any xsl stylesheets that DITA uses for the
> transformation that produce the output files.
>
> We're talking about the cascading stylesheets used for display. They
> don't need to be checked into svn, they just need to be accessible by
> the html files that comprise the manuals. Jeff proposes putting the
> stylesheet in each manual's output directory. Physical details: on
> minotaur, this means copying the stylesheet into each
> /www/incubator.apache.org/derby/docs/{adminguide, devguide, getstart,
> ref, tools, tuning} subdirectory.
>
> There's probably a precedent for this at Apache that would confirm if
> this is alright or not. Does anyone know for sure?
>
> -jean
>
>
> Jean T. Anderson wrote:
>
>> A quick summary (Jeff, correct me if I mangled any meaning) is:
>>
>> - A DITA style sheet produces a pleasing format for Dreby manuals
>> - Jeff's tweak of that style sheet improves the format even more
>>
>> The DITA toolkit is under the CPL license, and modifications to any of
>> these files create derivative works under CPL. I asked legal-discuss
>> back in March about checking files under a CPL license into the apache
>> SVN repository, and the answer that came back was a strong "No"; I
>> sent the status to derby-dev, see:
>>
>> http://mail-archives.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c422A393D.40306@bristowhill.com%3e
>>
>>
>> So, these files cannot be checked into svn.
>>
>> However, anyone who builds the docs is free to use that style sheet.
>> One option might be to make the style sheet available for download
>> from a public site outside apache. --This was an approach Ross Gardler
>> originally proposed for a DITA plugin for forrest when he offerred to
>> host it at Burrokeet, see:
>> http://mail-archives.apache.org/mod_mbox/forrest-dev/200503.mbox/%3c424C7886.3030100@apache.org%3e
>>
>>
>>
>> Anyhow, let's think about the "right apache way" for us to achieve
>> what we need -- and Derby mentors on this list should feel REALLY free
>> to chime in with your sage advice and experience.
>>
>> -jean
>>
>>
>> Jeff Levitt wrote:
>>
>>>
>>> --- "David Van Couvering (JIRA)" wrote:
>>> <snip>
>>>
>>>> Hm. I am uncomfortable going out with the release
>>>> when the HTML is so clunky. I don't know how hard
>>>> it is to set up a css file, but it seems like if
>>>> we're trying to get people interested in using
>>>> Derby, having docs that look funky does not send out
>>>
>>>
>>>
>>> a good message to interested but hesitant new users.
>>>
>>> </snip>
>>>
>>> So this got me into sort of an investigative mode, and
>>> I took a look at the html that is output by the DITA
>>> toolkit transform. It seems there IS a css file that
>>> these files point to, but they cant find it since its
>>> not in the directory. The name of the file they all
>>> point to is commonltr.css. So, I searched through the
>>> DITA toolkit package, and I found the file in the
>>> DITA-OT1.0.1\resource\ directory. When I copied that
>>> file into the directory with my output html files and
>>> reloaded the output in my browser, suddenly everything
>>> changed formatting. The problem was it didn't change
>>> the one issue you pointed out, which was that the
>>> spacing around a table caption was non-existent, and
>>> the font of those table captions was normal text, so
>>> you couldnt distinguish it from the surrounding text. Well, after
>>> playing with the css file, I finally
>>> figured out how to modify it so that the captions are
>>> bold and are spaced with margins around them. It
>>> looks a lot better and I think you'll be satisfied
>>> with the results.
>>>
>>> So what I suggest is that we fix the website to place
>>> the commonltr.css file into each manual's html output
>>> directory. However, we should use my modified one so
>>> that the tables look better. I have attached it to
>>> this email. If this is something we can do, can a
>>> committer do this for us so that the nightly builds
>>> he change?
>>
>>
>>
>
Re: [website] (was "Re: [jira] Commented: (DERBY-310) Document and/or
change Derby client code to match behavior with Embedded driver where possible.")
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
I wasn't reading Jeff's email closely (my apologies).
We aren't talking about any xsl stylesheets that DITA uses for the
transformation that produce the output files.
We're talking about the cascading stylesheets used for display. They
don't need to be checked into svn, they just need to be accessible by
the html files that comprise the manuals. Jeff proposes putting the
stylesheet in each manual's output directory. Physical details: on
minotaur, this means copying the stylesheet into each
/www/incubator.apache.org/derby/docs/{adminguide, devguide, getstart,
ref, tools, tuning} subdirectory.
There's probably a precedent for this at Apache that would confirm if
this is alright or not. Does anyone know for sure?
-jean
Jean T. Anderson wrote:
> A quick summary (Jeff, correct me if I mangled any meaning) is:
>
> - A DITA style sheet produces a pleasing format for Dreby manuals
> - Jeff's tweak of that style sheet improves the format even more
>
> The DITA toolkit is under the CPL license, and modifications to any of
> these files create derivative works under CPL. I asked legal-discuss
> back in March about checking files under a CPL license into the apache
> SVN repository, and the answer that came back was a strong "No"; I sent
> the status to derby-dev, see:
>
> http://mail-archives.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c422A393D.40306@bristowhill.com%3e
>
>
> So, these files cannot be checked into svn.
>
> However, anyone who builds the docs is free to use that style sheet. One
> option might be to make the style sheet available for download from a
> public site outside apache. --This was an approach Ross Gardler
> originally proposed for a DITA plugin for forrest when he offerred to
> host it at Burrokeet, see:
> http://mail-archives.apache.org/mod_mbox/forrest-dev/200503.mbox/%3c424C7886.3030100@apache.org%3e
>
>
>
> Anyhow, let's think about the "right apache way" for us to achieve what
> we need -- and Derby mentors on this list should feel REALLY free to
> chime in with your sage advice and experience.
>
> -jean
>
>
> Jeff Levitt wrote:
>
>>
>> --- "David Van Couvering (JIRA)" wrote:
>> <snip>
>>
>>> Hm. I am uncomfortable going out with the release
>>> when the HTML is so clunky. I don't know how hard
>>> it is to set up a css file, but it seems like if
>>> we're trying to get people interested in using
>>> Derby, having docs that look funky does not send out
>>
>>
>> a good message to interested but hesitant new users.
>>
>> </snip>
>>
>> So this got me into sort of an investigative mode, and
>> I took a look at the html that is output by the DITA
>> toolkit transform. It seems there IS a css file that
>> these files point to, but they cant find it since its
>> not in the directory. The name of the file they all
>> point to is commonltr.css. So, I searched through the
>> DITA toolkit package, and I found the file in the
>> DITA-OT1.0.1\resource\ directory. When I copied that
>> file into the directory with my output html files and
>> reloaded the output in my browser, suddenly everything
>> changed formatting. The problem was it didn't change
>> the one issue you pointed out, which was that the
>> spacing around a table caption was non-existent, and
>> the font of those table captions was normal text, so
>> you couldnt distinguish it from the surrounding text. Well, after
>> playing with the css file, I finally
>> figured out how to modify it so that the captions are
>> bold and are spaced with margins around them. It
>> looks a lot better and I think you'll be satisfied
>> with the results.
>>
>> So what I suggest is that we fix the website to place
>> the commonltr.css file into each manual's html output
>> directory. However, we should use my modified one so
>> that the tables look better. I have attached it to
>> this email. If this is something we can do, can a
>> committer do this for us so that the nightly builds
>> he change?
>
>
Re: [website] (was "Re: [jira] Commented: (DERBY-310) Document and/or
change Derby client code to match behavior with Embedded driver where possible.")
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
A quick summary (Jeff, correct me if I mangled any meaning) is:
- A DITA style sheet produces a pleasing format for Dreby manuals
- Jeff's tweak of that style sheet improves the format even more
The DITA toolkit is under the CPL license, and modifications to any of
these files create derivative works under CPL. I asked legal-discuss
back in March about checking files under a CPL license into the apache
SVN repository, and the answer that came back was a strong "No"; I sent
the status to derby-dev, see:
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c422A393D.40306@bristowhill.com%3e
So, these files cannot be checked into svn.
However, anyone who builds the docs is free to use that style sheet. One
option might be to make the style sheet available for download from a
public site outside apache. --This was an approach Ross Gardler
originally proposed for a DITA plugin for forrest when he offerred to
host it at Burrokeet, see:
http://mail-archives.apache.org/mod_mbox/forrest-dev/200503.mbox/%3c424C7886.3030100@apache.org%3e
Anyhow, let's think about the "right apache way" for us to achieve what
we need -- and Derby mentors on this list should feel REALLY free to
chime in with your sage advice and experience.
-jean
Jeff Levitt wrote:
>
> --- "David Van Couvering (JIRA)" wrote:
> <snip>
>
>>Hm. I am uncomfortable going out with the release
>>when the HTML is so clunky. I don't know how hard
>>it is to set up a css file, but it seems like if
>>we're trying to get people interested in using
>>Derby, having docs that look funky does not send out
>
> a good message to interested but hesitant new users.
>
> </snip>
>
> So this got me into sort of an investigative mode, and
> I took a look at the html that is output by the DITA
> toolkit transform. It seems there IS a css file that
> these files point to, but they cant find it since its
> not in the directory. The name of the file they all
> point to is commonltr.css. So, I searched through the
> DITA toolkit package, and I found the file in the
> DITA-OT1.0.1\resource\ directory. When I copied that
> file into the directory with my output html files and
> reloaded the output in my browser, suddenly everything
> changed formatting. The problem was it didn't change
> the one issue you pointed out, which was that the
> spacing around a table caption was non-existent, and
> the font of those table captions was normal text, so
> you couldnt distinguish it from the surrounding text.
> Well, after playing with the css file, I finally
> figured out how to modify it so that the captions are
> bold and are spaced with margins around them. It
> looks a lot better and I think you'll be satisfied
> with the results.
>
> So what I suggest is that we fix the website to place
> the commonltr.css file into each manual's html output
> directory. However, we should use my modified one so
> that the tables look better. I have attached it to
> this email. If this is something we can do, can a
> committer do this for us so that the nightly builds
> he change?
Re: [website] (was "Re: [jira] Commented: (DERBY-310) Document and/or change Derby client code to match behavior with Embedded driver where possible.")
Posted by Jeff Levitt <de...@mylevita.com>.
Ooops, forgot to attach the modified css file! Here
it is.