[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455792 ] Laura Stewart commented on DERBY-1972: --------------------------------------
Hi Kim - Re doc conventions. I think that we should not tie ourselves to what was done before. I say that because it is my understanding that the library of docs is a mis-mash of conventions from the companies that you named and from contributors who didn't have any guidelines to go by and used what was seen in other parts of the documentation. I want us to see the new conventions and (over time) implement them as we can. So for tags that are in DITA like filepath and cmdname, which currently don't have any formatting from the toolkit, I think that we should decide what the format should be an figure out how to change the xsl files. Like you, I am used to using italic for just a few limited things - the very ones that you mentioned :-) And monospace (aka codeph) for lots of other things. So, how about you implement what seems reasonable from my comments and lets start a discussion on the list about the formatting conventions that we do want to use. And if I have convinced you to use codeblock for non-code stuff, then you have convinced me to use userinput and systemoutput (although I think we can set the bold for the format for userinput thus eliminating the need to apply both bold and userinput ! I don't know XSL and have a few other things on my plate for the remainder of this year, but for early next year I want to start learning it so that when we agree on a format change, we can implement it. One of the things that I need to do this year is look at the new toolkit to see if it implements any new formats for us :-) Thanks Kim ! > 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
