This page contains my notes about converting TypeScript pages to Dart. You can go about it in two ways:

• Quick and dirty
• The long way

Either way, be sure to check for common differences.

These procedures assume that you already have a Dart version of the sample used by the page you're converting, and that this sample follows our conventions.

For example diffs, see these TOH PRs: #1091, #1071, #1065, #1063

1. Start the server: gulp serve-and-sync-devguide

2. Copy the TypeScript version of the page into the corresponding Dart location. Exception: If this page has hardly any code samples, then it's easier to import the TS page (see The long way).

3. Commit now, with the TS page unchanged . This will make it easier to use GitHub to highlight differences between the TS and Dart versions of the page. (This is optional, but recommended. We'll squish the commits later.)

4. After the intro and before the first heading, remove the link to the running example. Instead, link to the Dart source code.

   OLD:

    The [live example](/resources/live-examples/template-syntax/ts/plnkr.html)
    demonstrates all of the syntax and code snippets described in this chapter.
   

   NEW:

    The complete source code for the example app in this chapter is
    [in GitHub](https://github.com/angular/angular.io/tree/master/public/docs/_examples/template-syntax/dart).
   

5. Modify the Dart version's +make... code to use the Dart copy of the sample.

6. Add asides for "Dart Differences" (diffs from TS/JS). An example:

    .callout.is-helpful
      header Dart difference: Arrays are lists
      :marked
        Arrays in JavaScript correspond to lists in Dart
        (instances of the `List` class).
        This chapter uses _array_ and _list_ interchangeably.
        For more information, see
        [Lists](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#lists)
        in the [Dart language tour](https://www.dartlang.org/docs/dart-up-and-running/ch02.html).
   

7. Look for and fix common differences.

8. Read through the page, and fix anything else you notice. Try not to change the text too much. We can do an edit pass on the TS & Dart pages later.

9. Before submitting a PR run: gulp check-deploy. This will ensure that the official build process has not been broken.

Examples:

• Template Syntax: Dart page source, TypeScript page source
• Dependency Injection: Dart page source, TypeScript page source

Here's the basic process I followed for the Template Syntax and Dependency Injection pages. It's not fun, but it's probably the best way to keep the pages up-to-date. It does, however, run the risk of the pages getting ahead of the samples.

Before I converted either of these pages, I first copy edited the original TypeScript page. After the TypeScript page was in shape, I followed these steps:

1. Start the server: gulp serve-and-sync-devguide
2. Open editors with the file you’re getting text from (let’s call it the source file) and the one you’re putting the text into (the destination file). They should have the same name. For example, if you’re copying ts/latest/guide/template-syntax.jade to dart/latest/guide/template-syntax.jade, then ts/.../template-syntax.jade is the source file and dart/.../template-syntax.jade is the destination file.
3. In the destination file, have the usual include line at the top: include ../../../../_includes/_util-fns
4. In two browser tabs/windows, navigate to the destination file (e.g. http://localhost:3000/docs/dart/latest/guide/template-syntax.html) and the source file (e.g. http://localhost:3000/docs/ts/latest/guide/template-syntax.html).
5. In the source file, below the include but above any content (e.g. after line 2), add a new line with the following code: // #docregion intro
6. Still in the source file, pick a reasonable place to end the intro—probably before the first section heading and definitely before any +make* tags—and add a new line with the following code: // #enddocregion intro

NOTE: If you end the region in the middle of a markdown-formatted chunk of text, add a “:marked” tag to avoid breaking formatting or the whole page: // #enddocregion intro :marked 7. In the destination file, add the following code: +includeShared('{ts}', 'intro') 8. You should see the intro in the destination file, and the source file should look like it did before. (If not, see Tips below.) 1. You should probably open the source file in the browser, too, but that isn’t working for me yet. 9. Once you see the new content in the destination file, continue going back and forth: 2. Mark the docregion in the source file. 3. Include the region in the destination file. 4. Make sure it worked (eyeball the page). 5. Go back to a.

NOTE: See +includeShared, below, for tips on naming regions and deciding where to start and end them.

1. When you encounter +makeExample or +makeTab:
   • End the current region in the source file.
   • Copy the +make* code from the source file to the destination file.
   • Modify the destination file’s +make* code to use your copy of the sample. (You could wait until later to do this all at once.)
   • Begin a new region in the source file.
2. Once you believe you have all the content in the destination file, compare the source and destination pages in the browser, side-by-side. See Checking the results for details.
3. Once you know the content is clean, search the destination page for occurrences of suspect strings, such as TypeScript, JavaScript, truth, falsey, array. Decide whether to:
   • Keep the wording in all files.
   • Change to a different wording in the source file (and thus all files).
   • Change to a different wording in the destination file only.
4. Search the destination file for occurrences of /ts/.
5. Search the destination page for occurrences of BAD or XXX or PENDING.
6. Read the destination page to see whether anything else needs to be changed.
7. Repeat Step 10 as necessary, to make sure you didn’t mess anything up.

At first, I used a ‘s1’, ‘s1-1’ sequence of names, but that wasn’t very informative. I started doing this instead:

include ../../../../_includes/_util-fns

+includeShared('{ts}', <strong>'intro'</strong>)

+includeShared('{ts}', <strong>'html-1'</strong>)
+makeExample('template-syntax/dart/lib/app_component.html',
'my-first-app')(format=".")
+includeShared('{ts}', <strong>'html-2'</strong>)

+includeShared('{ts}', <strong>'interpolation-1'</strong>)
+makeExample('template-syntax/dart/lib/app_component.html',
'first-interpolation')(format=".")
+includeShared('{ts}', <strong>'interpolation-2'</strong>)
+makeExample('template-syntax/dart/lib/app_component.html',
'title+image')(format=".")
+includeShared('{ts}', <strong>'interpolation-3'</strong>)
+makeExample('template-syntax/dart/lib/app_component.html',
'sum-1')(format=".")
+includeShared('{ts}', <strong>'interpolation-4'</strong>)
+makeExample('template-syntax/dart/lib/app_component.html',
'sum-2')(format=".")
+includeShared('{ts}', <strong>'interpolation-5'</strong>)

+includeShared('{ts}', <strong>'template-expressions'</strong>)

+includeShared('{ts}', <strong>'template-statements'</strong>)
…

Where the topmost text is part of an “intro” section, and each ## section has its own prefix. The prefixes are the same as the IDs of the sections. (That was especially easy to get in this case because the page has a TOC.)

When to end/start a new docregion:

• Each ## section
• Each time you have a +make* line. (end the docregion, put an equivalent +make* line in your including file, and then start a new docregion.)

NOTE: It would be nice if you could just use the TS HTML samples and not worry about splitting up the regions. But you can’t, since you have to have each +make* in its own region. There’s no advantage to using the TS HTML sample except MAYBE if the text & code change, to keep them both in sync. (But then, you wouldn’t have tested the code with Dart; better to have the text out of sync than the code untested, I think.)

To publish a hidden version of the page (which I wanted to do because we already had a Dart placeholder for template-syntax), you need to change the +includeShared to specify the location of the source file. So when I named the file template-syntax-NEW.jade, I needed to globally change {ts} to ../../../ts/latest/guide/template-syntax.jade. For example:

+includeShared('../../../ts/latest/guide/template-syntax.jade',
'template-expressions-1')

I made a browser window < ⅓ my screen’s width and created 3 tabs:

• http://localhost:3000/docs/dart/latest/guide/template-syntax.html
• http://localhost:3000/docs/ts/latest/guide/template-syntax.html
• https://angular.io/docs/ts/latest/guide/template-syntax.html

Then I dragged them into their own windows, side-by-side, and started going through them, one windowful at a time, to make sure they differed only in expected ways.

I’m looking at the page shape, not the actual words. This pass is just to make sure nothing was left out or repeated, and that I didn’t mess up the TS version.

NOTE: I might have missed some differences. I used the scrollbar to page, but (at least, with the left nav gone) the search bar obscures the top of the page.

• It’s OK to +includeShared a region that doesn’t exist yet.
  • You might include each second-level heading’s ID, e.g., which lets you eyeball what’s left to do.
  • Or create a bunch of includes for a long section: inputs-outputs-1, inputs-outputs-2, …
• When you know you’ll have to fix something later, you can add a quick note into the destination file, using code like this: .p [PENDING: fix that sample]


• Make sure every region is mentioned in the destination file. Use a comment for the regions you aren’t using.

Must copy tables that contain +make*.

Must copy anything indented that contains +make*. E.g. an .l-sub-section with an indented +makeExample, like under “Declaring input and output properties” (just after inputs-outputs-3).

If you split up a markdown section, make sure the second region has a :marked tag. (:marked doesn’t carry over between regions, so the continued text will be weirdly formatted, at best, if you forget to add :marked.)

If you add text directly to the destination file, you need to add :marked even if the previously included section is markdown.

• Reload.
• Make sure you have an +includeShared that matches the missing doc region’s name!
  • grep docregion <ts-page.jade>
  • grep includeShared <dart-page.jade>
• If you see a problem in the source file, make sure you added :marked after any enddocregion that splits a markdown area.
• Restart gulp serve-and-sync-devguide

If you see a message like Error - unexpected token "pipeless-text", it’s probably due to bad indentation. Perhaps you’re missing :marked at the beginning of a line?

• array (TS) -> list (Dart)
  Array -> List
  • Watch out for "an list"!
• decoration (TS) -> annotation (Dart)
  Just search for "decorat", in case of variants like decorated (-> annotated).
  • Watch out for "a annotation"!
  • Watch out for "property on...decorator", which is more like "argument of...annotation".
  • Watch out for "function" and "call" in reference to an annotation. (TS implements annotations using function calls, not constructor invocations.)
• npm -> pub (usually; e.g., "npm start" -> "pub serve")
• promise -> future
  • Watch for for "callback". In Dart you usually use async-await instead.
• TypeScript/JavaScript -> Dart (usually)
• Many TS/JS functions/methods take an array argument, where Dart instead uses optional parameters.
  Example: @Component()
• Dart style is not to capitalize constant names.
  Example: HEROES -> mockHeroes
• Filenames and directory structure is different. (See Conventions for Dart Samples.)

Note: You can’t just go through .jade files to get "Dart differences". The code diffs matter too.