Minimum requirements for changing log4j.properties -> log4j2.properties

All,

I'm investigating the minimum effort I need to migrate a web application 
from log4j 1.x to 2.x and (as you can see from other posts), I'm running 
across a few snags. I'm 100% able to get it to work, but I want to 
understand why I haven't been able to get it to work more easily.

Coming from log4j 1.x, it's very easy to miss the *vitally important* 
change to configuration file names that requires the number 2 to appear 
in there. "properties"-based configuration is still supported, but the 
filename needs to be log4j2.properties instead of log4j.properties. (I 
see that a system property is available to configure log4j to look for 
the old filenames, but system properties aren't a good option in a web 
application environment.) I just wanted to say that the documentation 
could maybe make this more clear under the "Configuring Log4j 2" section 
of the migration guide.

I did the simplest thing I could possibly think of and just 
copied/re-named my existing properties file. No errors, but not expected 
behavior: my expected log file was not created, and nothing was logged 
to the disk. Enabling log4j debugging shows my file being read and 
processed, but no appenders or loggers are dumped into the debug log, as 
they are when I use a comparable XML-based configuration file.

Note that I changed nothing about my log4j.properties file other than 
renaming it, so all the class names for the appenders (e.g. console, 
file) and the pattern layout have not changed.

Is there something I am missing in the migration guide that would 
explain why I am not getting anything in my log file? I have a very 
simple configuration, here. I will first post the properties file 
configuration (with a very small change, just the shortened filename):

log4j.rootCategory=INFO,A1

log4j.appender.A1=org.apache.log4j.FileAppender
log4j.appender.A1.file = log4j.log
log4j.appender.A1.encoding=UTF-8
log4j.appender.A1.layout = org.apache.log4j.PatternLayout
log4j.appender.A1.layout.conversionPattern = %d [%t] %-5p %c- %m%n
log4j.appender.A1.append = true

# Turn-up the logging level on our code.
log4j.category.[internal package] = ALL
log4j.category.[another internal package] = ALL
#log4j.category.org.apache=ALL

log4j.logger.org.apache.velocity.generic=ALL

And here is the XML file which should be comparable:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">S
     <Properties>
         <Property name="log-dir" value="[...]" />
     </Properties>
     <Appenders>
         <Console name="Console" target="SYSTEM_OUT">
             <PatternLayout pattern="%d [%t] %-5p %c- %m%n" />
         </Console>
         <File name="File" fileName="${log-dir}/log4j.log" 
immediateFlush="false" append="true">
             <PatternLayout pattern="%d [%t] %-5p %c- %m%n" />
         </File>
     </Appenders>
     <Loggers>
         <Root level="debug">
             <AppenderRef ref="File"/>
         </Root>
         <Logger name="[internal package]" level="all" />
         <Logger name="[another internal package]" level="all" />
         <Logger name="org.apache.velocity.generic" level="all" />
     </Loggers>
</Configuration>

The XML works and the properties do not. Can someone help me understand 
why not?

I don't see any example properties configurations on the log4j 2 web site.

Thanks,
-chris