On Tue, Apr 16, 2024 at 5:54 PM Peter Turcan via Boost < boost@lists.boost.org> 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_... 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__jso... This list of symbols comes from the javadoc in the source code: https://github.com/boostorg/json/blob/9f85ed6d62ff91c6dc4fc30e3a20e9049ec675... 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