Re: Things I Hate (Re: New Website)

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2024-04-17 03:18:00

On Tue, Apr 16, 2024 at 5:54 PM Peter Turcan via Boost <
boost_at_[hidden]> wrote:

> 1. Line length...
> The maximum length in characters should be 50 to 75, with 66 being a
> popular choice.

Do you mean in the markdown? Or in the rendered HTML?

3. The tables are over-designed. The double lines are too busy and pull the
> eye towards the lines and away from the text. I like vertical lines between
> the columns to be a single line and light (very light) to separate the
> contents but not distract the eye.

You're talking about the Quickbook stylesheets. For example this page:

https://www.boost.org/doc/libs/master/libs/url/doc/html/url/ref/boost__urls__params_encoded_view.html

I agree, and Julio has been working on restyling the Antora UI stylesheets
for that. But note that there is no central stylesheet. Quickbook uses one
style, Asciidoc uses another, Antora uses a third, and there are a handful
of other documentation toolchains in use which all have their own styles.

> 4. All code pages should end with a See Also section, so that the
> async_read function can point to the async_write function, and vice versa.
> And to other closely related or alternative functions - async_byte_read if

there is such a thing.
>

Well yes this is always welcomed but it is up to each individual author to
put in this work. There is no way to automate this. The "See Also" you
refer to is typically the result of something manually added to a javadoc
and rendered as part of producing the reference. For example here:

https://www.boost.org/doc/libs/1_85_0/libs/json/doc/html/json/ref/boost__json__parse/overload1.html#json.ref.boost__json__parse.overload1.see_also

This list of symbols comes from the javadoc in the source code:

https://github.com/boostorg/json/blob/9f85ed6d62ff91c6dc4fc30e3a20e9049ec67585/include/boost/json/parse.hpp#L54

Currently Doxygen parses these javadocs to produce the reference. And soon,
Mr. Docs. But other doc toolchains do not do this so it would be up to the
author to write out the See Also section and manually add the links.

> I think if readability is made the focus, a great website will be the
> result.
>

There's no argument here :) The challenge is that there are many
stylesheets, and not enough manpower and creative expertise to work them
down in short order. Also don't forget that we want a dark mode stylesheet,
at least for Antora UI, so that is effectively a brand new sheet (as one
cannot simply "invert the colors").

Thanks