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