firebird-docs

[Firebird-docs] ATTN Darcy, and all: PDF rendering

[Paul V. <pa...@vi...>]

Hi Darcy,

Here are the issues I've found in the PDF you made with Ventura. I
have no idea how easy or difficult it will be to fix them, but most of
them *must* be fixed because they really "break" the doc.

Just an idea: would it be easier if you imported the HTML instead of
the XML? Because in the HTML, the rendering has already taken place. I
can easily set up a target so that what needs to become one PDF file
is also in one HTML file (unlike now, where it is chunked into
top-level sections).

OK, here goes:

- "Chapter One" shouldn't be there (single-chapter doc).

- Can URL/email links be made to work? It's not critical, but it
  would be nice.

- Speaking of which: URL links wreak havoc all over the place: they
  are formatted as a block (should be inline) and they "outdent"
  from their surrounding blockquotes, listitems etc. instead of
  respecting the current indentation/margins. They also tend to
  break away from the listitems they're supposed to belong to.

- <sect1>: Leave more vertical space before it (say 1.5 times as much
  as now). Within an <article> (as opposed to a <book>) it would be
  nice if <sect1>s started on a new page (but not very important).

- Blockquotes: bit more space before them (one line's worth).

- <quote> tags should not translate to italics. Italics emphasize,
  whereas quotes often relativize. Best translate them as surrounding
  double-quotes.

- Sometimes spaces get eaten after a tag, e.g.: "primerif" and
  "primersif" under "DocBook XML - An Introduction".

- Internal links should work.

- <programlisting>s should honour whitespace, especially newlines
  and start-of-line spaces/tabs. A fixed-width font is also highly
  desirable here.
  OTOH, no extra whitespace or newlines must be added. This goes
  wrong under "Typing text" where the text demonstrates that an
  "unreadable" layout has the same validity as a pretty one.

- If a programlisting occurs within an indented block, it should not
  "outdent" from the block. Same goes for <example>s.

- The element <sgmltag class="starttag"> should be translated to '<'
  + element content + '>', like in the HTML. If class = "endtag", it
  should be rendered as '</' + constant + '>'. For "emptytag", it's
  '<' + content + '/>'
  Now you see in the PDF: "italics is a start tag, italics is an end
  tag, ..." - you don't see the difference between the two.

- The element <sgmltag class="genentity"> should be translated to '&'
  + element content + ';', like in the HTML. In the PDF it now says:

      ...you type this:

        lt

      That's an ampersand, followed by the letters l and t (for less
      than), followed by a semicolon.

  The "lt" should be "&lt;" of course, otherwise the whole point of
  the text is lost.

- Content of <literal> elements should stand out typographically. The
  usual solution is to use a fixed-width font with the same size as
  the surrounding text. No italics or boldface. And keep it inline.

- <emphasis> should stand out, preferably as italics. But:
    <emphasis role="bold"> should always be rendered in boldface.

- Admonitions (<caution>, <important>, <note>, <tip>, and <warning>)
  should be recognizable as such. They should be formatted as a block,
  indented or with a frame around it, possibly in a smaller font, and
  with some kind of caption denoting what it is: a note, a warning,
  a tip, ...
  Of course this can also be a graphic (light bulb for a tip, excl.
  mark for a warning etc.)

- Paragraphs within a listitem shouldn't get bullets of their own -
  this makes them look like extra listitems. I see this happen in
  itemizedlists and variablelists.

- listitems in an <orderedlist> should not have bullets, but (by
  default) Arabic numerals. Unless otherwise specified by the
  "numeration" attribute.

- <literallayout> and <screen> MUST honour the source layout!
  <screen> must have fixed-width font.

- Tables: <tfoot> elements should wind up at the foot of the table,
  not near the top. <thead> and <tfoot> content should be printed
  bold or italic (preferably bold) to distinguish them from ordinary
  rows.
  "align" attributes should be honoured if possible.

- command, application, superscript and subscript tags should be
  honoured. Same for all those other tags discussed under "Various
  inline elements". It's OK if you render them all the same as
  <literal> (see above).

- <computeroutput> is an inline element and shouldn't be formatted
  as a block.

- Spaces before a smiley :-) are eaten in the PDF.

- A nested list should have its own indentation level and preferably
  also another type of bullet. This goes wrong under "Style".


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[Darcy O'N. <ds...@sk...>]

Hello,

I believe 90% of these are easily fixed in Ventura, the other 10% 
shouldn't be much harder since Ventura supports scripting which will 
allow me to correct any issues. For example the ampersand issue would 
use a script to fix the import problem.

I'll see what I can fix up in the next few days.

Darcy

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[Darcy O'N. <ds...@sk...>]

Hello,

Well things are moving along pretty well. Here are a few remaining 
issues, some discussion might help resolve them, plus it will give you 
more background on the process.

1. Chapter 1 - Basically, with Ventura a chapter system allows linking 
from the Table of Contents, also we can create one large book from 
multiple XML files. Even though we may have one big book, we could still 
have individual docs.

2. URL Links - Can be fixed, some links will have to me manually 
identified and created but it's a small job that I will do.

3. URL Wreaking Havoc - Mostly fix, a few small adjustments but looks good.

4a. <sect1> Vertical Space  - this is a preference issue, design wise it 
is infinitely adjustable
4b. <sect1> New Page - Looks good for websites, absolutely horrible for 
books, to much white space  and actually that would be  a chapter if you 
did a page break after every <sect1>

5. Blockquotes - Fixed

6. <quote> Double Quotes - Fixed

7. Space Eater (primerif) - Fixed

8. Internal Links - Will work again might require manual intervention

9. <programlisting> White Space - This is the big issue that needs some 
more experimenting. Manual intervention worst case

10. <sgmltag class="starttag"> - Fixed

11. <sgmltag class="genentity"> - Fixed

12. <literal> - Fixed

13. <emphasis> - Fixed

14. Admonitions - Fixed - Graphics will be added later

15. Paragraphs within a listitem shouldn't get bullets - this will be an 
interesting issue as the <para> is so common but Ventura has a hard time 
working with nested tags. Should be able to fix but needs more research

16. listitems in an <orderedlist> - Fixed

17. <literallayout> - partially fixed

18. Tables - Future (can be fixed)

19. command, application, subscript etc. Fixed

20. <computeroutput> - Fixed

21. Smiley's - In professional docs???

22. Nested Lists - Fixed

I'll post a followup message detailing some future issues that may come up.

Darcy

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[Paul V. <pa...@vi...>]

Hi Darcy,

A lot of things fixed already, great!

> 1. Chapter 1 - Basically, with Ventura a chapter system allows
> linking from the Table of Contents, also we can create one large
> book from multiple XML files. Even though we may have one big book,
> we could still have individual docs.

But is it mandatory that a doc (a single PDF file) have at least one
chapter? It's not the end of the world, but it looks a little silly to
have a document with just a "Chapter One" and no other chapters, even
though it is in itself complete. Oh well, if we can't change this, we
can put the Docbuilding + Docwriting Howtos in one PDF (they already
form one DocBook <book> together).

> 4a. <sect1> Vertical Space - this is a preference issue, design wise
> it is infinitely adjustable.
> 4b. <sect1> New Page - Looks good for websites, absolutely horrible
> for books, to much white space and actually that would be a chapter
> if you did a page break after every <sect1>

OK, agreed. The point is that the Docwriting Howto turned out a lot
bigger than I had originally envisaged. Some of the sections look more
like chapters. No problem as long as we have that extra vertical space
before <sect1>'s (and a little less before <sect2>'s, etc.)

> 10. <sgmltag class="starttag"> - Fixed
> 11. <sgmltag class="genentity"> - Fixed

Class endtag too, I suppose? Anyway it's the same procedure.

> 21. Smiley's - In professional docs???

Sure, why not? :-)

This was a doc for fellow (aspiring) docwriters. Tone is a little more
familiar here and there.

Maybe the space got eaten because Ventura thinks there should't be a
space before a colon? This has to be fixed, because there are also
other situations where a space precedes a colon, e.g. in a C code
fragment or in a ratio.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[dso <ds...@sk...>]

Hello,

>>1. Chapter 1 - Basically, with Ventura a chapter system allows
> 
> But is it mandatory that a doc (a single PDF file) have at least one
> chapter? It's not the end of the world, but it looks a little silly to
> have a document with just a "Chapter One" and no other chapters, even
> though it is in itself complete. Oh well, if we can't change this, we
> can put the Docbuilding + Docwriting Howtos in one PDF (they already
> form one DocBook <book> together).

Actually the Chapter can be removed for single doc's no problem. But if 
we do go to a 'complete' book then the chapters are beneficial. In the 
separated Chapters I just need to create a 'chapterless' template. Easy 
enough.

>>4a. <sect1> Vertical Space - this is a preference issue, design wise
>>4b. <sect1> New Page - Looks good for websites, absolutely horrible
> 
> OK, agreed. The point is that the Docwriting Howto turned out a lot
> bigger than I had originally envisaged. Some of the sections look more
> like chapters. No problem as long as we have that extra vertical space
> before <sect1>'s (and a little less before <sect2>'s, etc.)

Can be done, I'm going make some modifications to the layout etc., and 
then put a copy on my website for you to review. We'll do the final 
adjustments as we go.

>>10. <sgmltag class="starttag"> - Fixed
>>11. <sgmltag class="genentity"> - Fixed
> Class endtag too, I suppose? Anyway it's the same procedure.

Yep, those all work.

>>21. Smiley's - In professional docs???
> Sure, why not? :-)
> 
> This was a doc for fellow (aspiring) docwriters. Tone is a little more
> familiar here and there.

OK, now I just need to see if Smiley's are supported in Ventura.

> Maybe the space got eaten because Ventura thinks there should't be a
> space before a colon? This has to be fixed, because there are also
> other situations where a space precedes a colon, e.g. in a C code
> fragment or in a ratio.

I think maintaining 'spaces' is going to be the hardest part of these 
doc's. Ventura supports formatting without problems i.e. cut and paste a 
text doc into Ventura and it will keep the tabs and spacing perfectly. 
Import XML and it doesn't see the spaces because it see the doc as a XML 
file and removes all spacing, then applies formating to the tags.

Anyway, like I said, worst case scenario requires a little hand editing 
prior to final publishing.

Darcy

[Firebird-docs] Spaces (was: PDF rendering)

[Paul V. <pa...@vi...>]

Hi Darcy,

>> Maybe the space got eaten because Ventura thinks there should't be
>> a space before a colon? This has to be fixed, because there are
>> also other situations where a space precedes a colon, e.g. in a C
>> code fragment or in a ratio.

> I think maintaining 'spaces' is going to be the hardest part of
> these doc's. Ventura supports formatting without problems i.e. cut
> and paste a text doc into Ventura and it will keep the tabs and
> spacing perfectly.  Import XML and it doesn't see the spaces because
> it see the doc as a XML file and removes all spacing, then applies
> formating to the tags.

I don't understand this. Sure it can remove all spacing *between*
elements, i.e. it can convert

  <section>
    <para>
      <emphasis>
         Don't forget this!
      </emphasis>
    </para>
  </section>

to:

  <section><para><emphasis>Don't forget this!</emphasis></para></section>

But here we're talking about spacing between words etc. *inside*
elements. I suppose Ventura doesn't convert <para>This is some
text</para> to <para>Thisissometext</para>, and neither should it
convert <para>a = x == y ? b : c</para> to <para>a=x==y?b:c</para> or
<para>Hi :-)</para> to <para>Hi:-)</para>


Greetings,
Paul Vinkenoog