db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kim Haase <Camilla.Ha...@Sun.COM>
Subject Re: Documentation conventions, DITA, and the toolkit
Date Mon, 13 Nov 2006 22:15:24 GMT
Laura Stewart wrote On 11/13/06 14:28,:
> Kim -
> 
> Thanks for your thoughtful work on this. Since you have a lot of
> comments, I am going to respond to each section/piece separately.

Thanks, Laura. That makes sense, since my posting was very long.

> 
> Section - Overall, New Terms, File Names/Paths
> 
> On 11/8/06, Kim Haase <Camilla.Haase@sun.com> wrote:
> 
>>This note is on a subject that could feed into the Guidelines doc,
>>especially the parts about textual tags as opposed to structural tags.
>>
>>The Getting Started manual has a section called "Typographical
>>conventions"
>>(http://db.apache.org/derby/docs/dev/getstart/rgsdocs18277.html) that
>>describes documentation conventions for the Derby manuals. It may need
>>some refining. And then how to make the conventions happen in DITA leads
>>to some toolkit questions. The goal of the section should be to describe
>>the way things mostly are, so that we can try to encourage contributors
>>to be consistent in the future. Fixing what's there now is a lower
>>priority goal. I would appreciate your views, Laura, and those of anyone
>>who's had longer experience with the docs than I have (most of you, I
>>think).
>>
>>New terms in italic: this is fine. The DITA <term> tag seems to
>>translate into a <dfn> tag in HTML.
>>
>>File and directory names in italic: this is a somewhat unusual
>>convention in my experience (fixed-width is more common, I think), but
>>I'd feel better about it if the documentation used it consistently. But
>>even the Getting Started manual doesn't. I think this may be a toolkit
>>issue, because Getting Started uses <filepath> instead of <i>, and the
>><filepath> tag currently seems to translate into ordinary text font
>>(<span class="filepath">, with no available css file to define the
>>class). (The 3 css files that are copied into the output directory don't
>>define this class.)
> 
> 
> 
> Discussion - Overall, New Terms, File Names/Paths
> 
> OVERALL -
> I agree, we need to look at what is documented here and see what needs
> to be updated or added. I also think that it would be beneficial for
> the typography info to be included on the Web, wherever it is not
> already discussed. And on the Web there should be some info about
> tagging, but that should not be in the docs.

I agree with these points -- assuming that by the Web you mean the
Writing Guidelines page at
http://db.apache.org/derby/manuals/guidelines.html.

> 
> NEW TERMS -
> Yes, the <term> tag is the correct one to use in DITA.  There should
> probably be some guidelines on the Web as to what constitutes a new
> term.  Any thoughts on this?

Ideally writers should use the <term> tag at the point where the term is
first used and defined, and not after. If the term is defined in more
than one place (which is likely given the size of our doc set), then the
tag could be used more than once too.

> 
> FILE NAMES/PATHS -
> I like it when they appear in italic but the <filename> tag does not
> appear to use that format.  I don't know very much about the CSS and
> if we can change it to whatever format we want.  Do you know of a site
> that gives a tutorial on style sheets?

Not offhand; I have an old O'Reilly HTML book that covers them, and they
aren't that hard to figure out from examples. However, if we wanted to
fix the stylesheets, we'd have to make sure they were used. Currently
the toolkit makes it really easy for them not to be. I didn't go into
this in my original posting because it would have made it even longer.

The toolkit does one of two things (I can't figure out how this happens;
there are a bunch of incomprehensible property settings that seem to do
it in the toolkit xml files):

1) If you use the default docs.properties file, it hardcodes the
absolute pathname of the stylesheet into each HTML file and copies the
three stylesheets into the output directory. For instance, in the
current trunk build this is what is hardcoded:

<link href="C:\nightlies\docs-trunk\out\reftemp\commonltr.css"
type="text/css" rel="stylesheet" />

The files in http://db.apache.org/derby/docs/dev/ref/ can't find this
file, though the file does exist at
http://db.apache.org/derby/docs/dev/ref/commonltr.css. For one thing,
the hardcoded pathname points to an interim location, reftemp, a
directory that disappears when processing is completed.

2) If you add the following empty property setting to the
docs.properties file --

 args.csspath=

you end up with a link that looks for the file in the current directory,
whatever that is:

<link href="commonltr.css" type="text/css" rel="stylesheet" />

Which would work perfectly -- except that if you do this, the CSS files
are *not* copied into the output directory. So they are equally
inaccessible, unless you copy them in by hand.

So we could ask for this bug to be fixed, one way or another. Or there
is yet another solution buried deep in the toolkit and possibly less
accessible to fixing. The file DITA-OT1.1.2.1/xsl/xslhtml/sw-d.xsl
defines what actually shows up in the html:

<xsl:template match="*[contains(@class,' sw-d/filepath ')]"
name="topic.sw-d.filepath">
 <span class="filepath">
  <xsl:call-template name="commonattributes"/>
  <xsl:call-template name="setidaname"/>
  <xsl:call-template name="flagcheck"/>
  <xsl:call-template name="revtext"/></span>
</xsl:template>

If "span" could be changed to "i" or "em", the css files would be
unnecessary. This is the file that specifies that <userinput> comes out
as <kbd> and that <systemoutput> comes out as <tt>. Some of the other
DITA tags that are defined as "span class" could also be changed here
(cmdname, for instance).

Andrew, who seems to know the most about the toolkit, might have some
ideas on what would be the best approach here. I could file a JIRA issue
and hope he could help.

> 
> I'll respond to the other sections as I have time.
> 

Thanks -- no rush!

Kim


Mime
View raw message