[ 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> for). 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: 10.2.1.6 > 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
