Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use box drawing art for illustrating an example for ArrayView::split_at #565

Merged
merged 4 commits into from
Sep 3, 2019

Conversation

bluss
Copy link
Member

@bluss bluss commented Dec 1, 2018

This is a proof of concept.

Temporarily hosting the docs on github pages see the ArrayView::split_at example there.

Box drawings are relatively easy to produce, easy to distribute and
maintain in all places rustdoc renders, readable in plain text and
when rendered, and they have a consistent style.

The biggest positive is that it enables us to produce many
illustrations.

They have the drawback that they restrict us to mostly 2-D (but that makes
for easier to understand illustrations anyway), and it doesn't look very
impressive.

@bluss
Copy link
Member Author

bluss commented Dec 1, 2018

High priority items we can illustrate:

@jturner314 What do you think? Too ugly and unprofessional or pragmatic? Using boxes is not exactly flexible, can't color anything, but the boxes by themselves look surprisingly sharp.

@jturner314
Copy link
Member

Text has a lot of practical advantages – easy to edit, doesn't require any special software to edit, works nicely with version control, integrates well into existing docs, and makes it easy to maintain a consistent style. The best alternative would be SVG (which can be edited with Inkscape and included directly as an image), but then the images would be in separate files from the docs, hosting them would be more difficult, they wouldn't be as easy to edit/diff, and keeping the style consistent would be more difficult. Plain text doesn't look as nice as SVG images and is somewhat limiting, but IMO the practical advantages outweigh the disadvantages.

By the way, I do have a few minor suggestions about the sample drawing:

  1. I'd put the indices of the vertical axis closer to the matrix to make it easier to see that they match up to the edges between boxes (see below).

  2. I'd suggest making the elements include their indices to more easily see how they correspond to the indices on the edges:

    ///          ──▶ Axis(1)
    ///         ┌─────┬─────┬─────┬─────┐ 0
    ///       │ │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │
    ///       ▼ ├─────┼─────┼─────┼─────┤ 1
    ///  Axis(0)│ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
    ///         ├─────┼─────┼─────┼─────┤ 2
    ///         │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │
    ///         └─────┴─────┴─────┴─────┘ 3 ↑
    ///         0     1     2     3     4 ← possible split_at indices.
    

    or

    ///          ──▷ Axis(1)
    ///         ┌────┬────┬────┬────┐ 0
    ///       │ │ 00 │ 01 │ 02 │ 03 │
    ///       ▽ ├────┼────┼────┼────┤ 1
    ///  Axis(0)│ 10 │ 11 │ 12 │ 13 │
    ///         ├────┼────┼────┼────┤ 2
    ///         │ 20 │ 21 │ 22 │ 23 │
    ///         └────┴────┴────┴────┘ 3 ↑
    ///         0    1    2    3    4 ← possible split_at indices.
    
  3. I'd suggest making the horizontal axis arrow longer to be more similar to the vertical axis arrow (see above).

  4. I'd consider replacing the v and > with triangles, which I think look a little nicer (see above).

@bluss
Copy link
Member Author

bluss commented Aug 24, 2019

Rebased & resolved conflict

bluss and others added 4 commits September 1, 2019 16:21
…plit_at

This is a proof of concept.

Box drawings are relatively easy to produce, easy to distribute and
maintain in all places rustdoc renders, readable in plain text and
when rendered, and they have a consistent style.

The biggest positive is that it enables us to produce many
illustrations.

They have the drawback that they restrict us to mostly 2-D (but that makes
for easier to understand illustrations anyway), and it doesn't look very
impressive.
@bluss bluss force-pushed the box-art-illustrations branch from 054d979 to 2ab3e9e Compare September 1, 2019 14:24
@bluss
Copy link
Member Author

bluss commented Sep 3, 2019

Let's go, one less PR in the queue :)

@bluss bluss merged commit 52bc1f9 into master Sep 3, 2019
@bluss bluss deleted the box-art-illustrations branch September 3, 2019 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants