documentation/Makefile: Added mega-file, comments, and publish test

Three things done to the Makefile:

1. Added logic so that the user can generate the mega-manual HTML
   document.  It includes processing links using mega-manual.sed

2. Added and updated the comments for 1.3 and inclusive of
   mega-manual generation.

3. Added a test for the existance of HTML file in the publish
   task.  Previously you got some error that was geeky.

(From yocto-docs rev: 99b865ab96b086d818375d1c00f98a3e3a4f4e9f)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 67 insertions, 23 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index 764c52b87c..ee7089aee6 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -1,12 +1,15 @@
 # This is a single Makefile to handle all generated Yocto Project documents.
 # The Makefile needs to live in the documents directory and all figures used
 # in any manuals must be .PNG files and live in the individual book's figures
-# directory.  Note that the figures for the Yocto Project Development Manual
-# differ between the 'master' and 'edison' branches.
+# directory as well as in the figures directory for the mega-manual.  
+# Note that the figures for the Yocto Project Development Manual
+# differ depending on the BRANCH being built.
 #
 # The Makefile has these targets:
 #
 #    pdf:      generates a PDF version of a manual.  Not valid for the Quick Start
+#              or the mega-manual (single, large HTML file comprised of all 
+#              Yocto Project manuals).
 #    html:     generates an HTML version of a manual.
 #    tarball:  creates a tarball for the doc files.
 #    validate: validates 
@@ -14,18 +17,20 @@
 #    clean:    removes files
 #
 # The Makefile generates an HTML and PDF version of every document except the
-# Yocto Project Quick Start.  The Quick Start is in HTML form only.  The variable
-# DOC is used to indicate the folder name for a given manual. The variable
-# VER represents the distro version of the Yocto Release for which the manuals 
-# are being generated.  The variable BRANCH is used to indicate the 'edison'
-# branch and is used only when DOC=dev-manual (making the YP Development
-# Manual).  
+# Yocto Project Quick Start and the single, HTML mega-manual, which is comprised
+# of all the individual Yocto Project manuals.  These two manuals are in HTML 
+# form only.  The variable DOC indicates the folder name for a given manual. The 
+# variable VER represents the distro version of the Yocto Release for which the 
+# manuals are being generated.  The variable BRANCH is used to indicate the 
+# branch (edison or denzil) and is used only when DOC=dev-manual or 
+# DOC=mega-manual.  If you do not specify a BRANCH, the default branch used 
+# will be for the latest Yocto Project release.  
 #
-# To build the HTML and PDF versions of the manual you must invoke the Makefile
-# with the DOC argument.  If you are going to publish the manual then you 
-# you must invoke the Makefile with both the DOC and the VER argument.
-# If you are building the 'edison' version of the YP DEvelopment Manual then
-# you must use the DOC and BRANCH arguments.  
+# To build a manual, you must invoke Makefile with the DOC argument.  If you 
+# are going to publish the manual, then you must invoke Makefile with both the 
+# DOC and the VER argument.  If you are building a particular version of the 
+# Yocto Project Development Manual or you are building any version of the 
+# mega-manual, you must use the DOC and BRANCH arguments.  
 #
 # Examples:
 #
@@ -33,29 +38,35 @@
 #     make DOC=yocto-project-qs
 #     make pdf DOC=poky-ref-manual
 #     make DOC=dev-manual BRANCH=edison
+#     make DOC=mega-manual BRANCH=denzil
 #
 # The first example generates the HTML and PDF versions of the BSP Guide.
 # The second example generates the HTML version only of the Quick Start.  Note that 
 # the Quick Start only has an HTML version available.  The third example generates 
 # both the PDF and HTML versions of the Yocto Project Reference Manual. The 
-# last example generates both the PDF and HTML 'edison' versions of the YP 
-# Development Manual.
+# fourth example generates both the PDF and HTML 'edison' versions of the YP 
+# Development Manual.  The last exmample generates the HTML version of the 
+# mega-manual and uses the 'denzil' branch when choosing figures for the 
+# tarball of figures.
 #
 # Use the publish target to push the generated manuals to the Yocto Project 
 # website.  All files needed for the manual's HTML form are pushed as well as the 
 # PDF version (if applicable).  
 # Examples:
 #
-#    make publish DOC=bsp-guide VER=1.2
-#    make publish DOC=adt-manual VER=1.2
+#    make publish DOC=bsp-guide VER=1.3
+#    make publish DOC=adt-manual VER=1.3
 #    make publish DOC=dev-manual VER=1.1.1 BRANCH=edison
 #    make publish DOC=dev-manual VER=1.2 
+#    make publish DOC=mega-manual VER=1.3 BRANCH=denzil
 #
 # The first example publishes the 1.2 version of both the PDF and HTML versions of 
 # the BSP Guide.  The second example publishes the 1.2 version of both the PDF and 
 # HTML versions of the ADT Manual. The third example publishes the PDF and HTML
-# 'edison' versions of the YP Development Manual.  Finally, the last example publishes
-# the PDF and HTML 'master' versions of the YP Development Manual. 
+# 'edison' versions of the YP Development Manual.  The fourth example publishes
+# the PDF and HTML 'master' versions of the YP Development Manual.  The last
+# example publishes the 1.3 version of the mega-manual (HTML-only) and the 
+# version generated and published is based on the 'denzil' branch.
 #
 
 ifeq ($(DOC),bsp-guide)
@@ -241,12 +252,12 @@ all: $(ALLPREQ)
 pdf:
 ifeq ($(DOC),yocto-project-qs)
         @echo " "
-        @echo "ERROR: You cannot generate a PDF file for the Yocto Project Quick Start"
+        @echo "ERROR: You cannot generate a yocto-project-qs PDF file."
         @echo " "
 
 else ifeq ($(DOC),mega-manual)
         @echo " "
-        @echo "ERROR: You cannot generate a PDF file for the single HTML manual"
+        @echo "ERROR: You cannot generate a mega-manual PDF file."
         @echo " "
 
 else
@@ -255,10 +266,33 @@ else
 endif
     
 html:
+ifeq ($(DOC),mega-manual)
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
+        @echo " "
+        @echo "******** Building "$(DOC)
+        @echo " "
+        cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
+        @echo " "
+        @echo "******** Using mega-manual.sed to process external links"
+        @echo " "
+        cd $(DOC); sed -f ../tools/mega-manual.sed < mega-manual.html > mega-output.html; cd ..
+        @echo " "
+        @echo "******** Cleaning up transient file mega-output.html"
+        @echo " "
+        cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd ..
+else
 #       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
+        @echo " "
+        @echo "******** Building "$(DOC)
+        @echo " "
         cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
+endif
+
 
 tarball: html
+        @echo " "
+        @echo "******** Creating Tarball of document files"
+        @echo " "
         cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd ..
 
 validate:
@@ -266,8 +300,18 @@ validate:
 
 
 publish:
-        scp -r $(MANUALS) $(STYLESHEET) www.yoctoproject.org:/srv/www/www.yoctoproject.org-docs/$(VER)/$(DOC)
-        cd $(DOC); scp -r $(FIGURES) www.yoctoproject.org:/srv/www/www.yoctoproject.org-docs/$(VER)/$(DOC)
+        @if test -f $(DOC)/$(DOC).html; \
+          then \
+            echo " "; \
+            echo "******** Publishing "$(DOC)".html"; \
+            echo " "; \
+            scp -r $(MANUALS) $(STYLESHEET) www.yoctoproject.org:/srv/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
+            cd $(DOC); scp -r $(FIGURES) www.yoctoproject.org:/srv/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
+        else \
+          echo " "; \
+          echo $(DOC)".html missing.  Generate the file first then try again."; \
+          echo " "; \
+        fi
 
 clean:
         rm -f $(MANUALS)