Are there any plans to fix issues with the new HTML documentation format
in the near future?
I'm looking at the 6.1.1 documentation on `docs.racket-lang.org`. I've
mentioned most of these issues before:
1. The CSS is still using font sizes for body text other than what the
user has set their browser to use as their preferred size for reading
body text. This can make the font size too small for some people.
(It's going out of its way to violate a 20 year-old standard, like it
really hates ADA people and device independence.) For other people, this
can result in less text being shown than people want, with the very
limited screen real estate they have. (Say, when you're trying to keep
one or more editor windows, documentation window, application window in
view on a screen at the same time, but the CSS decides it knows better
than the user and device what body font size to use.)
2. The CSS is still varying the font size dynamically in suboptimal
ways. For example, making the window wider can result in *less* text
being shown, which is a problem for some types of reading we do from
manuals. (Go to a TOC page, drag out the width of the window, and watch
how number of TOC entries visible "throbs" up and down, for no good
reason.) Another problem is the overhead from people having to
constantly adjust to different text sizes. (Go read a page of text in a
larger than normal size, and then go read in normal size, and notice
that the normal text seems small and takes some moments to adjust.
Consider that you might be able to use that compute power and
distraction for better purposes than tolerating ill-behaved CSS.)
3. The CSS is still conflating links for different purposes, such as for
terminology, which used to be distinguished visually. This throws away
important information.
4. By default, when I format the documentation for a package, I'm now
getting absolute URLs to CSS files that are potentially specific to the
Scribble version that generated the HTML. With the previous HTML
format, by default I was getting relative URLs and fewer CSS and JS
files, so I could just copy them to my Web site without modification, as
the Web page for the package they document. (Maybe there are options to
work around the undesirable defaults?)
I'm asking not only because of usability and accessibility, but also
because I need to mess with generated documentation as part of moving to
the new package system. I don't want to spend my limited time kludging
around new infrastructure changes, before I can release more open source
packages/updates, especially if the infrastructure is just going to
change out from under me again.
Neil V.
--
You received this message because you are subscribed to the Google Groups "Racket
Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/racket-dev/552DD0AA.7010400%40neilvandyke.org.
For more options, visit https://groups.google.com/d/optout.
