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
