Documentation conventions, DITA, and the toolkit

[Kim Haase <Ca...@Sun.COM>]

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.)

Dictionary objects in italic: These are things stored in the database
(tables, etc.). Italic also seems to be used generally for things like
property names, Java object, interface, and method names, identifiers,
and other code objects (which I'm also more used to seeing in
fixed-width). I notice again that in the DITA source this is generally
done with <i> rather than semantic tagging, probably because there is no
suitable semantic tag. One odd thing is that these objects are sometimes
in fixed-width italic and sometimes plain italic, often within the same
sentence or paragraph. (See, for example, "java.*, javax.*" in
http://db.apache.org/derby/docs/dev/devguide/cdevdeploy15818.html, the
second sentence in
http://db.apache.org/derby/docs/dev/devguide/tdevdvlp14496.html, or
http://db.apache.org/derby/docs/dev/devguide/cdevspecial16181.html.) I'm
not sure why.

Replaceable items: this is fine too, and the <varname> DITA tag does
this job; it translates into <var> in HTML. However, the syntax
statement in the table is in fixed-width plain, when fixed-width bold is
more usual.

Probably some other things for which italic is used should be added to
the table. These include book titles and section references; the <cite>
tag works for these. (I would have added words that are emphasized, but
DITA doesn't seem to believe in emphasis; there is no tag equivalent to
HTML <em> -- which actually is what DITA <i> tags are translated into.)

A number of items are listed as "Bold and/or fixed-width." This seems to
give more leeway than is usual, though I gather it is meant to be more
descriptive than prescriptive. However, there seems to be some
consistency in how these are used in the books (I think you may have
worked on making this so), so the descriptions could be narrowed in most
cases.

SQL examples: These seem to be nearly always fixed-width bold.
<codeblock><b> is commonly used for examples. This translates into
<pre><strong>.

Java application examples: These are less consistent -- sometimes
fixed-width bold (in the Ref Manual) and sometimes fixed-width but not
bold (in the Dev Guide and Admin Guide). I have to say I prefer the
plain fixed-width, but if there is a much larger volume of text
currently in fixed-width bold it would make sense to go with that.

Things you type in a command prompt: These usually seem to be
fixed-width bold. <userinput> translates into <kbd>, which is
fixed-width but not bold, so when you use it you have to add a <b> tag.
This is also the case with <codeblock>.

Comments within examples: These are usually fixed-width bold, too, when
the SQL examples are. Sometimes with Java examples I have seen the
comment in bold but the code in plain fixed-width
(http://db.apache.org/derby/docs/dev/devguide/rdevconcepts88082.html).
This has the merit of differentiating comments from code, but is more
work for the writer.

SQL keywords (commands) in all caps: this is fine (no DITA tags).

It might be good to mention command syntax, which usually seems to be in
fixed-width bold, with the replaceable items in fixed-width bold italic
(using a <codeblock>).

There is no doc convention listed for commands that are not SQL
commands, like ij, sysinfo, java, and the like. Possibly as a result,
there's not much consistency in how these are done. I notice that the
DITA <cmdname> tag translates into plain text -- in HTML it comes out as
<span class="cmdname">, but this translates into nothing. So these
commands are sometimes in <codeph> tags, sometimes in plain text, and
occasionally in bold. They don't seem to be in italic, though. We could
file a bug to get <cmdname> to translate into something (my inclination
would be fixed-width, though italics would be more consistent with other
code-related items).

Another item not mentioned is computer output (after you type a
command); this is usually in plain fixed-width. (The <systemoutput> DITA
tag translates to <tt> in HTML.)

So the possible JIRA issues I see from this are:

1) Update the doc conventions in Getting Started
2) Get toolkit fixed so <filepath> translates into italic
3) Get toolkit fixed so <cmdname> translates into fixed-width (?)

I'm not sure how technically feasible the latter two are.

Sorry this is so long. I appreciate any feedback!

Thanks,
Kim Haase

Re: Documentation conventions, DITA, and the toolkit

[Kim Haase <Ca...@Sun.COM>]

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 <Ca...@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

Re: Documentation conventions, DITA, and the toolkit

[Laura Stewart <sc...@gmail.com>]

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.

Section - Overall, New Terms, File Names/Paths

On 11/8/06, Kim Haase <Ca...@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.

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?

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?

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

-- 
Laura Stewart