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