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 Documentation conventions, DITA, and the toolkit
Date Wed, 08 Nov 2006 16:35:45 GMT
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


Mime
View raw message