From e19dfd1dd9178794ca6fccacd986a134a1ad0c2b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 22 Aug 2012 17:30:54 -0700 Subject: 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 Signed-off-by: Richard Purdie --- documentation/Makefile | 90 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 67 insertions(+), 23 deletions(-) (limited to 'documentation/Makefile') 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) -- cgit v1.2.3-54-g00ecf