firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Fixing XML issues in docbook

[Mark R. <ma...@la...>]

On 16-05-2020 15:17, Dmitry Yemanov wrote:
> 02.05.2020 19:50, Dmitry Yemanov wrote:
>>
>> For FB3, doing it now (or in May in general) is OK to me. For FB4, 
>> please wait until Beta 2 is published.
> 
> Mark, you may update the v4 RN files now, if required.

I have made the changes to the rlsnotes40 XML.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 15:18, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
>> Could you look at the overall style of things to see if there are things
>> you really don't like.
> 
>> https://www.lawinegevaar.nl/fbdocs/pdf/en/experiment/fblangref25.pdf
> 
> First reaction to the PDF:
> 
> - Overall, OK!
> 
> - Document title and author listing: really don't like the right-alignment here,
> I'd rather see it left-aligned or centered.
> 
> - Navigation pane: only has a depth of 2 (chapter and top-level paragraph).
> This means that lots of 2nd- and 3rd-level paragraphs are now missing from
> the nav pane. It would be very useful having them back.
> 
> - Some of the fonts are not very pleasant to the eye (at least my eye); they
> look horizontally compressed.
> 
> - Some other fonts are too big (e.g. in Examples sections), but I guess you
> already know that; this is simple a matter of adjustment, nothing complicated.

I made some minor tweaks: 
https://www.lawinegevaar.nl/fbdocs/pdf/en/experiment/fblangref25/fblangref25.pdf

Specifically I changed:
- admonition captions/titles are now bold instead of italic
- text on title page is now centered

With regard to the code font, I didn't want to spend too much time 
experimenting with that now. As to the size of fonts being too big in 
examples sections, that is due to the use of blockquotes, so it should 
disappear once I have removed them, and otherwise we can tweak the size 
further later.

Mark
-- 
Mark Rotteveel

[Firebird-docs] [FirebirdSQL/firebird-documentation] afa09b: Rename rlsnotes40 rename .docbook to .xml, use inc...

[Mark R. <no...@gi...>]

  Branch: refs/heads/master
  Home:   https://github.com/FirebirdSQL/firebird-documentation
  Commit: afa09bd79ce6ff4a3a30b1b76a5bc5e41b9e4856
      https://github.com/FirebirdSQL/firebird-documentation/commit/afa09bd79ce6ff4a3a30b1b76a5bc5e41b9e4856
  Author: Mark Rotteveel <ma...@la...>
  Date:   2020-05-16 (Sat, 16 May 2020)

  Changed paths:
    R src/docs/rlsnotes/rlsnotes40/APIandODS40.docbook
    A src/docs/rlsnotes/rlsnotes40/APIandODS40.xml
    R src/docs/rlsnotes/rlsnotes40/Appendix01_40.docbook
    A src/docs/rlsnotes/rlsnotes40/Appendix01_40.xml
    R src/docs/rlsnotes/rlsnotes40/BugFixes40.docbook
    A src/docs/rlsnotes/rlsnotes40/BugFixes40.xml
    R src/docs/rlsnotes/rlsnotes40/Compatibility40.docbook
    A src/docs/rlsnotes/rlsnotes40/Compatibility40.xml
    R src/docs/rlsnotes/rlsnotes40/ConfigParams40.docbook
    A src/docs/rlsnotes/rlsnotes40/ConfigParams40.xml
    R src/docs/rlsnotes/rlsnotes40/DDL40.docbook
    A src/docs/rlsnotes/rlsnotes40/DDL40.xml
    R src/docs/rlsnotes/rlsnotes40/DML40.docbook
    A src/docs/rlsnotes/rlsnotes40/DML40.xml
    R src/docs/rlsnotes/rlsnotes40/Engine40.docbook
    A src/docs/rlsnotes/rlsnotes40/Engine40.xml
    R src/docs/rlsnotes/rlsnotes40/FbTeams40.docbook
    A src/docs/rlsnotes/rlsnotes40/FbTeams40.xml
    R src/docs/rlsnotes/rlsnotes40/GeneralNotes40.docbook
    A src/docs/rlsnotes/rlsnotes40/GeneralNotes40.xml
    R src/docs/rlsnotes/rlsnotes40/Licence40.docbook
    A src/docs/rlsnotes/rlsnotes40/Licence40.xml
    R src/docs/rlsnotes/rlsnotes40/MSQL40.docbook
    A src/docs/rlsnotes/rlsnotes40/MSQL40.xml
    R src/docs/rlsnotes/rlsnotes40/NewFeatures40.docbook
    A src/docs/rlsnotes/rlsnotes40/NewFeatures40.xml
    R src/docs/rlsnotes/rlsnotes40/PSQL40.docbook
    A src/docs/rlsnotes/rlsnotes40/PSQL40.xml
    R src/docs/rlsnotes/rlsnotes40/ReservedWords40.docbook
    A src/docs/rlsnotes/rlsnotes40/ReservedWords40.xml
    R src/docs/rlsnotes/rlsnotes40/Security40.docbook
    A src/docs/rlsnotes/rlsnotes40/Security40.xml
    R src/docs/rlsnotes/rlsnotes40/Utilities40.docbook
    A src/docs/rlsnotes/rlsnotes40/Utilities40.xml
    M src/docs/rlsnotes/rlsnotes40/rlsnotes40.xml

  Log Message:
  -----------
  Rename rlsnotes40 rename .docbook to .xml, use include


  Commit: 2bda0f9cc668c0cfe3a33613118de5db060c310c
      https://github.com/FirebirdSQL/firebird-documentation/commit/2bda0f9cc668c0cfe3a33613118de5db060c310c
  Author: Mark Rotteveel <ma...@la...>
  Date:   2020-05-16 (Sat, 16 May 2020)

  Changed paths:
    M src/docs/rlsnotes/rlsnotes40/APIandODS40.xml
    M src/docs/rlsnotes/rlsnotes40/Appendix01_40.xml
    M src/docs/rlsnotes/rlsnotes40/BugFixes40.xml
    M src/docs/rlsnotes/rlsnotes40/Compatibility40.xml
    M src/docs/rlsnotes/rlsnotes40/ConfigParams40.xml
    M src/docs/rlsnotes/rlsnotes40/DDL40.xml
    M src/docs/rlsnotes/rlsnotes40/DML40.xml
    M src/docs/rlsnotes/rlsnotes40/Engine40.xml
    M src/docs/rlsnotes/rlsnotes40/FbTeams40.xml
    M src/docs/rlsnotes/rlsnotes40/GeneralNotes40.xml
    M src/docs/rlsnotes/rlsnotes40/Licence40.xml
    M src/docs/rlsnotes/rlsnotes40/MSQL40.xml
    M src/docs/rlsnotes/rlsnotes40/NewFeatures40.xml
    M src/docs/rlsnotes/rlsnotes40/PSQL40.xml
    M src/docs/rlsnotes/rlsnotes40/ReservedWords40.xml
    M src/docs/rlsnotes/rlsnotes40/Security40.xml
    M src/docs/rlsnotes/rlsnotes40/Utilities40.xml
    M src/docs/rlsnotes/rlsnotes40/rlsnotes40.xml

  Log Message:
  -----------
  Fix XML issues in rlsnotes/rlsnotes40


Compare: https://github.com/FirebirdSQL/firebird-documentation/compare/26f1e3dc856d...2bda0f9cc668

Re: [Firebird-docs] Fixing XML issues in docbook

[Dmitry Y. <fir...@ya...>]

02.05.2020 19:50, Dmitry Yemanov wrote:
> 
> For FB3, doing it now (or in May in general) is OK to me. For FB4, 
> please wait until Beta 2 is published.

Mark, you may update the v4 RN files now, if required.


Dmitry

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 14:22, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
>> I have published an PDF and HTML version of the Firebird 2.5 Language
>> Reference built from asciidoc. I have used some elements of style from
>> the old documentation, but a lot of it is based on the standard asciidoc
>> styles.
>>
>> Could you look at the overall style of things to see if there are things
>> you really don't like.
>>
>> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25.html
> 
> First impressions of the HTML (after 1-2 minutes of reading and scrolling):
> 
> - Font size is rather biggish. Maybe 10% smaller or so would be better and
> more in line with the average informative website?

I tweaked the font size a bit:
https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25.html

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 21:05, Mark Rotteveel wrote:
> I see what you mean. I'll publish a variant later this week that has the 
> animation disabled. Alternatively, you could try this yourself by 
> disabling (or changing) the transition rule on #tocbot .is-collapsible.

For comparison:

Version with standard transition delay:
https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25-stddelay.html

Version without transition delay:
https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25-nodelay.html

Mark

-- 
Mark Rotteveel

[Firebird-docs] [FirebirdSQL/firebird-documentation] 26f1e3: Corrections and additions for Beta 2

[Dmitry Y. <no...@gi...>]

  Branch: refs/heads/master
  Home:   https://github.com/FirebirdSQL/firebird-documentation
  Commit: 26f1e3dc856d6dc07f910df270a9ad80a76b9017
      https://github.com/FirebirdSQL/firebird-documentation/commit/26f1e3dc856d6dc07f910df270a9ad80a76b9017
  Author: Dmitry Yemanov <dye...@us...>
  Date:   2020-05-12 (Tue, 12 May 2020)

  Changed paths:
    M src/docs/rlsnotes/rlsnotes40/APIandODS40.docbook
    M src/docs/rlsnotes/rlsnotes40/Compatibility40.docbook
    M src/docs/rlsnotes/rlsnotes40/ConfigParams40.docbook
    M src/docs/rlsnotes/rlsnotes40/DDL40.docbook
    M src/docs/rlsnotes/rlsnotes40/DML40.docbook
    M src/docs/rlsnotes/rlsnotes40/Engine40.docbook
    M src/docs/rlsnotes/rlsnotes40/GeneralNotes40.docbook
    M src/docs/rlsnotes/rlsnotes40/MSQL40.docbook
    M src/docs/rlsnotes/rlsnotes40/NewFeatures40.docbook
    M src/docs/rlsnotes/rlsnotes40/Security40.docbook
    M src/docs/rlsnotes/rlsnotes40/Utilities40.docbook
    M src/docs/rlsnotes/rlsnotes40/rlsnotes40.xml

  Log Message:
  -----------
  Corrections and additions for Beta 2

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

> On 11-05-2020 14:30, Paul Vinkenoog wrote:
> > Dmitry Yemanov wrote:
> > 
> >> 4) I don't like how titles of <note> / <important> blocks are rendered,
> >> they're just italic of the default size. I'd prefer a bigger font (and
> >> maybe a different colour) as it was in the old version.
> > 
> > I don't think it looks good if notes, warnings and the like have a bigger
> > font than the main text - just as long as they stand out by indentation,
> > a border, an icon, maybe italics (rather not bold), and/or cetera.
> 
> Dmitry is specifically talking about the title of an admonition (note, 

You're right, I didn't read that well.

> tip, warning). In the PDF the admonition title is in italics + slightly 
> smaller font than body text which doesn't make it really stand out. In 
> the HTML it is italic + darker than the body text of the admonition, but 
> also a slightly smaller font.
> 
> > BTW, in the old version (if you mean the current docs by that), notes
> > and other admonitions have a somewhat smaller font than the main
> > text (I prefer that, actually).
> 
> The current rendering (in HTML) uses the same size for the admonition 
> body as for the main text, but a slightly smaller font-size for the 
> title, which is a bit weird.

Indeed, it's just a bit smaller. I had't noticed that at first. It may even
'formally' be the same font size, but some italicization methods do that
(analogous to tilting a flagpole, which makes the top come closer to the
ground).

Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

> > Striping is evil, because it suggests that odd rows are of a different
> > nature than even rows, which of course they are not. It's also totally
> > unnecessary, because rows are separated by lines.
> >
> > Striping makes tables 'noisy' and less readable. IMO we should do
> > away with it.
>
> It can be disabled. Personally, in real tables (as in, showing data), I 
> prefer striping over borders, as long as the striping is subtle. In my 
> opinion it enhances readability.

I find it confusing because it suggests a difference that doesn't exist.
Of course, without lines or borders (i.e. if the only alternative is no
visual support at all) striping may be the lesser evil.

Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 11-05-2020 14:30, Paul Vinkenoog wrote:
> Dmitry Yemanov wrote:
> 
>> 4) I don't like how titles of <note> / <important> blocks are rendered,
>> they're just italic of the default size. I'd prefer a bigger font (and
>> maybe a different colour) as it was in the old version.
> 
> I don't think it looks good if notes, warnings and the like have a bigger
> font than the main text - just as long as they stand out by indentation,
> a border, an icon, maybe italics (rather not bold), and/or cetera.

Dmitry is specifically talking about the title of an admonition (note, 
tip, warning). In the PDF the admonition title is in italics + slightly 
smaller font than body text which doesn't make it really stand out. In 
the HTML it is italic + darker than the body text of the admonition, but 
also a slightly smaller font.

> BTW, in the old version (if you mean the current docs by that), notes
> and other admonitions have a somewhat smaller font than the main
> text (I prefer that, actually).

The current rendering (in HTML) uses the same size for the admonition 
body as for the main text, but a slightly smaller font-size for the 
title, which is a bit weird.

I'll see if I can tweak it a bit.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 11-05-2020 14:44, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
>> However the rendering of this table is very similar in the old and new
>> PDF docs, while in the new HTML it has striping, which it doesn't have
>> in the old HTML.
> 
> Striping is evil, because it suggests that odd rows are of a different
> nature than even rows, which of course they are not. It's also totally
> unnecessary, because rows are separated by lines.
> 
> Striping makes tables 'noisy' and less readable. IMO we should do
> away with it.

It can be disabled. Personally, in real tables (as in, showing data), I 
prefer striping over borders, as long as the striping is subtle. In my 
opinion it enhances readability.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

> However the rendering of this table is very similar in the old and new
> PDF docs, while in the new HTML it has striping, which it doesn't have
> in the old HTML.

Striping is evil, because it suggests that odd rows are of a different
nature than even rows, which of course they are not. It's also totally
unnecessary, because rows are separated by lines.

Striping makes tables 'noisy' and less readable. IMO we should do
away with it.

Cheers,
Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

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

Dmitry Yemanov wrote:

> 4) I don't like how titles of <note> / <important> blocks are rendered,
> they're just italic of the default size. I'd prefer a bigger font (and
> maybe a different colour) as it was in the old version.

I don't think it looks good if notes, warnings and the like have a bigger
font than the main text - just as long as they stand out by indentation,
a border, an icon, maybe italics (rather not bold), and/or cetera.

BTW, in the old version (if you mean the current docs by that), notes
and other admonitions have a somewhat smaller font than the main
text (I prefer that, actually).


Paul Vinkenoog
 

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 20:43, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
> [PDF]:
> 
>> Be aware that some tables are currently a bit mangled (both in spacing,
>> and in some cases having wrong number of columns), which might make this
>> look worse than normal. I'll see if I can clean it up, but that might be
>> better done as a cleanup step after migration.
> 
> I also see it in simple, straightfoward tables without spans etc., e.g. tables
> 34-36 and in paragraph 7.5.2 (DML Triggers) under 'Trigger options'.
> That last one is not a formal table btw. I hope this is not how a description
> list is rendered?

For table 34 (and 35 and 36) the primary difference is that it is 
currently rendered at 100% width (for HTML, with PDF that is also the 
case in the old documentation), and with wrong column proportions (1,1) 
instead of (1,3). The proportions I will fix, and I'll look at options 
for the width (eg %autowidth, or I might change it to a description list).

As for the table in 7.5.2, it is an informaltable in docbook. Asciidoc 
doesn't really distinguish between table and informaltable, except by 
the exact properties specified on them (for asciidoc, the distinguishing 
property between a table and informaltable is the presence or absence of 
a title). For the asciidoc version, the problem is that the width is now 
100% (in HTML), which I need to disable.

However the rendering of this table is very similar in the old and new 
PDF docs, while in the new HTML it has striping, which it doesn't have 
in the old HTML.

This looks like something I will need to manually fix after conversion, 
because I'm not sure if I can properly automate that. In fact, the 
current rendering of informaltable in our old docs is likely a property 
of our stylesheets.

>>> Same for unnecessary parentheses
>>> around language elements in tables.
>>
>> Do you have a specific example of this last thing, so I know what I
>> should look for?
> 
> Same 'table' under 'Trigger options', but also a similar one under 7.5.3,
> 'Database Triggers'.

Right, now I understand what you mean.

> Also, in these examples the text isn't vertically aligned on the baseline.
> The stuff within parentheses floats higher - not because of the parentheses
> I assume, but because of the different font.

Interesting, it might have to do with the parentheses though. In most 
monospace fonts, the parentheses dip below the baseline, but it looks 
like in the PDF the bottom of the parentheses is used as the baseline, 
so the text is elevated. I'm not sure if that is something I can fix, it 
might be a bug in asciidoctor-pdf. I'll check what happens with a 
different font or if I remove the parentheses.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 20:21, Paul Vinkenoog wrote:
> Mart Rotteveel wrote:
>>> - Font size is rather biggish. Maybe 10% smaller or so would be better and
>>> more in line with the average informative website?
>>
>> The font size is based on the default font size in your browser
>> settings. Would changing that setting be good enough for you?
> 
> Not really, because my default font size is simply the browser default
> (i.e. 'Ctrl-0'), and suits me fine on 90% of the sites I visit. If I set a
> smaller default, it will be too small for comfort on many other sites.
> 
> I uploaded an example here:
> 
>     http://firebird.vinkenoog.nl/Fontgroottes_uitsnede.png
> 
> where you can see, left to right: your rendering, the Firebird website and
> the BBC. The lowercase letter height is around 12% bigger on your site
> than on the other two; that of capitals 20% bigger than the Fb site and
> 10% bigger than the BBC.
> 
> The Firebird site is still fine with me, althought near the lower limit.
> 
> The Beeb is perfect (I think), and I imagine this size might be OK for
> many people.

The stylesheet I use defers to the browser font size by specifying the 
sizes in em units, while the Firebird website specifies font-size in px. 
The BBC also uses relative font size, but indeed looks a bit smaller.
I'll see if specifying the size to 90% instead of its default of 100% 
looks better.

I'll post a new version, or multiple versions later this week.

>> I'll see if I can add a wider padding, but reducing the font-size would
>> already 'fix' this.
> 
> Not if the padding was specified in ex units ;-)

Yes and no, because the content width is specified using em as well, 
reducing the font-size will likely cause the content block to reduce in 
size as well (unless your screen is of course already small).

In any case, I have been tweaking things a bit to get a similar padding 
as the old documentation (with the current font-config). I'll publish 
later this week.

[..]

>> I can't tweak much about this, except showing the three levels of the
>> TOC all the time. That kind of defeats the purpose why I added this in
>> the first place. And maybe I can tweak something about the animation of
>> the transition, but the current 300ms 'ease-in-out' animation applied
>> for expanding and collapsing is less fidgety than no delay to me, and
>> increasing the delay a lot further makes it seem sluggish, but will
>> reduce the jitter while scrolling very fast.
> 
> I realize now that what irritates me most is that first something goes down
> (as the newly focused section is expanded) and than it goes up again (as
> the previously focused section is collapsed). And this also happens if you're
> not scrolling, bust just click somewhere in the ToC. I think I'd prefer this
> instantaneoulsy.

I see what you mean. I'll publish a variant later this week that has the 
animation disabled. Alternatively, you could try this yourself by 
disabling (or changing) the transition rule on #tocbot .is-collapsible.

Mark

-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

[PDF]:

> > - In tables, sometimes the first column is centered and the second one
> > left-justified; sometimes the first is right-justified and the second left-justiified.
> > I know this is already the case in the existing LangRef, but I find it absolutely
> > horrible, so maybe we should fix this.
>
> Be aware that some tables are currently a bit mangled (both in spacing, 
> and in some cases having wrong number of columns), which might make this 
> look worse than normal. I'll see if I can clean it up, but that might be 
> better done as a cleanup step after migration.

I also see it in simple, straightfoward tables without spans etc., e.g. tables
34-36 and in paragraph 7.5.2 (DML Triggers) under 'Trigger options'.
That last one is not a formal table btw. I hope this is not how a description
list is rendered?

> > Same for unnecessary parentheses
> > around language elements in tables.
>
> Do you have a specific example of this last thing, so I know what I 
> should look for?

Same 'table' under 'Trigger options', but also a similar one under 7.5.3,
'Database Triggers'.

Also, in these examples the text isn't vertically aligned on the baseline.
The stuff within parentheses floats higher - not because of the parentheses
I assume, but because of the different font.

Cheers,
Paul

Re: [Firebird-docs] Example of new documentation

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

Mart Rotteveel wrote:

> > First impressions of the HTML (after 1-2 minutes of reading and scrolling):
> > 
> > - Font size is rather biggish. Maybe 10% smaller or so would be better and
> > more in line with the average informative website?
> 
> The font size is based on the default font size in your browser 
> settings. Would changing that setting be good enough for you?

Not really, because my default font size is simply the browser default
(i.e. 'Ctrl-0'), and suits me fine on 90% of the sites I visit. If I set a
smaller default, it will be too small for comfort on many other sites.

I uploaded an example here:

   http://firebird.vinkenoog.nl/Fontgroottes_uitsnede.png

where you can see, left to right: your rendering, the Firebird website and
the BBC. The lowercase letter height is around 12% bigger on your site
than on the other two; that of capitals 20% bigger than the Fb site and
10% bigger than the BBC.

The Firebird site is still fine with me, althought near the lower limit.

The Beeb is perfect (I think), and I imagine this size might be OK for
many people.

> > - I thought the horizontal margins around the main text were too small, but
> > then I noticed that they grow if I widen the window. This is not what one
> > expects in HTML, but it works. (However: could a minimum margin be imposed
> > that is bigger that the current one?)
> 
> This is pretty much standard today, this restricts the reading area to 
> about 50-70 characters wide is good for readability.

Agreed.

> Eg compare:
> https://www.firebirdsql.org/file/documentation/drivers_documentation/java/4.0.x/release_notes.html#general-notes
> with
> https://www.firebirdsql.org/file/documentation/drivers_documentation/java/2.2.x/release_notes.html#general-notes

Wow! Talk about small font sizes! :-)

> I'll see if I can add a wider padding, but reducing the font-size would 
> already 'fix' this.

Not if the padding was specified in ex units ;-)

But more seriously: a 5-10% font size reduction would mean a relative
margin widening of around the same percentage. I think 50-100% wider
would be better, but of course youy have to see these things 'in action'.

Mind you, I can live with both the font size and the margins as they are.

> > - But I really don't like the way the ToC adjusts when you use the slider
> > to scroll up and down. Stuff in the ToC rolls up and down, collapses and
> > expands, and all this is animated. That draws your attention constantly to
> > a place where it isn't needed. If there's an option to turn the animation off,
> > I would prefer that. (The fact as such that the ToC follows the scrolling is
> > of course very useful.)
>
> This is actually something that is not part of the standard asciidoc 
> output (see https://asciidoctor.org/docs/user-manual/ for an example 
> with a standard TOC). I added it because the TOC becomes a bit too big 
> in something like the language reference, and in the mono-html output 
> you will miss the section tocs we had in the old chunked html 
> (especially in chapters like "Built-in functions and Variables").
>
> This is a trade-off between showing everything (or at least: 3 levels 
> deep in the current config), and being able to quickly navigate to a 
> specific chapter without having to scroll a lot in the TOC itself. I 
> think the annoying effect you notice is more pronounced by quickly 
> scrolling through it, than when you're actually reading a document or 
> consulting it as a reference.

True. If you're just reading it's much less irritating.

> I can't tweak much about this, except showing the three levels of the 
> TOC all the time. That kind of defeats the purpose why I added this in 
> the first place. And maybe I can tweak something about the animation of 
> the transition, but the current 300ms 'ease-in-out' animation applied 
> for expanding and collapsing is less fidgety than no delay to me, and 
> increasing the delay a lot further makes it seem sluggish, but will 
> reduce the jitter while scrolling very fast.

I realize now that what irritates me most is that first something goes down
(as the newly focused section is expanded) and than it goes up again (as
the previously focused section is collapsed). And this also happens if you're
not scrolling, bust just click somewhere in the ToC. I think I'd prefer this
instantaneoulsy.

However, this too is not a big issue. And one we can always explore later.

Cheers,
Paul

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 15:18, Paul Vinkenoog wrote:
> - In tables, sometimes the first column is centered and the second one
> left-justified; sometimes the first is right-justified and the second left-justiified.
> I know this is already the case in the existing LangRef, but I find it absolutely
> horrible, so maybe we should fix this. Same for unnecessary parentheses
> around language elements in tables.
> (OK, I realize this is in the source and not in the rendering, but I'll leave it
> here as a reminder ;-))

Depending on the use case, I'm considering replacing some of the tables 
with description lists, see 
https://asciidoctor.org/docs/user-manual/#description-list for examples.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 18:16, Mark Rotteveel wrote:
> On 10-05-2020 17:23, Dmitry Yemanov wrote:
>> 3) Looking at <link linkend="fblangref25-sidebar01">Switching the 
>> Terminator in <emphasis>isql</emphasis></link> on page 159 inside the 
>> DDL chapter, I see that PDF is rendered with two links "Switching the 
>> Terminator in" and "isql". Looks weird.
> 
> I think this is a limitation or bug of the asciidoc-pdf renderer. I'll 
> report it as a bug.

Reported at https://github.com/asciidoctor/asciidoctor-pdf/issues/1688

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 17:23, Dmitry Yemanov wrote:
> 10.05.2020 14:19, Mark Rotteveel wrote:
> 
>> I have published an PDF and HTML version of the Firebird 2.5 Language 
>> Reference built from asciidoc. I have used some elements of style from 
>> the old documentation, but a lot of it is based on the standard 
>> asciidoc styles.
>>
>> Could you look at the overall style of things to see if there are 
>> things you really don't like.
>>
>> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25.html
> 
> Basically close to excellence, in my opinion ;-) Font size is OK to me, 
> styles are good. Some comments:
> 
> 1) 3.1. Integer Data Types, 3.2. Floating-Point Data Types, 3.3. 
> Fixed-Point Data Types -- why titles use a monospace font? This is OK 
> for "3.2.1. FLOAT", for example, but not for the regular text. "3.1.4. 
> Hexadecimal Format for Integer Numbers" is OK though. I see that this is 
> actually a problem with the source (<database> tag is wrongly used 
> there), but the old rendering seems not paying attention to that.

Yes, the problem is already in the docbook sources, but the old styling 
did not (always) use a monospaced font for database-literals. For 
example for Integer Data Types, the effect is visible on 
https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/html/fblangref25-datatypes.html, 
but not on 
https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/html/fblangref25-datatypes-inttypes.html

I'll fix it after migration (or maybe before migration).

> 2) The code examples inside <blockquote><programlisting> are not only 
> italic but also use a bigger font than inside just <programlisting>. 
> Non-code <blockquote>s are also bigger than the text around them. Should 
> the <blockquote> really change the underlying font size? This doesn't 
> disturb much in HTML, but it's more annoying in PDF. I think a box with 
> yellow background is enough to separate quotes from the other text, 
> bigger font is an overkill here.

I'm going to remove the blockquotes before migration. The way we 
currently use blockquotes is not how they are supposed to be used. As to 
that styling, that is simply the default styling. I haven't touched that 
because - as far as I can tell - we don't have any real use case for 
blockquotes.

> 3) Looking at <link linkend="fblangref25-sidebar01">Switching the 
> Terminator in <emphasis>isql</emphasis></link> on page 159 inside the 
> DDL chapter, I see that PDF is rendered with two links "Switching the 
> Terminator in" and "isql". Looks weird.

I think this is a limitation or bug of the asciidoc-pdf renderer. I'll 
report it as a bug.

> 4) I don't like how titles of <note> / <important> blocks are rendered, 
> they're just italic of the default size. I'd prefer a bigger font (and 
> maybe a different colour) as it was in the old version.

I'll see if I can tweak the title a bit. As to different colour: the pdf 
theming doesn't provide full control (eg specifying a background colour 
is not possible): 
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#keys-admonition

> 5) Table columns need to be properly sized. 50/50 doesn't look good, 
> especially for argument-description type of tables. Right-size alignment 
> in some columns also looks weird.

Yes, the tables need some work.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Dmitry Y. <fir...@ya...>]

10.05.2020 14:19, Mark Rotteveel wrote:

> I have published an PDF and HTML version of the Firebird 2.5 Language 
> Reference built from asciidoc. I have used some elements of style from 
> the old documentation, but a lot of it is based on the standard asciidoc 
> styles.
> 
> Could you look at the overall style of things to see if there are things 
> you really don't like.
> 
> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25.html

Basically close to excellence, in my opinion ;-) Font size is OK to me, 
styles are good. Some comments:

1) 3.1. Integer Data Types, 3.2. Floating-Point Data Types, 3.3. 
Fixed-Point Data Types -- why titles use a monospace font? This is OK 
for "3.2.1. FLOAT", for example, but not for the regular text. "3.1.4. 
Hexadecimal Format for Integer Numbers" is OK though. I see that this is 
actually a problem with the source (<database> tag is wrongly used 
there), but the old rendering seems not paying attention to that.

2) The code examples inside <blockquote><programlisting> are not only 
italic but also use a bigger font than inside just <programlisting>. 
Non-code <blockquote>s are also bigger than the text around them. Should 
the <blockquote> really change the underlying font size? This doesn't 
disturb much in HTML, but it's more annoying in PDF. I think a box with 
yellow background is enough to separate quotes from the other text, 
bigger font is an overkill here.

3) Looking at <link linkend="fblangref25-sidebar01">Switching the 
Terminator in <emphasis>isql</emphasis></link> on page 159 inside the 
DDL chapter, I see that PDF is rendered with two links "Switching the 
Terminator in" and "isql". Looks weird.

4) I don't like how titles of <note> / <important> blocks are rendered, 
they're just italic of the default size. I'd prefer a bigger font (and 
maybe a different colour) as it was in the old version.

5) Table columns need to be properly sized. 50/50 doesn't look good, 
especially for argument-description type of tables. Right-size alignment 
in some columns also looks weird.


Dmitry

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 15:18, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
>> Could you look at the overall style of things to see if there are things
>> you really don't like.
> 
>> https://www.lawinegevaar.nl/fbdocs/pdf/en/experiment/fblangref25.pdf
> 
> First reaction to the PDF:
> 
> - Overall, OK!
> 
> - Document title and author listing: really don't like the right-alignment here,
> I'd rather see it left-aligned or centered.

I'll try to tweak that.

> - Navigation pane: only has a depth of 2 (chapter and top-level paragraph).
> This means that lots of 2nd- and 3rd-level paragraphs are now missing from
> the nav pane. It would be very useful having them back.

I have currently built it with the asciidoctor-default of toclevels 2, 
I'll set it to 3.

> - Some of the fonts are not very pleasant to the eye (at least my eye); they
> look horizontally compressed.

I think this is especially the code font, and that is how this font is 
designed. I'll try a few other fonts.

> - Some other fonts are too big (e.g. in Examples sections), but I guess you
> already know that; this is simple a matter of adjustment, nothing complicated.

I'll try to tweak that.

> - In tables, sometimes the first column is centered and the second one
> left-justified; sometimes the first is right-justified and the second left-justiified.
> I know this is already the case in the existing LangRef, but I find it absolutely
> horrible, so maybe we should fix this.

Be aware that some tables are currently a bit mangled (both in spacing, 
and in some cases having wrong number of columns), which might make this 
look worse than normal. I'll see if I can clean it up, but that might be 
better done as a cleanup step after migration.

> Same for unnecessary parentheses
> around language elements in tables.

Do you have a specific example of this last thing, so I know what I 
should look for?

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 14:22, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
> 
>> I have published an PDF and HTML version of the Firebird 2.5 Language
>> Reference built from asciidoc. I have used some elements of style from
>> the old documentation, but a lot of it is based on the standard asciidoc
>> styles.
>>
>> Could you look at the overall style of things to see if there are things
>> you really don't like.
>>
>> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25.html
> 
> First impressions of the HTML (after 1-2 minutes of reading and scrolling):
> 
> - Font size is rather biggish. Maybe 10% smaller or so would be better and
> more in line with the average informative website?

The font size is based on the default font size in your browser 
settings. Would changing that setting be good enough for you?

The problem with tweaking the stylesheet in this respect would be that 
it could render fonts too small for people that do change their font 
settings for good reasons (and might hinder readability on mobile, but 
that is less of a concern).

> - I thought the horizontal margins around the main text were too small, but
> then I noticed that they grow if I widen the window. This is not what one
> expects in HTML, but it works. (However: could a minimum margin be imposed
> that is bigger that the current one?)

This is pretty much standard today, this restricts the reading area to 
about 50-70 characters wide is good for readability.

Eg compare:
https://www.firebirdsql.org/file/documentation/drivers_documentation/java/4.0.x/release_notes.html#general-notes
with
https://www.firebirdsql.org/file/documentation/drivers_documentation/java/2.2.x/release_notes.html#general-notes

I'll see if I can add a wider padding, but reducing the font-size would 
already 'fix' this.

See also 
https://ux.stackexchange.com/questions/3618/ideal-column-width-for-paragraphs-online
https://baymard.com/blog/line-length-readability

> - GREAT to have the ToC alongside!
> 
> - But I really don't like the way the ToC adjusts when you use the slider
> to scroll up and down. Stuff in the ToC rolls up and down, collapses and
> expands, and all this is animated. That draws your attention constantly to
> a place where it isn't needed. If there's an option to turn the animation off,
> I would prefer that. (The fact as such that the ToC follows the scrolling is
> of course very useful.)

This is actually something that is not part of the standard asciidoc 
output (see https://asciidoctor.org/docs/user-manual/ for an example 
with a standard TOC). I added it because the TOC becomes a bit too big 
in something like the language reference, and in the mono-html output 
you will miss the section tocs we had in the old chunked html 
(especially in chapters like "Built-in functions and Variables").

This is a trade-off between showing everything (or at least: 3 levels 
deep in the current config), and being able to quickly navigate to a 
specific chapter without having to scroll a lot in the TOC itself. I 
think the annoying effect you notice is more pronounced by quickly 
scrolling through it, than when you're actually reading a document or 
consulting it as a reference.

I can't tweak much about this, except showing the three levels of the 
TOC all the time. That kind of defeats the purpose why I added this in 
the first place. And maybe I can tweak something about the animation of 
the transition, but the current 300ms 'ease-in-out' animation applied 
for expanding and collapsing is less fidgety than no delay to me, and 
increasing the delay a lot further makes it seem sluggish, but will 
reduce the jitter while scrolling very fast.

> - All in all though, it already looks _much better_ than our current HTML!

Thanks

-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

> Could you look at the overall style of things to see if there are things 
> you really don't like.

> https://www.lawinegevaar.nl/fbdocs/pdf/en/experiment/fblangref25.pdf

First reaction to the PDF:

- Overall, OK!

- Document title and author listing: really don't like the right-alignment here,
I'd rather see it left-aligned or centered.

- Navigation pane: only has a depth of 2 (chapter and top-level paragraph).
This means that lots of 2nd- and 3rd-level paragraphs are now missing from
the nav pane. It would be very useful having them back.

- Some of the fonts are not very pleasant to the eye (at least my eye); they
look horizontally compressed.

- Some other fonts are too big (e.g. in Examples sections), but I guess you
already know that; this is simple a matter of adjustment, nothing complicated.

- In tables, sometimes the first column is centered and the second one
left-justified; sometimes the first is right-justified and the second left-justiified.
I know this is already the case in the existing LangRef, but I find it absolutely
horrible, so maybe we should fix this. Same for unnecessary parentheses
around language elements in tables.
(OK, I realize this is in the source and not in the rendering, but I'll leave it
here as a reminder ;-))

Cheers,
Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

[Mark R. <ma...@la...>]

On 10-05-2020 13:38, Денис Симонов via Firebird-docs wrote:

> Descriptions of parameters, for example, Table 17. CREATE SHADOW 
> Statement Parameters.
> The parameter should not be centered. It looks bad.

In the current documentation it is also centered. The difference is that 
in the new HTML version, the table is now rendered at 100% width, 
instead of minimum necessary, and the columns are the same size instead 
of 1 vs 3.

See 
https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/Firebird_Language_Reference_25EN.pdf
and 
https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/html/fblangref25-ddl-shadow.html

It looks like the conversion tool did something wrong there, the old 
table was defined as

           <colspec colname="colParam" colwidth="*"></colspec>
           <colspec colname="colDes" colwidth="3*"></colspec>

but the tool has made this cols="1,1" instead of "1,3"

Mark
-- 
Mark Rotteveel