Docs: Inconsistent switch usage for C# compiler options

[BillWagner]

This page and all pages under C# compiler options are inconsistent in how they list compiler options.

The TOC and titles uses the - character. The headers all use '/'

We should pick one to be consistent.

[BillWagner]

My preference is to use '-' throughout the docs to avoid confusion with a path separator. The index pages should mention that both are supported.

Respond 👍 to agree, 👎 if you'd prefer '/'

[mairaw]

Not only headers but the syntax block also shows /. So we should be consistent everywhere!

[fearthecowboy]

The dash is best!

[borland]

👍 for dash

[Jazzynupe]

Not to mention in PowerShell we primarily use "-" for parameters. So I say dash for the win.

[amir-khatibzadeh]

👍 dash baby

[phillipsj]

:+1:

[mairaw]

Thanks for the feedback everyone. So far dash seems to be the overwhelming preference.

@fearthecowboy you get my vote for best comment! 😄

We have some other priorities we have to tackle first. So if anyone wants to jump in to change from / to -, please let us know!

[jonstodle]

For across platform future across platform solution is needed. Dash all the way

[CodeCharm]

Dash. Even the box says to use it everywhere.

[IainWardle]

:+1:

[niranjankala]

👍 dash

[ryantrem]

👍

[sputier]

@mairaw Hm... Changing the switch everywhere may also include the VB compiler. For instance, this page is related to both compilers : changing the switch here may lead to changing it everywhere.
As the initial scope of this issue is the C# compiler, I'm not really sure of the way to handle it. Are VBists OK with the use of - ?

[eduard-malakhov]

@mairaw this page still has one usage of "/" in "To change the location of the .pdb file, see /pdb (C# Compiler Options)." Should I change it too as part of this issue?

[sputier]

@eduard-malakhov Of course, feel free to fix any switch I may have forgotten ! :-) Are you working on "everything" ? If you only plan to fix this, do you want me to include it in the next PR ?

[eduard-malakhov]

@sputier I've fixed every place I could find C# compiler options. Please see PR #4165

[eduard-malakhov]

I've also noticed that f1_keywords metadata (or whatever it is properly called) on these options pages (example here) often specifies the switch with a slash, not a hyphen while helpviewer_keywords usually use both. Is that correct?

[BillWagner]

tagging @mairaw on the above comment. What should we do for the F1 metadata on compiler command options?

[mairaw]

@KathleenDollard do you think we should also switch the VB compiler options to use - instead of /? I agree with you @sputier that in some cases is trickier since it's used for both. I'd vote for consistency and have dashes everywhere, @BillWagner what do you think?

For the F1 question, I've noticed that @sputier added them where they were missing unless I missed something. Those entries are used for the index of offline books so it's fine to leave both options. But if the dash is missing from a page, we should add.

[eduard-malakhov]

@mairaw just to make sure we're on the same page, do you mean that we need to update these pages so that this

f1_keywords: 
  - "/addmodule"
helpviewer_keywords: 
  - "/addmodule compiler option [C#]"
  - "-addmodule compiler option [C#]"
  - "addmodule compiler option [C#]"

becomes this

f1_keywords: 
  - "/addmodule"
  - "-addmodule"
helpviewer_keywords: 
  - "/addmodule compiler option [C#]"
  - "-addmodule compiler option [C#]"
  - "addmodule compiler option [C#]"

?

Do we need to add an option without prefix (- "addmodule") as well like we have it in helpviewer_keywords?

[KathleenDollard]

I'm interested in other people's thoughts, but I did not know VB supported - in compiler options. A quick search didn't find anywhere that used them. Is there somewhere we think VB is inconsistent with itself in the use of / over -?

I would not want to make a change, unless it is to fix an inconsistency, or if there is something I'm unaware of that makes - better than /

[CodeCharm]

I just did a quick check (not an exhaustive one).

vbc.exe -version

Produces exactly the same output as

vbc.exe /version

... even though the built-in help only uses slashes for documentation.

Based on that, I expect that the VB compiler will handle - just fine, and the index page can make it clear that either - or / is supported.

[sputier]

@eduard-malakhov Nice to have some help to handle this issue ! Thanks for the proof-read & fixes !

@mairaw @eduard-malakhov Yeah, I had seen the f1_keywords, but since helpviewer_keywords already used / and -, I thought it wasn't necesary to change it.

@KathleenDollard I already read a bit of the VB docs, and it seems only / is used. And I also think changes are not necesary for the VB docs, or maybe just add 1 line somewhere (compiler-options/index.md ?) to introduce the use of -.

So... I think common pages (like https://docs.microsoft.com/dotnet/framework/app-domains/how-to-build-a-multifile-assembly) could keep the / syntax, as C# guys should already know they can use / or -.

[sputier]

@CodeCharm I also tried some compiler options (-out, -doc, -target, and a few others), and vbc handled it without any problem.

[CodeCharm]

Thanks, @sputier

I can't think of a good reason to use / for VB and - for C#. They should both (all) use -.

[BillWagner]

Let me make a couple clarifying comments:

Both the VB and C# compilers support '-' and '/' for command options. This issue is not suggesting a feature change to either compiler.

The docs will mention that both switch styles are supported. However, we want to use one syntax consistently to describe the switches in the TOC (table of contents) and the reference.

The question is which syntax we use consistently in docs for compiler switches:

• C# used both / and - in different pages and different TOC files.
• A quick look indicates that VB consistently uses '/'

We've had pretty consistent feedback that C# docs should prefer '-', based on the cross platform considerations.

I agree with @KathleenDollard that there isn't a good reason to change the VB docs en mass from '/' to '-'.

Is anyone concerned if VB and C# switch docs use a different syntax? '-' for C#, and '/' for VB?

[CodeCharm]

I didn't get that anyone thought it was a suggestion for a feature change... may be that I'm only speaking for myself, though.

Being adept at both C# and VB, I still don't find a reason to support the "different but equal" part especially when it comes to shell-level command switches. This isn't about the language. It's about scripting. Especially if we're looking at non-Windows platforms, and why shouldn't we? (I know, not there yet, but why not be consistent?)

As with C#, the - is friendlier to PowerShell than /. I think that _is_ a good reason for VB docs to use -. There's nothing magical in the VB-language world about compiler-switch syntax.

[mairaw]

We can keep the VB compiler options as / if people prefer that, but we need to make a decision on how we do those on the multi-language topics such as https://docs.microsoft.com/en-us/dotnet/framework/app-domains/how-to-build-a-multifile-assembly.

The instructions are for both languages. So in those cases, what is the preference? To adopt the - or keep the /?

[KathleenDollard]

I hate to look at these one at a time, but I feel that one is easy. There is no VB code in that article, it just says VB can do this too. Thus, changing it to CSC syntax seems appropriate.

I have no problem with this not having VB syntax. Anyone interested in a multiple assembly that writes in VB can easily translate - especially since the - will work in VB.

So, I suggest that we use C# - for csc. If csc and vbc appear on the same page, that might look weird, but let's look at that in context.

[rpetrusha]

Aside from switches for C#, the only other use of switches is for al, which also accepts "-" as well as "/". So all of these can be changed to "-".
I can't think of another topic that combines both C# and VB compiler switches on the command line.

[mairaw]

@KathleenDollard that article does have VB code. You need to switch the language on the left top corner:

[KathleenDollard]

Interesting. You mean if I click on C# on that page, it should offer me VB.

On my machine, in Safari, it does not.

---

From: Maira Wenzel [e-mail]
Sent: Wednesday, January 24, 2018 12:11 PM
To: dotnet/docs
Cc: Kathleen Dollard; Mention
Subject: Re: [dotnet/docs] Inconsistent switch usage for C# compiler options (#4072)

@KathleenDollardhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fkathleendollard&data=02%7C01%7Ckathleen.dollard%40microsoft.com%7C9355bcd411e0493a9cc108d563669b4a%7Cee3303d7fb734b0c8589bcd847f1c277%7C1%7C0%7C636524214700640399&sdata=tof3QWAY6gaSLnOA4NSXSzBRQ7bwf8hQaXhQIlS1jeE%3D&reserved=0 that article does have VB code. You need to switch the language on the left top corner:
[image]https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F12971179%2F35354670-a05098d2-00ff-11e8-90e1-1082839e3d6e.png&data=02%7C01%7Ckathleen.dollard%40microsoft.com%7C9355bcd411e0493a9cc108d563669b4a%7Cee3303d7fb734b0c8589bcd847f1c277%7C1%7C0%7C636524214700640399&sdata=4ygbZ9f55i7Yd1%2Bn8ryBuHKCUwOJeY%2FaK0caTtAyoWo%3D&reserved=0

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdotnet%2Fdocs%2Fissues%2F4072%23issuecomment-360258448&data=02%7C01%7Ckathleen.dollard%40microsoft.com%7C9355bcd411e0493a9cc108d563669b4a%7Cee3303d7fb734b0c8589bcd847f1c277%7C1%7C0%7C636524214700640399&sdata=%2BAnGyg%2BPz1o4lp2wqGOqWZ5IgeC7xZPRldhsFSZzk8s%3D&reserved=0, or mute the threadhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAFktXqDguacNi6UVnJGrD5963SJ-tiVZks5tN45bgaJpZM4RWgmo&data=02%7C01%7Ckathleen.dollard%40microsoft.com%7C9355bcd411e0493a9cc108d563669b4a%7Cee3303d7fb734b0c8589bcd847f1c277%7C1%7C0%7C636524214700640399&sdata=%2B6%2BbPTDJMxoSChRZryxOf7xBn5C7n%2Fvv8Fz5NwOkUOo%3D&reserved=0.

[mairaw]

Discussed this with @KathleenDollard today, so here's the plan:

• For multi-language topics, let's use dash
• We should add a note to Visual Basic Command-Line Compiler to call out that the option is available in two forms similar to the C# version (PR #4449)
• We opened a separate issue (#4450) to discuss with the VB community what is their preference for the compiler options

[mairaw]

I think this one can be closed, right @BillWagner?

[BillWagner]

Yes, closing now.