Break up the Language Tour

[MaryaBelanger]

Staged: https://dart-dev--pr4612-language-tour-2-koullabo.web.app/

---

Waiting for #4604 to merge first -- Fixes #4588

---

This PR breaks sections of the language tour into separate pages and lists them directly under "Language" in the side nav, so the features of the Dart language are visible and navigable more easily than the previous single page.

(see #4588 and #4565 for background; see Kotlin and Swift docs for inspiration/direction)

What this PR is:

• Addressing the side nav and new organization. Please comment and review the new layout of the side nav under "Language".

  

• Addressing the grouping of info on the new pages. Please let me know if the new page groupings make sense. They almost entirely follow the structure of original Language Tour -- I didn't write that, I won't be improving that structure in this PR beyond what's necessary.

• Fixing links to the old language tour page.

• Adding manual redirect links to old language tour page

TODO:

In this PR...

• Manually add links to old language tour page, in case external links end up there
  • Link on every section to its new page/location
• Search the entire site source for internal links to /language-tour/#<section> to change to new page/location
• Add ignore thing from language-tour for code excerpts
• Figure out "<< Previous" / "Next >>" buttons for bottom of each page
  • Parkers going to write a script after this lands
• Prevent old /language-tour page from showing up in search results
• Add a little introduction about the language tour to intro page
• Firebase redirects after this PR

---

What this PR is not:

This PR is not...

• Addressing content.
  • Please do not review the contents of any of the new pages, I didn't write it. Open a separate issue for...
    • redundancy
    • sub-optimal information flow within a page (page-to-page is in scope for the PR)
    • inaccurate/outdated content
    • etc.
• Major rewrite.
  • Splitting up or rearranging certain content requires major rewrites or at minimum analysis of the existing content; that will not happen as part of this PR.
  • Referring to the Type System page and all the Null Safety content, which can and should be split up into more granular topic by page, but it's not straight forward (see TODO below)
• Creating a "Getting started" or de facto intro page.
  • Again, I will not be doing any major rewrites in this PR, and consolidating Language samples and Language cheatsheet intro content is a major rewrite.

TODO:

In future PRs...

• Break up the topics on the Type System page to more granular topics:
  • Type inference
  • Type promotion
  • etc.
• Re-work the contents under Null Safety to more granular topics (see this comment) and minimize reference to unsound null safety (see [Sound null safety] Language feature docs #4584 )
  • Introduce "nullable types" page under "Types"
  • Add "null" content to "Variables"
  • Put the rest of the null safety content somewhere else/delete it (migrating, unsound, faq. etc)
  • Break existing content up into these sections:
    • Non-null vs nullable
    • Correctness
    • Flow analysis
    • Working with nullable topes
    • Core library changes
• Consolidate the future/async/await content on the Concurrency page, into the new /language/async page.
  • Info is redundant, Concurrency page should just be about Isolates

[github-actions]

Visit the preview URL for this PR (updated for commit e868b37):

https://dart-dev--pr4612-language-tour-2-97gcxvq9.web.app

_{(expires Fri, 17 Mar 2023 22:40:46 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: d851bc446d3c4d7394c5406c6f07255afc7075f3}

[parlough]

See #4610 (comment) for my thoughts on libraries and visibility:

I think Libraries and visibility needs to remain in the language tour as it is more about the language functionality of libraries which is important to consider when writing any code with Dart. If anything we need to expand on the concept a little and do it much earlier. A lot of code in the tour imports other libraries but we never talk about what it means until way later.

[MaryaBelanger]

@parlough where do you think the library content should go? Does it make sense as an entry under "variables & expressions"? (not knowing where to put it definitely influenced my impulse to move it under libraries 🙃 )

[parlough]

I don't think Variables and expressions is the right place.

@MaryaBelanger Perhaps a first-level doc called Libraries and imports before Classes and objects. I don't believe imports are used much or at all before then.

I say and imports instead of and visibility because (I imagine) that's what most people will have the context to search/look for.

[atsansone]

As discussed, I would move control flow and error handling up, but otherwise LGTM!

GREAT JOB!

[mit-mit]

Looks great overall! A few comments:

1. I think we should move the Keywords page to the end of the Language < submenu, It's mostly a background page, and not something I think we should lead with
2. The Types > Type system page does indeed seem a bit odd in the new structure. Until the re-work PR for that, I think we should either move it up as the first page under Types >, or alternatively make it the last page there.

[mit-mit]

I don't think Variables and expressions is the right place.

@parlough can you elaborate a bit on that? I was actually thinking that might be a good place (I'd just call the page Libraries and make it the last node under Variables and Expressions...

[parlough]

Libraries aren't really about variables or expressions, they are a more high-level concept core to using Dart, nor is import an expression.

Overall, the current Variables and expressions section doesn't make a lot of sense to me. If I'm looking to learn about Libraries, Metadata, or Comments, I would not think to expand Variables and expressions. None of them are (solely) about variables or expressions. Perhaps the problem is in the name of the section rather than the placement of these pages?

[MaryaBelanger]

I took everyone's comments into consideration and came up with the following structure as a compromise for the time being, as I need to merge this so I can start placing new Dart 3 pages in the new structure:

Language

• Introduction
• Syntax basics (I went with this title instead of "Variables and expressions", kind of like this Kotlin section. Probably still not ideal but I think it's vague enough to be a benign place holder)
  • Variables
  • Operators
  • Comments
  • Metadata
  • Libraries & imports ("Libraries & visibility" is back, changed to "imports". Also moved it with the other /language files and updated links across the site)
  • Keywords (Moved "Keywords" to the end of the section)
• Types
  • Built-in types
  • Collection types
  • Typedefs
  • Generics
  • Type system (Moved "Type system" to the end of the section)
• Functions
• Control flow (Moved "Control flow" up)
• Error handling (Moved "Error handling" up)
• Classes & objects
  • Classes
  • Constructors
  • Methods
  • Extend a class
  • Extension methods
  • Enum types
  • Mixins
  • Callable classes
• Concurrency
  • Asynchronous support
  • Isolates
• Null safety (Moved "Null safety" to the end for now)
  • Sound null safety
  • Migrating to null safety
  • Understanding null safety
  • Unsound null safety
  • FAQ

Please open a new issue if anything isn't sitting right. Especially if it's really egregious, I'll try to fix it ASAP. Thanks all!