firebird-docs

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

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

> 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

Both look better now IMO.

> 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.

Agreed.

I'm still having a problem with:

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

It's the NotoSerif font. It's on the narrow side and (in my Adobe Acrobat Reader)
also looks a bit unsharp.

But if I'm the only one complaining about this, let's not waste any more time
and just keep it. (I can always bring it up later if I find a better alternative).

Cheers,
Paul

Re: [Firebird-docs] Example of new documentation

[P-Soft - F. C. <f.c...@p-...>]

very good job

both are readable very easily


Fabio Codebue


P-SOFT di Codebue Fabio

Via Nuova n. 9 - 24060 Tavernola B.sca (BG)

P.I. 03624950162

C.F. CDBFBA72A11C618T

Mobile: +39.348.3515786

Fax: +39.030.5100306

Web: http://www.p-soft.biz <http://www.p-soft.biz/>



pec: amm...@pe...
cod.intermediario SDI: KRRH6B9



------ Messaggio originale ------
Da: "Mark Rotteveel" <ma...@la...>
A: fir...@li...
Inviato: 16/05/2020 14:51:21
Oggetto: Re: [Firebird-docs] Example of new documentation

>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
>
>
>_______________________________________________
>Firebird-docs mailing list
>Fir...@li...
>https://lists.sourceforge.net/lists/listinfo/firebird-docs

Re: [Firebird-docs] Example of new documentation

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

Hi all,

> very good job
>
> both are readable very easily
>
>
> Fabio Codebue

I agree with Pavel and Fabio that the docs look much better now than
they have ever done. For the first time they have a real professional look
- a look that Firebird deserves.

Thanks a lot for that, Mark!

I know from (past) experience how incredibly time-consuming doc writing
and styling are.

Cheers,
Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

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

Hi Mark,

>> 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.

> 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

I like that second one *much* better! Even if you fast-scroll with the slider (which, I admit, is
pretty pointless) it still looks good, with the nav focus just following without any up-and-down
bouncing going on.

My 2 cts.
Paul Vinkenoog

Re: [Firebird-docs] Example of new documentation

[Norman D. <No...@du...>]

Morning All,

Hopefully we are all staying safe.

I'm with Paul, the second version is much better.


Cheers,
Norm.
-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [Firebird-docs] Example of new documentation

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

On 18-05-2020 01:16, Paul Vinkenoog wrote:
> Hi Mark,
> 
>>> 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.
> 
>> 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
> 
> I like that second one *much* better! Even if you fast-scroll with the slider (which, I admit, is
> pretty pointless) it still looks good, with the nav focus just following without any up-and-down
> bouncing going on.

Ok, I'll remove the transition from the CSS.

Mark

-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

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

Hi Mark,

> > - 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

The font size is exactly the same as before (I kept the screen snapshots from last week).
I'm just talking about the main text and the nav pane here, didn't check the others.

Cheers,
Paul

Re: [Firebird-docs] Example of new documentation

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

On 18-05-2020 01:39, Paul Vinkenoog wrote:
> Hi Mark,
> 
>>> - 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
> 
> The font size is exactly the same as before (I kept the screen snapshots from last week).
> I'm just talking about the main text and the nav pane here, didn't check the others.

I didn't change the font size of the navigation pane, but there is a 
difference in the size of the main body text (1em instead of 1.0625em), 
compare with 
https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25-oldsize.html, 
or see this image: 
https://www.dropbox.com/s/3ra80co6ol05e18/compare-sizes.png?dl=0

Be aware, the sources of the 'oldsize' document are not identical to the 
previous one as I had to recreate the asciidoc sources. There are 
rendering differences. For example the introduction of the first section 
still uses a monospace font because I didn't fix that issue, and I have 
removed more blockquotes than in the previous version, because I started 
in the wrong place to fix the cause of a rendering error, and some of 
the other fixes and changes I applied while experimenting are not in 
this version.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] Example of new documentation

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

Mark Rotteveel wrote:

>>> I tweaked the font size a bit:
>>> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25.html
>> 
>> The font size is exactly the same as before (I kept the screen snapshots from last week).
>> I'm just talking about the main text and the nav pane here, didn't check the others.
> 
> I didn't change the font size of the navigation pane, but there is a 
> difference in the size of the main body text (1em instead of 1.0625em), 
> compare with 
> https://www.lawinegevaar.nl/fbdocs/html/en/experiment/fblangref25/fblangref25-oldsize.html, 
> or see this image: 
> https://www.dropbox.com/s/3ra80co6ol05e18/compare-sizes.png?dl=0

OK, I understand now. With such small differences, it depends on screen resolution and
other factors whether the different point sizes translate to different on-screen pixel sizes.
In my case, the letter height remains the same (11 px for caps, 8 for lower size).

However, comparing fblangref25.html to fblangref25-oldsize.html, I do see that the width
of some letters is 1 px less on the newer one, and letter spacing and word spacing are
definitely less. (And the line spacing as well, but only marginally so: 26 px instead of 27.)

On you comparison image, another font is used and I can clearly see the height difference
there.

So let's leave it at that!

Cheers,
Paul Vinkenoog