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
