[racket] Best way to propose changes to Scribble CSS files

After spending more time with this, I noticed one issue. Apologies if
someone already pointed this out, but I didn't notice it scanning the
thread again just now.

I like that `@margin-note{}`s are no longer awkward little boxes in
the right margin. It's great that they're now in the main column.

However this means that the placement of the @margin-note in the
Scribble source matters, I think more than before.

There are instances of this sprinkled throughout the docs. For one
stretch of many examples, see "2.2.3 Identifiers" and the several
sections following it:

http://mbutterick.github.io/racket-doc-redo/doc/guide/syntax-overview.html#%28part._.Identifiers%29

There are many occurrences of:

~~~

  Racket’s syntax for identifiers is especially liberal. Excluding the
special characters:

     [Note: Identifiers and Binding (later in this guide) explains
more about identifiers.]

   ( ) [ ] { } " , ' ` ; # | \

~~~

In other words the note interrupts the flow between "let's look at
this:" and "this". This seems weird, to me. Not sure what other people
think.


p.s. In my (small) experience writing Scribble, I was never sure where
to put @margin-note, "semantically". I would sort of wing it, and if
it was generally in the correct neighborhood in the margin, good
enough.

For all I know the doc examples above are placing @margin-note in
exactly the correct, intended place. If so, I'm not sure what to do
about it in terms of the new layout. Anyway I wanted to point this
out.


On Sat, Nov 16, 2013 at 11:31 AM, Matthew Butterick <mb at mbtype.com> wrote:
> It's a reasonable suggestion. I've updated the design so that all the
> internal cross-references share the same color.
>
> http://mbutterick.github.io/racket-doc-redo/doc/
>
>
>
>
> On Nov 15, 2013, at 7:25 AM, Neil Toronto <neil.toronto at gmail.com> wrote:
>
> On 11/13/2013 11:33 PM, David T. Pierson wrote:
>
> On Wed, Nov 13, 2013 at 06:55:10PM -0800, Matthew Butterick wrote:
>
> I've made a number of updates to the Scribble CSS, and posted more sample
> docs, if you care to revisit:
>
> http://mbutterick.github.io/racket-doc-redo/doc/
>
>
> I notice an improvement in the styles used with definitions and most
> content on pages like
>
> http://mbutterick.github.io/racket-doc-redo/doc/reference/pairs.html
>
> But some of the link styles are still too grey/light for me (like the
> link for "Mutable Pairs and Lists" at the top of the above page) and the
> links in the table of contents pages like
>
> http://mbutterick.github.io/racket-doc-redo/doc/guide/index.html
>
> are too light for my eyes.
>
> When I'm reading a web page for information I like the links to stand
> out.  I suppose it helps me scan/navigate more efficiently.  I feel like
> the grey links have the opposite effect.  It is as if they are hidden.
>
>
> There are studies that show hyperlinks may reduce reading comprehension by
> increasing cognitive overhead, and that how much is partly determined by how
> they are presented:
>
> http://en.wikipedia.org/wiki/Reading_comprehension#Reading_comprehension_and_hyperlinks
>
> Overhead also seems depends on the background of the reader. Readers with
> more domain knowledge appear to be less affected by hyperlink presentation.
>
> What Matthew has come up with might be a decent compromise.
>
> Neil ⊥
>
> ____________________
> Racket Users list:
> http://lists.racket-lang.org/users
>
>
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>