Unclear docs regarding escaping of Windows paths.

[Jonathan Gibbons]

Thorsten,

I am sorry for the confusion regarding the documentation for argument 
files in the javadoc tool.

 From an implementation point of view, javadoc and javac behave the same 
with regard to argument files. There was no change in behavior between 
JDK 7 and JDK 8. In JDK 9, support for argument files was added to the 
Java launcher [1], and the support for argument files in javadoc and 
javac was upgraded to match that as closely as possible, while retaining 
as much compatibility as possible with any existing argument files. This 
was documented in the JDK 9 Release Notes [2], albeit under a javac 
heading instead of a javadoc heading.

The change that you noted in the URIs is just a side-effect of internal 
changes in the way that the documentation was generated. We removed the 
documentation for the old implementation from 9, and it is a bug that we 
did not get to update it with a reference to the new syntax, as 
described for the Java launcher in [1].

Please also note that the handling of command-line arguments is 
different from the handling of the contents of argument files. In 
general, command-line-arguments are managed by the shell being used to 
issue the command, whether that is bash, ksh, CMD.exe, or a program like 
Ant or Maven, whereas argument-files are handled by code in the 
respective tools (java, javac, javadoc, etc)

-- Jon

[1] 
https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-4856361B-8BFD-4964-AE84-121F5F6CF111

[2]https://www.oracle.com/technetwork/java/javase/9-notes-3745703.html#JDK-8162810

On 12/28/2018 04:48 AM, Thorsten Schöning wrote:
> Hi all,
>
> this question is related to an issue raised for the javadoc plugin of
> Maven[1], which doesn't seem to escape paths forwarded to argument
> files supported by javadoc on Windows. The problem is that the docs
> have changed regarding such details in the last versions of the JDK
> and it's unclear currently how to escape paths properly when and what
> to not escape etc.
>
> The following is for Java 7:
>
>> If a filename contains embedded spaces, put the whole filename in
>> double quotes, and double each backslash ("My Files\Stuff.java").
> https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles
>
> The following from Java 8:
>
>> If a file name contains embedded spaces, then put the whole file
>> name in double quotation marks.
> https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
>
> In docs of Java 11 that part is completely missing, no mention of
> quotes, spaces or backslashes anymore:
>
> https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D
>
> If you have a look at the URIs, in former versions of the JDK they
> were Windows-specific, while the last one is not. So I guess things
> have been refactored and some details of the argument files have been
> simply lost by accident. Or it might be by purpose for some reason.
>
> The interesting thing is that e.g. the following example for parts of
> an argument file are still there:
>
>> -overview \java\jdk9\docs\api\overview-summary.html
> But regarding the docs of Java 7 that example is wrong, because it
> uses single backslashes only and as MJAVADOC-469 proves, those don't
> work properly in paths of argument files.
>
> So, could someone please have a look at the docs and why such
> important details like those for when to escape backslashes have been
> removed? And readd some or some more clarification, at least at the
> level of JDK 7?
>
> Even in JDK 7 there's no definitive answer to the question if
> backslash is a general escape character, only examples of using them
> as such. One is paths under Windows, the other colons in tag names,
> which are not mentioned anymore in JDK 11 as well.
>
> It would be great if this whole thing could be cleared up so that
> people generating the argument files know for sure when to escape
> backslashes and when not.
>
> MJAVADOC-469 proposes a regular expression currently which escapes
> backslashes if not already escaped or being part of a tag name. That
> doesn't handle a mixture of escaped and unescaped backslashes and
> applies the replacement to everything in lack of knowing what a path
> is currently. But it fixes the one problem with unescaped paths and
> shouldn't break too much else in case of wrong escaping. OTOH, it
> might be that all backslashes need to be escaped anyway, one simply
> doesn't know currently.
>
>> (?<!\\)\\(?!\\|:)
>> additionalOption = additionalOption.replaceAll("(?<!\\\\)\\\\(?!\\\\|:)", "\\\\");
> https://issues.apache.org/jira/browse/MJAVADOC-469?focusedCommentId=16729567&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-16729567
>
> Before raising this a s bug somewhere, I was trying to get some more
> insights here, maybe someone already able and willing to clarify the
> docs or able to tell me where to raise a bug etc. I'm feeling a bit
> lost currently.
>
> Thanks!
>
> [1]: https://issues.apache.org/jira/browse/MJAVADOC-469
>
> Mit freundlichen Grüßen,
>
> Thorsten Schöning
>