- document proper handling of .war file in porters handbook

Approved by:	wblock (mentor)
Reviewed by:	bcr, remko (mentors)

en_US.ISO8859-1/books/porters-handbook/book.xml

@@ -7547,6 +7547,33 @@ USE_QT4=	moc_build qmake_build rcc_build uic_build</programlisting>
 	  already installed ones (from
 	  <filename>${JAVAJARDIR}</filename>).</para>
 
+	<para>When porting a &java; application that requires an
+	  application server such as
+	  <package role="port">www/tomcat7</package> to run the
+	  service, it is quite common for a vendor to distribute a
+	  <filename>.war</filename> file.  A <filename>.war</filename>
+	  file is a Web application ARchive and is extracted when called
+	  by the application.  Avoid adding a <filename>.war</filename>
+	  file to the <filename>pkg-plist</filename>.
+	  It is not considered best practice.  An application server
+	  will expand the <filename>war</filename> archive, but not
+	  clean it up properly if the port is removed.  A more
+	  desirable way of working with this file is to extract the
+	  archive, then install the files, and lastly add these files
+	  to <filename>pkg-plist</filename>.</para>
+
+	<programlisting>TOMCATDIR=	${LOCALBASE}/apache-tomcat-7.0
+WEBAPPDIR=	myapplication
+
+post-extract:
+	@${MKDIR} ${WRKDIR}/${PORTDIRNAME}
+	@${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME}
+
+do-install:
+	cd ${WRKDIR} &amp;&amp; \
+	${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME}
+	@cd ${WRKDIR}/${PORTDIRNAME} &amp;&amp; ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting>
+
 	<para>Regardless of the type of your port (library or
 	  application), the additional documentation should be
 	  installed in the