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