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