Docs: Add info about how to format console output using interpolated strings

[mairaw]

Topic: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/interpolated-strings

One thing I think we should add to the topic (or to a new topic?) is showing how you can format your output using interpolated strings. See this PR (#3210) and comment that prompted me to add this here: dotnet/docs.zh-cn#39 (comment).

[akudhingra]

This seems like a good issue to start contributing.

I believe you are referring to the comment asking what item.Name,-15does. I see that the topic does talk about the structure of an interpolated string being: $"<text> {<interpolated-expression> [,<field-width>] [:<format-string>] } <text> ..." (3rd snippet from the top). This is followed by brief descriptions of field-width and format-string.

What's missing is examples showing their usage. I think adding a couple of example snippets should clarify things. In addition, we could add links pointing to Alignment Component and Format String Component from the Composite Formatting topic which have more details.

Let me know if this sounds okay and I can go ahead and submit a PR.

[BillWagner]

@aakarshit Thanks for volunteering. We'd appreciate the contributions.

I agree that what's missing is examples that show usages of field width and format strings. It would be great to add those.

If you want to really improve the topic, there are a couple other changes we've found that visitors have really appreciated:

• [ ] Putting the snippets in a single downloadable sample project for readers to download and run.
• [ ] Making use of the code-csharp-interactive tag on code samples so they are runnable in the browser.

I've got an open PR on other topic that made similar changes. See #4427 for the changes that would implement those.

If that's more work than you wan to take on, we understand. We'd be happy with whatever size contribution you want to make.

Just tag @mairaw and I when you open PR and we'll take a look. If you want us to look at early drafts, just add '[WIP]' (for Work in Progress) to the title of the PR, and we'll know its not done but that you want us to take a look.

[pkulikov]

Oh! Last week I've thought about and looked on interpolated string coverage in docs as well.
@aakarshit @BillWagner there are examples, maybe not good ones:

• Tutorial
• Quick-start
• Local quick-start

In PR #4491 I've updated the topic in interest with the links to above-mentioned pages. That was a quick fix.

As for a real fix, I thought about suggesting to make "How to: use interpolated strings" page that would cover (and use code samples as @BillWagner suggested):

• basic usage with expressions inside
• special symbols, e.g., comma, colon
• padding and allignment
• formatting
• using culture info, especially invariant culture info with Invariant($"Interpolated string")

After such topic is created, both tutorials and quick-start might be deleted, as code-csharp-interactive is a really good feature: no need to type the whole code, but just modify interesting parameters.

Maybe, that How to can be combined with the main page on interpolated strings. Then, there would be only one source of information on interpolated strings in the documentation, not four scattered as it is now.

[BillWagner]

I'd add one more sample on culture: How to use a specific culture. The scenario is something like "my server is in the US and a visitor from Germany is looking at the numeric data. I want to format numbers like "1.000.000,234" instead of "1,000,000.234".

I have an example from a talk that I will find and add as a comment or gist here.

[pkulikov]

@BillWagner as for an example, the current version, (see point 2) already has it as well; though with currency, but update-able for numeric data. I'd remove reflection on IFormattable and sample is ready.

[pkulikov]

@aakarshit regardless of the above messages, I think merely adding links to pages on formatting and improving existing code samples would be a big improvement of existing content. So, don't hesitate to go ahead with it if you have time. If a bigger clean-up of the topic seems too large or time-consuming, I can do that in the middle of March.

[akudhingra]

@pkulikov @BillWagner, had a very busy week at work. I'd certainly like to do the bigger cleanup. I'll probably have time tomorrow to evaluate how much I can take up.

[akudhingra]

@pkulikov @BillWagner I started working on consolidating all info into one "How To" article as suggested, but can't seem to build a local version correctly. When I serve using docfx on my mac, I don't see a "How To" topic. I see others and on drilling down I could only find media files. I looked through issues and did find a similar issue but didn't have much time to follow it through. Are you familiar with this? All I want to do is to look at the changes I've been making. Is it also possible to test the code-csharp-interactive feature locally? I did see a lot of warnings for this when building.

Anyway, I'm traveling for the next three weeks for work, don't think I'll be able spare any time to work on this. I'll have a whole week free once I'm back. So please take this forward if you or others have the bandwidth, otherwise I'll pick this up once I'm back.

[pkulikov]

@aakarshit that's fine, I'll work on this in March.

As for testing on local machine, I don't use docfx at all as it takes too long to build and final result doesn't look properly. I use Visual Studio Code to edit Markdown files and preview them (.NET docs-specific stuff is not rendered properly, of course, but that's fine). As for the code examples, I've noticed that @BillWagner creates one static method per example. Then, it's fine to run the corresponding console application with the example code locally. Whatever goes to the console output is displayed in the output of the interactive window in the browser.

[pkulikov]

@BillWagner I'll follow the plan discussed earlier in this thread to update the content. Now I would like to agree about changes in doc structure.

I aim to merge these two pages:
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/interpolated-strings
https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/string-interpolation

(By the way, the address of the former page confuses me as it's somehow under /language-reference/keywords.)

I suggest to kill those two pages (with adding redirects) and add instead the how-to page with such a name:
https://docs.microsoft.com/en-us/dotnet/csharp/how-to/format-strings-with-string-interpolation

Then, string interpolation topic would be close to other How-tos on strings. Second, we can use existing project for the code examples.

[BillWagner]

@pkulikov I'd like to take a different direction on your plan:

I aim to merge these two pages:
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/interpolated-strings
https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/string-interpolation

Those should stay separate. Think of the language reference as a complete description of the feature. The tutorial is a guided tour where the emphasis is on understanding the breadth of scenarios for a set of features.

The "How to" section contains short articles to get developers un-stuck. In a sense, they are like tutorials, but should be short, focused and tied to one topic.

To this comment:

(By the way, the address of the former page confuses me as it's somehow under /language-reference/keywords.)

Yes, that's unfortunate. We also have a topic in the special characters section that has some of the information, and it's in a better place. Those should be combined.

I think a good way to go is the following:

• [ ] Add a new "How to: Format console output using string interpolation". This would focus on field widths, numeric formatting and similar to provide visually appealing output in text, including different cultures.
• [ ] The existing tutorial should be updated to include more detail on field width and other formatting, including culture.

• [ ] The existing keyword topic content should be merged into the interpolated strings token page

  How does that sound?

Adding @rpetrusha to review suggested organization.

[pkulikov]

@BillWagner that's true, description of a feature and examples of using a feature should be separate articles. One is more theoretical, while another one provides replies to numerous "how to..." googles.

Description of a feature. I'll merge the keyword topic into the token page. One question though, what link text to use when referencing that token page from other pages to give more details about string interpolation and not about $ character? Would 'String interpolation' be fine (like it's in TOC now)?

Usage of a feature. Existing tutorials are at least of two kinds. The Console Application tutorial has a narrative and covers several features, while Using Attributes tutorial is a collection of "How to" stories around one feature (attributes). I think the tutorial on string interpolation fits the latter scenario. Thus, I'll reorganize it in How to.. sections and add more examples. By the way, as examples are not related I suggest to omit creation of console application and use code-csharp-interactive at the tutorial.

Along with tutorial, there is also a quickstart. Quickstart sounds like a tutorial-light. I don't touch the quickstart now.

@BillWagner above I've explained how I understand two last action points from your list. Is my understanding correct? If yes, I proceed with these two steps first.

A new "How to: Format console output using string interpolation" page confuses me as I'm afraid it would be just a subset of the tutorial. My confusion might evaporate after I finish with tutorial. Then the purpose and content of a new page will become more clear to me. That's why I prefer to address that page last or even in another PR.

Does that sound like a plan?

[BillWagner]

@pkulikov That's perfect. Yes, "string interpolation" is the right link text.

The "tutorial" "how to" and "quick start" are fuzzy distinctions. I think of them like this:
Quick Start is for a beginner audience. It's all 100 level content.
How To is very focused. If you're stuck and want an answer to one thing, you want to land at a "how to" article.
Tutorials are longer and more focused on learning how features fit together in a (probably small) real-world program.

[pkulikov]

@mairaw @BillWagner do you think this issue can be closed as an updated tutorial answers common How to... questions?

[BillWagner]

Fixed in #5200