I like Rik's proposal in comment #24. I pushed a change to the stable branch that will hopefully avoid that the formatting of the docstring in the terminal causes confusion:
https://hg.savannah.gnu.org/hgweb/octave/rev/4d74446020ad

Marking as ready for test.

I think we are using Texinfo tags appropriately.  For reference,

@code : for code (mono-spaced font).  In Info format the block is enclosed in single quotes.
@command : for UNIX commands, such as @command{ls}
@env  : for environment variables, such as @env{HOME}
@file : file names, such as @file{~/.hgrc}
@kbd  : keyboard input typed by user
@key  : a key, such as @key{RET} for Return
@option : for options, such as @option{-l}
@samp : catch-all for any text that should be set off from the surrounding documentation, but is not one of the categories above.  The text will be enclosed by single quotes in Info format.

The @qcode macro is one I designed because the single quotes around a piece of text that is already quoted look horrible in Info format.

@code{"Text"} -> '"Text"' in Info
@qcode{"Text"} -> "Text" in Info

I also created the @tcode macro for code that ends with a transpose operator (').

@code{y = x'} -> 'y = x''  in Info
@tcode{y = x'} -> y = x'   in Info

Perhaps we shouldn't bother to document "short e" form and just document "shorte".  Both will be accepted by the format command, but the second form doesn't have documentation problems.

I understand that the quoting caused confusion, but I think this is really a problem due to a mixture of bad Texinfo markup in the source file.  In the docstring for the format command in pr-output.cc, we have four tables.  Three use "@table @code" like this:

@table @code
@item short
...
@item long
...
@item  short e
@itemx long e
...
@end table

which results in the items being typeset in typewriter font in PDF and similar output formats and surrounding in single quote characters in the Info and the output displayed by the command-line help function.

The other table uses "@table @asis" with the @item entries sometimes tagged with @qcode{}, like this:

@table @asis
@item  @qcode{"+"}
@itemx @qcode{"+"} @qcode{"@var{chars}"}
@itemx @code{plus}
@itemx @code{plus @var{chars}}
...
@item bank
...
@item native-hex
...
@end table
+verbatim+

To further confuse things, we also have

+verbatim+
@item  short eng
@itemx long eng
Identical to @samp{short e} or @samp{long e} but displays the value using an
engineering format, where the exponent is divisible by 3.  For example, with
the @samp{short eng} format, @code{10 * pi} is displayed as @code{31.416e+00}.

By using @samp, you get a typewriter font surrounded by quotation marks in typeset output and text enclosed in single quote characters in ASCII output.  The use of @samp might just be wrong.  I don't remember the guidelines about what tags to use for what purpose.

Part of the problem is that in the Info format and what is displayed by the help function the convention is to use single quotes to display @code elements because simple ASCII output doesn't have a typewriter font.

I'm not sure what is best.  Maybe the guidelines for Texinfo formatting are not being followed correctly or they are just outdated.  The quotes in simple ASCII output were probably fine in 1990 but easily misinterpreted today.  Maybe we should try to improve the help function so that it displays nicely typeset output when possible?  That might avoid confusion in about 99% of all use cases in these modern times.

Thanky Nicholas, your Comment #17 correctly states the original cause of my confusion. The arguments are quoted including the space wherever mentioned in running text. If found this really misleading and it would be easy to repair.

I don't have access to Octave currently. Did you try the command syntax form `format "short e"`? Does that work?
If it doesn't, I don't think we should document that spaces in the format arguments are not allowed only in function syntax...

That's what I figured. So, the function doesn't take spaces in its arguments (no matter whether it is called in function or command style - see e.g. `format "short e"`). To avoid possible confusion, get rid of the first part of the proposed documentation change imho.
While the end of the proposed documentation change is technically correct, I don't think this is the correct place to document that. We would need to document that fact for all functions that take multiple string arguments. Instead of repeating the same thing for all of those functions, we should document that in a more central location (if it isn't already).
This leaves us with the fact that it isn't documented that the function also allows contracting the "e" to some options. We should document just that imho.

by my understanding of the code, not so much intentional checking as an artifact of how it processes the inputs.  'format short e' has two separate options, 'short' and 'e', passed to it. if the code sees 'short' it checks to see if the next input is 'e' or another valid option, and if so processes it as 'shorte', etc.  for function input, format('short e') has only one option input, and none match 'short e', but format('shorte') matches, and format('short','e') behaves the same as 'format short e'

apparently a sloppy combination of the preview and back button use has the wrong text in comment #11. patch text in file #53185 is:

When using the functional form of @code{format}, option strings cannot contain
spaces.  Format options with spaces must be specified with spaces removed or
as multiple function inputs, for example, as @code{format("shorte")} or
@code{format("short", "e")}.  Specifying an option with spaces, e.g.,
@code{format("short e")} will produce an error.

I think this is just confusion about command form versus function form and that there is no need to change to try and support

format ('short e')

If someone wants to make a documentation change to clarify this that might be okay.  Otherwise, I would just close this as "Won't Fix" and move on.

is the desired path forward just to document that function form calls must not include spaces, or how hard would it be to replace the tolower step with the c++ equivalet of:

arg = arg(!isspace(tolower(arg)))

correct, matlab errors on format('short e'):

>> format shorte
>> format short e
>> format('short','e')
>> format('short e')
Error using format
Invalid format option short e.

except for the latter, the above all make the same format change to:

a = format

a =

  DisplayFormatOptions with properties:

    NumericFormat: "shortE"
      LineSpacing: "loose"

so, all their documentation list as single words, but they accept two-word format states except for the function call.

All of Octave's documentation list the format states as two words. There is no mention of a 'shorte' option, just 'short e'.  Since Short and E are separate format specifiers, this does make some sense, and needing to send them to the function form as two separate strings makes sense in that context. 

Maybe then this is primarily a documentation problem.

renamed reprot to, i believe, better capture the state of the bug.

>> format short e
>> format shorte
>> format ('shorte')
>> format ('short e')
error: format: unrecognized format state 'short e'

It was maybe my mistake to use quotes on the command line.
The following is not accepted:

>> format "short e"
error: format: unrecognized format state 'short e'

while these two command forms are accepted:

>> format short e
>> format "shorte"

But even when you use the function form

>> format("shorte")
>> format("short e")
error: format: unrecognized format state 'short e'

only the first version is accepted.

I have to admit that I am a bit puzzled by these results... Maybe it is more than a documentation bug?

The names of the numeric formats than can be specified as argument to the "format" command seem to be misspelled on the doc page.

The documentation lists the following format names:

• "short e"
• "short eng"
• "long e"
• "long eng"
• "short g"
• "long g"

I cannot exclude that the implementation of "format" is wrong. At least it is accepting the following formats in the current version 7.1.0

• "shorte"
• "shorteng"
• "longe"
• "longeng"
• "shortg"
• "longg"