Early look: Trafodion SQL Reference Guide

[Gunnar Tapper <ta...@gmail.com>]

Hi,

I've spent the last few days figuring out asciibook PDF themes, their
capabilities, limitations, and gotchas. A lot of trial and error but now I
have something that's workable.

I'm attaching a rendered Web Book and PDF version of the Trafodion SQL
Reference Manual or rather, the pieces I've ported so far.

A couple of limitations:

1. Can't use text formatting in example blocks. So, no italics.
2. Can't indent text without custom CSS work, which does not translate into
the PDF rendering. You have to use bullets and sub-bullets to achieve
indentation.

I'd like your input on:

1. This guide is VERY link rich including links within a subsection. For
example, see the ALTER TABLE Statement. Should we remove the
within-statement links?
2. I go back and forth on syntax highlighting mostly because the
highlighter doesn't know verbs such as "invoke", which makes the
highlighting inconsistent. Keep or drop.

-- 
Happy New Year,

Gunnar
*If you think you can you can, if you think you can't you're right.*

Re: Early look: Trafodion SQL Reference Guide

[Kevin DeYager <ke...@gmail.com>]

Hi Gunnar,



Excellent progress.  I know that this is a significant amount of work.
Trafodion’s heritage gives is an outstanding set of reference documentation
but with that also comes complexity.  Would remove the within-statement
links.  That’s a lot of linking to maintain and time can better be spent on
updating the documentation.  I also agree with you that the inconsistencies
in the highlighter are annoying and even a bit confusing, so my preference
would be to replace it with plain text.

- Kevin

On Thu, Dec 31, 2015 at 12:37 PM, Gunnar Tapper <ta...@gmail.com>
wrote:

> Hi,
>
> I've spent the last few days figuring out asciibook PDF themes, their
> capabilities, limitations, and gotchas. A lot of trial and error but now I
> have something that's workable.
>
> I'm attaching a rendered Web Book and PDF version of the Trafodion SQL
> Reference Manual or rather, the pieces I've ported so far.
>
> A couple of limitations:
>
> 1. Can't use text formatting in example blocks. So, no italics.
> 2. Can't indent text without custom CSS work, which does not translate
> into the PDF rendering. You have to use bullets and sub-bullets to achieve
> indentation.
>
> I'd like your input on:
>
> 1. This guide is VERY link rich including links within a subsection. For
> example, see the ALTER TABLE Statement. Should we remove the
> within-statement links?
> 2. I go back and forth on syntax highlighting mostly because the
> highlighter doesn't know verbs such as "invoke", which makes the
> highlighting inconsistent. Keep or drop.
>
> --
> Happy New Year,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
>

Re: Early look: Trafodion SQL Reference Guide

[Kevin DeYager <ke...@gmail.com>]

Hi Gunnar,



Excellent progress.  I know that this is a significant amount of work.
Trafodion’s heritage gives is an outstanding set of reference documentation
but with that also comes complexity.  Would remove the within-statement
links.  That’s a lot of linking to maintain and time can better be spent on
updating the documentation.  I also agree with you that the inconsistencies
in the highlighter are annoying and even a bit confusing, so my preference
would be to replace it with plain text.

- Kevin

On Thu, Dec 31, 2015 at 12:37 PM, Gunnar Tapper <ta...@gmail.com>
wrote:

> Hi,
>
> I've spent the last few days figuring out asciibook PDF themes, their
> capabilities, limitations, and gotchas. A lot of trial and error but now I
> have something that's workable.
>
> I'm attaching a rendered Web Book and PDF version of the Trafodion SQL
> Reference Manual or rather, the pieces I've ported so far.
>
> A couple of limitations:
>
> 1. Can't use text formatting in example blocks. So, no italics.
> 2. Can't indent text without custom CSS work, which does not translate
> into the PDF rendering. You have to use bullets and sub-bullets to achieve
> indentation.
>
> I'd like your input on:
>
> 1. This guide is VERY link rich including links within a subsection. For
> example, see the ALTER TABLE Statement. Should we remove the
> within-statement links?
> 2. I go back and forth on syntax highlighting mostly because the
> highlighter doesn't know verbs such as "invoke", which makes the
> highlighting inconsistent. Keep or drop.
>
> --
> Happy New Year,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
>