Language question: with \x defined as , why using command \x is not the same as using

Question

This is intended more as a LaTeX language question than a "how do I accomplish XYZ" question.

In the code below, a usage of VerbatimOut is successful.
Place that usage inside a \newcommand* definition, and using the new command fails.

From the language perspective, why are these not equivalent?
What happens when tokenizing, processing, etc that causes these to have different behaviors?

\documentclass[11pt]{article}
\usepackage{fancyvrb}
\newcommand*{\writeToFile}{
\begin{VerbatimOut}{myFileFromCommand.txt}
fromCommand
\end{VerbatimOut}
\input{myFileFromCommand.txt}
}
\begin{document}
% works
\begin{VerbatimOut}{myFileFromPlain.txt}
fromPlain
\end{VerbatimOut}
\input{myFileFromPlain.txt}
% fails with error "FancyVerb Error: Extraneous input ` fromCommand \end {VerbatimOut} \input{myFileFromCommand.txt} ' between \begin{VerbatimOut}[<key=value>] and line end.
\writeToFile
\end{document}

Note: (likely better on meta discussion, but I don't have enough rep to post there) I've seen that many questions of "why do I get error E when trying to X with code C?" get answered with:

• (A) You can't use C - here's D that works
• (B) Read the TeX book and the documentation for C

Upsides of these answers:

• (A) is great for one-time LaTeX programmers who don't care about learning and just want something that does X
• (B) is great for LaTeX experts who already know how TeX works - they just need to look at C

Downsides of these answers:

• (A) is only useful for people who have the exact same goal X, and usually X is fairly specific
• (B) is daunting for novices who want just enough information to understand the error and search for a solution

Perhaps some kind of debugging mode that shows the operations LaTeX ran (showing before and after expanding each user-defined command, and showing which token is currently being processed) would help, both for individual debugging and posting the "why" something went wrong/right.

Answer 1

It is a general rule that verb-like commands that make catcode changes may not be used in the argument of another command.

To see why you get a runaway argument VerbatimOut changes the interpretation of \ so that it is a normal character and \foo instead of making the single token with name foo it makes 4 character tokens \ f o o

So \end{VerbatimOut} would not be interpreted as \end with argument VerbatimOut in order to stop processing the environment checks for the string and ends the environment by hand.

But your definition is saved with normal catcodes in force

\newcommand*{\writeToFile}{
\begin{VerbatimOut}{myFileFromCommand.txt}
fromCommand
\end{VerbatimOut}
\input{myFileFromCommand.txt}
}

has an \end token a open group { token and character tokens VerbatimOut so the expected verbatim character tokens \end{VerbatimOut} are never found.