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/[EMAIL PROTECTED]
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/[EMAIL PROTECTED]
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?
