db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart" <scotsmat...@gmail.com>
Subject Re: [jira] Commented: (DERBY-408) Fix formatting of manuals in PDF output
Date Mon, 16 Oct 2006 22:13:40 GMT
Hi Kim -

I think that there is a LOT of tagging in the Derby docs that needs to
be reviewed and corrected :-)

One of the problems that Derby has is that there aren't any tagging
standards.  I want to propose some on the list and perhaps you can
comment on your perspective and we can come to some consenscious which
can then be documented on the Derby Documentation web page.

I don't think the owner (whoever they are) will be offended if you
open an issue to fix the tagging in WWD.

And yes, I don' t think that italic is the correct format for output.
Most DITA files that I have worked with use <codeblock>


On 10/16/06, Kim Haase <Camilla.Haase@sun.com> wrote:
> Hi, Laura,
> Thanks for this comment. I've been wondering about the tagging in the
> Working with Derby book -- I think it is often unconventional (should
> output be in italics?? I don't think so). There is a DITA - to - XSL-FO
> problem, as you say, but possibly the formatting should be cleaned up
> too. This would be a separate bug, though. I could file it (and fix it)
> if you think it would be worth while.
> I'm sending this offline as I don't know who contributed the WWD book --
> it's good to have it and the content is very useful -- and I don't want
> to hurt their feelings.
> Kim
> Laura Stewart (JIRA) wrote On 10/16/06 12:25,:
> >     [ http://issues.apache.org/jira/browse/DERBY-408?page=comments#action_12442633
> >
> > Laura Stewart commented on DERBY-408:
> > -------------------------------------
> >
> > I don't believe that the documentation should use tags like bold <b> to force
line breaks. Infact, in most cases there shouldn't be bold tags inside of codeblocks and syntax.
 Typically uppercase letters are used for the required SQL and lowercase letters for the variables
such as index-name. Sometimes <varname> is used for the variables, which displays the
text in italic.
> >
> > This sounds like a DITA - to - XSL-FO problem.
> >
> >
> >>Fix formatting of manuals in PDF output
> >>---------------------------------------
> >>
> >>                Key: DERBY-408
> >>                URL: http://issues.apache.org/jira/browse/DERBY-408
> >>            Project: Derby
> >>         Issue Type: Bug
> >>         Components: Documentation
> >>        Environment: all
> >>           Reporter: Jeff Levitt
> >>        Assigned To: Andrew McIntyre
> >>           Priority: Minor
> >>            Fix For:
> >>
> >>        Attachments: derby-408.diff
> >>
> >>
> >>1.  The syntax boxes in many of the Derby manuals seem to output with extra End-of-line
feeds in the PDF's.  Some syntax boxes print one word per line.   For example:
> >>http://incubator.apache.org/derby/docs/tools/tools-single.html#rtoolsijpropref10135
> >>This might be a bug with the DITA toolkit, because the DITA source files dont
have these End-of-line feeds in them.
> >>This bug was originally reported in the doc reviews for version 10.1:
> >>http://issues.apache.org/jira/browse/DERBY-383
> >>(see Myrna's comments)
> >>2.  Based on http://issues.apache.org/jira/browse/DERBY-384 comments to the doc
review (see Sunitha's comments), we need to figure out how to et the table numbers to ascend.
 Currently, they all output as table 1.
> >
> >

Laura Stewart

View raw message