Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Scaladoc Tool
    • Labels:
    • Environment:

      scaladoc formatting readability font default

      Description

      === problem ===
      ScalaDoc currently specifies "Arial".

      === analysis ===
      Arial is not really engineered for technical documentation.
      Additionally, not everyone has it.
      To summarize, this is not good.

      === enhancement recommendation ===
      After testing I came to the conclusion that something along the lines of "Ubuntu", "Droid Sans", "Trebuchet MS", "Lucida Grande", "Lucida Sans", "DejaVu Sans Condensed", sans-serif; would enable good quality font use on major platforms (Ubuntu/Linux/Android/Apple/Windows).

      Ubuntu: Best differentiation between l/1/I and O/0 etc. Standard on Ubuntu, popular on Linux.

      Droid Sans: Stable properties with wide range of supported glyphs. Standard on Android, popular on Linux.

      Trebuchet MS: Stable font available on all Windows platforms, popular on Linux (with MS core fonts).

      Lucida Grande: Available on all Apple machines.

      Lucida Sans: Available on Windows, shipped with Sun Java.

      DejaVu Sans Condensed: Available on Linux. Wide range of supported glyphs.

      The chosen fonts have all the same glyph height and shouldn't cause any major differences (except the occasional different linebreak in texts).

      The monospace font should be left undefined as currently.

        Activity

        Show
        Simon Ochsenreither added a comment - https://github.com/scala/scala/pull/29
        Hide
        Heather Miller added a comment -

        During the Scaladoc redesign, I made a design decision to go with Arial- which I still stand by for aesthetic reasons.
        Actually, a lot of technical documentation lives in Arial.

        In case a user doesn't have Arial installed, the font-family ordering "Arial, sans-serif;" ensures that the sans-serif browser/system default sans-serif font is used in Arial's place (after checking for Arial)- so in the case of a user running Ubuntu, that might be the Ubuntu font.

        That browser/system default sans-serif font is also user-configurable. If unhappy with that font, a user can decide to change it.

        Finally, high-traffic, professional websites like cnn.com and heise.de use Arial and have as alternatives Helvetica and "sans-serif". Having more than one or two alternative fonts is generally not necessary.

        (On an aside: the github pull request revealed that "sans-serif;" was missing in index.css, so that has been adjusted accordingly.)

        Show
        Heather Miller added a comment - During the Scaladoc redesign, I made a design decision to go with Arial- which I still stand by for aesthetic reasons. Actually, a lot of technical documentation lives in Arial. In case a user doesn't have Arial installed, the font-family ordering "Arial, sans-serif;" ensures that the sans-serif browser/system default sans-serif font is used in Arial's place (after checking for Arial)- so in the case of a user running Ubuntu, that might be the Ubuntu font. That browser/system default sans-serif font is also user-configurable. If unhappy with that font, a user can decide to change it. Finally, high-traffic, professional websites like cnn.com and heise.de use Arial and have as alternatives Helvetica and "sans-serif". Having more than one or two alternative fonts is generally not necessary. (On an aside: the github pull request revealed that "sans-serif;" was missing in index.css, so that has been adjusted accordingly.)
        Hide
        Commit Message Bot added a comment -

        (heathermiller in r25434) Minor changes to the Scaladoc stylesheets, as suggested by Simon Ochsenreither. Closes SI-4499. No review.

        Show
        Commit Message Bot added a comment - (heathermiller in r25434 ) Minor changes to the Scaladoc stylesheets, as suggested by Simon Ochsenreither. Closes SI-4499 . No review.

          People

          • Assignee:
            Unassigned
            Reporter:
            Simon Ochsenreither
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development