I was proofreading a README file and noticed inconsistent spelling of a phrase spelled two ways: "command line" and "command-line". I went looking for a conclusive answer and did not find much (see this archived exchange and this Microsoft style guide page). I concluded that it probably doesn't matter and that "command line" seems to be more common, but now I'm curious; has anyone else run into this issue? If you're an industry professional that documents your code, were you ever provided an answer?
Side note: I was debating whether or not to ask this here, as it's certainly more of a code-adjacent question, but considering that if you're writing code, you should be writing documentation as well, I figured it would fit the criteria of "a practical, answerable problem that is unique to software development" stated here. If this is not the case, do let me know-- thanks!
Both "command line" and "command-line" are acceptable and widely used in today's writing. When used as an adjective before a noun, use "command-line" (with a hyphen) in your writing to help prevent confusion. For example, in the sentence "Make sure you entered the correct command-line parameter." the word "command-line" is describing a type of parameter.
When used as a noun, use "command line" (with no hyphen) in your writing. For example, in the sentence "Open the command line." the use of "command line" is used as a noun.
Command line when using it as a noun: "Type yo in the command line."
Command-line when using it as a compound adjective: "The command-line usage of this program..."
Related
The CMake documentation on generator expressions is fairly clear that "A common mistake is to try to split a generator expression across multiple lines with indenting". Here is the example they give:
# WRONG: New lines and spaces all treated as argument separators, so the
# generator expression is split and not recognized correctly.
target_compile_definitions(tgt PRIVATE
$<$<AND:
$<CXX_COMPILER_ID:GNU>,
$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
>:HAVE_5_OR_LATER>
)
My experience is that using multiple lines with indenting works exactly as I'd hope. For example, the following code produces the exact results I would naively expect with the use of whitespace and indentation:
target_compile_options(common_interface INTERFACE
$<$<CXX_COMPILER_ID:MSVC>:
/W4 # Turn on warnings
/WX # Turn warnings into errors
>
$<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:
-Wall # Turn on warnings
-Wextra # Turn on warnings
-Werror # Turn warnings into errors
>
)
As I understand the CMake documentation, each line here would be added as a separate compile option (e.g., $<$<CXX_COMPILER_ID:MSVC>:), but that is clearly not the case since the generated build files show the flags come through correctly.
My questions are:
What am I missing? Is the issue only with certain types of expressions (e.g., logical operators)? Has the behavior changed and the documentation is out of date? or maybe the documentation needs to be enhanced to clarify the restrictions and expected behavior?
Is it safe to continue using whitespace and indentation in some circumstances?
My suspicion is that the resulting true_string (or false_string in $<IF:condition,true_string,false_string>) of a conditional expression may contain whitespace, but the other arguments of an expression cannot be broken.
Tsyvarev's comments to the question are on the money, but I'll give a more formal answer as both one of the CMake maintainers and the author of the generator expression documentation you linked to. The TLDR version is "The docs describe what you can rely on. Don't rely on implementation details that are outside that and which may change.".
The documentation makes clear where you are required to use quoting to ensure robust behavior. Splitting a genex across multiple lines or whitespace has never been officially supported. Sometimes it might appear to work, but that is by coincidence, not by design. Just because you found a case that happens to work in some range of CMake versions, you shouldn't assume that is supported behavior, especially when the documentation now explicitly calls that out as unsupported. There is no promise that such unsupported behavior will continue to work in future releases.
To be absolutely clear, the direct answers to your questions are:
What am I missing? Is the issue only with certain types of expressions (e.g., logical operators)? Has the behavior changed and the documentation is out of date? or maybe the documentation needs to be enhanced to clarify the restrictions and expected behavior?
The documentation is up to date, and I don't know how to make things clearer than what the existing documentation already says. You're asking about things that go directly against that documentation. The aspects you're asking about are not things we intend to document because they are specifically not intended to be supported behavior! Furthermore, CMake's behavior in this area may well have changed over different versions, but it has never been promised to be stable, since it has never been part of CMake's documented API.
Is it safe to continue using whitespace and indentation in some circumstances?
No. The current documentation should make it very clear what's safe and what isn't. If you're asking if something that contradicts that documentation is safe, well, it should hopefully be clear that my answer is still "No". ;)
Footnote
People failing to quote their generator expressions has been one of the most frequently reported problems (or more accurately, the cause of reported problems) in the CMake forums and issue tracker. It kept biting people over and over, to the point where I wrote a Quoting In CMake blog article about quoting in general and I also added the Whitespace And Quoting section to the generator expressions manual in the official CMake docs (that update appeared with CMake 3.24).
I have posted on this before, but couldn't find a simple example. Here's one. I had some code commented out. Part if it was a comment. I used un-comment to turn the code back on for testing. And so this...
'check to see if this is a "simple" struct that has only basic types inside, not additional embedded type 5's
Turned into this...
check to see if this Is a "simple" struct that has only basic types inside, Not additional embedded type 5's
Look at the Is and Not. This isn't happening on all keywords, it appears that it's primarily Linq related terms get re-camel cased - Is, On, Where etc. And that's weird, because I don't have or use Linq in any of my projects.
This is annoying, but what is actually damaging is when this happens inside quotes. Let's say you had something like this...
'this is a "really long comment that I want to split into two lines"
Now I place my cursor in front of, say, "I" and hit return. This produces a second line with a trailing quote. Now every keyword in the entire file from that point on is re-cased, because there's an open quote confusing VS. Now my git diff is basically screwed.
Does anyone have any suggestions on what might be happening and how to turn it off?
The re-casing of keywords is a feature of "Pretty listing (reformatting) of code". This feature was less aggressive in VS versions earlier then VS2015 and did not run un-commenting a line.
To disable it go to:
Tools Menu->Options->Text Editor->Basic-> Advanced-> Editor help section
and uncheck "Pretty listing (reformatting) of code".
In a customer object, we found an SWC statement that our parser chokes on.
IF NOT ( pyparaid IS INITIAL OR dataset_exp IS INITIAL ).
swc_set_element container 'DATASET' dataset_exp+10.
ENDIF.
Although this page seems to imply that they are well known in the ABAP world, I cannot find a page where they are documented officially. (Similar to the ABAP keyword documentation).
Are these macros considered part of the language? In other words, if they are not covered, would you consider a parser incomplete? Please point me to their documentation.
Please try searching for yourself next time. The first hit when googling for "site:help.sap.com swc_set_element" would have lead you straight to the reference.
Yes, a parser that is unable to process macros is incomplete. You have been warned about that half a year ago... :-)
Neither Google nor the User CLI doc seem to be helpful.
I've "kept" some files and want to "unkeep" them.
I can see how to "unpromote" with "revert", but that does not seem to be the right command for just pitching the kept changes. I'm sure it is one of the commands, but the command name choices (like verbing the noun, "defunct") leave me uncertain as to which might be the one I want. So, which command has the option for unkeeping a kept file? (A "see also" reference for the "keep" command would be nice, Micro Focus folks.)
Thanks in advance!
"purge" You'd think it means, "purge" from your work area or something, but it really means "purge the changes". Too hard.
I'm trying to add additional functionality to the already defined method "compile" in smalltalk.
here is the code I wrote:
compile: code notifying: requestor trailer: bytes ifFail: failBlock
self log:(self substring: code delimiter: $?).
super compile: code notifying: requestor trailer: bytes ifFail: failBlock.
as you can see compile has 4 parameters, I only know what to give the first parameter when calling the method compile (which is the code as a string).
whatever functionality I added isn't relevant, I'm not able to run any tests for my method because I dont know what to give the last 3 parameters.
So my question here is how can i call my method with the right set of parameters.
This is where I got stuck while writing a test for it:
co := ContractObject new.
code := 'rate: aRate
"?This is the Compiler Comment. Log me?"
hourlyRate := aRate. '.
co compile: code. "3 parameters missing here"
Since you mentioned this is a homework assignment, I will not deprive you of discovering the joys of a live, dynamic system like Smalltalk ;) The best tutor is your image itself. For many messages (including the one in question), there are helpful examples right under your finger tips that can give you clues about how to send them.
To find these real world examples, you "Browse Senders" of the message in question and see how these clients handle the parameters you're confused about. In Squeak (you didn't say which dialect and Pharo doesn't have that message), I see two senders in particular that show how to handle those parameters.
If you don't know how to "browse senders", there are many great references to teach you. For me, "Pharo By Example" is my go-to reference for basic "how do I" questions like yours (or "Squeak By Example" if you're using Squeak). This "fishing pole", if you will, will provide you with faster answers, and more understanding, then begging for fish on SO ;)
n.b. When asking Smalltalk questions, please tag the dialect (e.g. Pharo, Squeak, Amber) because not all dialects have the same set of messages (e.g. Pharo does not have the message you asked about)