db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup
Date Tue, 05 Dec 2006 22:07:23 GMT
    [ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455773 ] 
Kim Haase commented on DERBY-1972:

Thank you, Laura! You have gone way beyond what I did and found things I had not noticed or
known how to deal with, including things in the original version that I had just left as is
because I was making so many other changes. To most of what you say my answer is just Yes!
I'll make those fixes. I'm glad you looked at the index entries, for example; since they don't
yet show up in the output, I have been ignoring them.

You've also raised a bunch of interesting philosophical issues about DITA. I guess I was somewhat
narrowly focused on using DITA "properly," that is on using tagging for semantic purposes
(to the extent the somewhat buggy toolkit would allow). Whereas another major goal to keep
in mind, as you point out, is usability by a large community whose main goal is to fix content
and not to have to worry too much about tagging.

Hence the answers to some of the questions you raise:

Why <pre>? Well, according to the DITA spec, <codeblock> is a programming element
meant just for "lines of program code," whereas <pre> -- which is familiar to those
who know HTML -- is for any other kind of preformatted text, such as command input and output.
However, DITA really violates its own rules, because it allows all sorts of things inside
a codeblock that are not normally part of program code: in fact, everything that's allowed
inside <pre> is also allowed inside <codeblock> and vice versa. So what the heck.
You've convinced me. We've been using <codeblock>, so let's stick with it.

Similarly I was using <userinput> and <systemoutput> semantically. The DTD we
use at Sun has <userinput> so I was used to it. But if our goal is simplicity there
is really no need for these.

There was also some weird stuff about certain formatting tags within codeblocks getting munged
(the toolkit ignoring spaces between them). I think whatever tags I used solved that problem;
I'll have to experiment to find what else works.

You also raise some good points about our doc conventions (the ones in the Getting Started
manual). There are really a couple of separate issues -- what we want certain things to look
like, and how to do that with the toolkit (the current one anyway; I haven't had time to try
the new one). 

Speaking of the toolkit, the first thing you noticed -- "PDF copyright (page 4) appears run
together" -- has been the case for all the docs since 10.1 I think. You mean the fact that
the string "Apache Software FoundationWorking With DerbyApache Derby" is all stuck together
in both the PDF and the monohtml version, I think? If this is not already a JIRA issue we
should make it one, and if it is maybe we should raise its priority.

I think the contribution line and the rev attributes must date from when the files were first
checked in. I had not thought about them, but I guess none of our other books use them. It
probably makes sense to remove those.

I am not clear exactly what you mean by "the way that the text in the steps runs together"
-- could you clarify that? There are at least two problems of that nature: vertical spacing
in the HTML; and the fact that in the PDF and monohtml, the toolkit removes any space between
the output of a <ph> (like "Derby") and anything before or after it that is not in plain
text font. Possibly others!

Re doc conventions -- I used italics for the database names because they are "dictionary objects"
(not a term I'm used to, but I looked it up) and for the message log because it is a file.
I would like to use <filepath> for files and directories, but as you say, the toolkit
doesn't provide any formatting for this tag. Same with <cmdname> for commands -- it
would be very handy, but if you use it, there's no formatting for it. We can file a bug after
we decide what format we want.

Also you asked about method names. They seem to be in italics in other books -- for example,
in the JDBC material in the Reference Manual. I am used to monospace for method names and
for all other programming terms. And I'm also used to monospace (<codeph>) for files,
directories, database names, commands and, in fact, most of the things that the doc conventions
specify italics for. The only things I'm used to italics for are new terms, emphasis, book
titles, and placeholders to be replaced with a real name or value (what we use <varname>

However, though the typographic conventions in Getting Started seem strange to me, I'm willing
to adopt them if I can figure out the principle behind them. The latest theory I have come
up with is that every programming or database term in body text that isn't in all caps (like
environment variables and SQL commands) is supposed to be in italics -- whereas I'm used to
those things being in monospace (even the all-caps ones). There's some inconsistency in the
docs, so I'm not sure this principle really works, but it's the best I can come up with. Do
you have any idea of the history behind the current conventions -- do they come from IBM,
or Informix, or Cloudscape before it was bought? 

If we stick with that principle, then we can ask for <filepath> and <cmdname>
to be output in italics, and I can fix command names and attributes and whatnot in the Working
With Derby book to be in italics too.

In the meantime, I'll work on these fixes. Thanks again!

> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>                 Key: DERBY-1972
>                 URL: http://issues.apache.org/jira/browse/DERBY-1972
>             Project: Derby
>          Issue Type: Bug
>          Components: Documentation
>    Affects Versions:
>            Reporter: Kim Haase
>         Assigned To: Kim Haase
>            Priority: Minor
>         Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip,
DERBY-1972.zip, DERBY_1972.diff
> The Working With Derby book uses DITA tags in ways that are not always consistent with
the usage in other books and that lead to some problems in the processed output. Some examples
are the use of the <varname> tag in inappropriate places and the use of formatting tags
within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.

This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira


View raw message