Unclear docs regarding escaping of Windows paths.

[Thorsten Schöning]

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

-- 
Thorsten Schöning       E-Mail: Thorsten.Schoening at AM-SoFT.de
AM-SoFT IT-Systeme      http://www.AM-SoFT.de/

Telefon...........05151-  9468- 55
Fax...............05151-  9468- 88
Mobil..............0178-8 9468- 04

AM-SoFT GmbH IT-Systeme, Brandenburger Str. 7c, 31789 Hameln
AG Hannover HRB 207 694 - Geschäftsführer: Andreas Muchow