Skip to contentSkip to conversation

Add eclipse help generation to build system.

RFC In review [email protected] 2 participants 9 messages Sep 6, 2012

lore
Share & tools
lore
#0 lore raw

cover Add eclipse help generation to build system.

From: Timo Mueller <[email protected]>

Hi,

before my vacation I've submitted a patch to the eclipse-poky project integrating the documentation into the eclipse IDE. To enable the integration into eclipse I've manually generated eclipse help from the documentation using the eclipse stylesheet provided by docbook.

I've added the target 'eclipse' to the documentation's build system to automate the process of eclipse help generation. This can help to facilitate the process of keeping the integrated documentation in sync with the yocto documentation.

In this first RFC I've only integrated the adt-manual as a PoC, because I'm also proposing some changes to the existing html generation. These changes add a separation of the options used for the different output formats. They also help to keep the Makefile clean and concise.

Cheers,
Timo

Timo Mueller (6):
documentation/adt-manual: Moved stylesheet parameters to
customization file
documentation/adt-manual/adt-manual-eclipse-customization.xsl: Added
stylesheet for eclipse help
documentation/Makefile: Added eclipse target for generating eclipse
help
documentation/template/titlepage.templates.xml: Remove title from pdf
template
documentation/adt-manual/adt-manual.xml: Added title to bookinfo documentation/Makefile: Added eclipse target to adt-manual
documentation

 documentation/Makefile                             |   36 ++++++++++++++-----
 .../adt-manual/adt-manual-customization.xsl        |    7 +++-
 .../adt-manual-eclipse-customization.xsl           |   22 ++++++++++++
 documentation/adt-manual/adt-manual.xml            |    5 ++-
 documentation/template/titlepage.templates.xml     |   13 -------
 5 files changed, 57 insertions(+), 26 deletions(-)
 create mode 100644 documentation/adt-manual/adt-manual-eclipse-customization.xsl
Signature · 1 line
1.7.7.6
#1 lore raw

RFC 1/6 documentation/adt-manual: Moved stylesheet parameters to customization file

From: Timo Mueller <[email protected]>

Standard stylesheet parameters were moved to the docbook customization file tying them to the docbook stylesheet used. Removing these parameters simplifies the Makefile.

Furthermore supporting new output formats can now be achieved by creating a new customization file containing its corresponding parameters. Parameters that are used across different stylesheets with different values will then be separated through different customization files.

Global parameters can still be set through the XSLTOPTS variable since this precedes the parameters in the customization file.

---
 documentation/Makefile                             |    7 +------
 .../adt-manual/adt-manual-customization.xsl        |    7 +++++--
 2 files changed, 6 insertions(+), 8 deletions(-)
documentation/Makefile +1 -6
index ee7089a..380193d 100644
@@ -213,12 +213,7 @@ endif
 
 
 ifeq ($(DOC),adt-manual)
-XSLTOPTS = --stringparam html.stylesheet adt-style.css \
-           --stringparam  chapter.autolabel 1 \
-           --stringparam  appendix.autolabel A \
-           --stringparam  section.autolabel 1 \
-           --stringparam  section.label.includes.component.label 1 \
-           --xinclude
+XSLTOPTS = --xinclude
 ALLPREQ = html pdf tarball
 TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
documentation/adt-manual/adt-manual-customization.xsl +5 -2
index 8eb6905..373bdb7 100644
@@ -3,6 +3,9 @@
   
   <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
 
-<!--  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>  -->
-
+  <xsl:param name="html.stylesheet" select="'adt-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
 </xsl:stylesheet>
Signature · 1 line
1.7.7.6
#2 lore raw

RFC 2/6 documentation/adt-manual/adt-manual-eclipse-customization.xsl: Added stylesheet for eclipse help

From: Timo Mueller <[email protected]>

This stylesheet uses the eclipse stylesheets of docbook to create eclipse help from this documentation. In addition to simple html files these stylesheets will also create xml files which are needed to integrate the documentation into eclipse (e.g. toc.xml).

---
 .../adt-manual-eclipse-customization.xsl           |   22 ++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)
 create mode 100644 documentation/adt-manual/adt-manual-eclipse-customization.xsl
documentation/adt-manual/adt-manual-eclipse-customization.xsl new file +22 -0
new file mode 100644
index 0000000..7844738
@@ -0,0 +1,22 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+	xmlns="http://www.w3.org/1999/xhtml"
+	xmlns:fo="http://www.w3.org/1999/XSL/Format"
+	version="1.0">
+
+  <xsl:import
+	  href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="base.dir" select="'html/adt-manual/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
Signature · 1 line
1.7.7.6
#3 lore raw

RFC 3/6 documentation/Makefile: Added eclipse target for generating eclipse help

From: Timo Mueller <[email protected]>

This target will generate eclipse help for the adt-manual using the adt-manual-eclipse-customization.xsl stylesheet.

The output will be generated to a separate directory which can be used for integrating the documentation into eclipse.

---
 documentation/Makefile |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)
documentation/Makefile +20 -0
index 380193d..87e1fde 100644
@@ -284,6 +284,26 @@ else
 endif
 
 
+eclipse: BASE_DIR = html/$(DOC)/
+
+eclipse:
+ifneq ($(DOC),adt-manual)
+	@echo " "
+	@echo "ERROR: You can only create eclipse documentation of the"
+	@echo "       Yocto Project Application Development Toolkit (ADT)"
+	@echo "       User's Guide"
+	@echo " "
+else
+	cd $(DOC); \
+		xsltproc $(XSLTOPTS) \
+				--stringparam base.dir '$(BASE_DIR)' \
+				-o eclipse/$(DOC).html \
+				$(DOC)-eclipse-customization.xsl $(DOC).xml; \
+		mv eclipse/toc.xml eclipse/$(DOC)-toc.xml; \
+		cp -rf $(FIGURES) eclipse/$(BASE_DIR)/$(FIGURES); \
+		cd ..
+endif
+
 tarball: html
 	@echo " "
 	@echo "******** Creating Tarball of document files"
Signature · 1 line
1.7.7.6
#4 lore raw

RFC 4/6 documentation/template/titlepage.templates.xml: Remove title from pdf template

From: Timo Mueller <[email protected]>

The title of a pdf document is part of the image used on the title page. Thus the title defined (e.g. bookinfo.title) in a document should never be used when creating title pages for pdf documents. As other output formats may use the title information to create metadata the title has been removed from the template.

---
 documentation/template/titlepage.templates.xml |   13 -------------
 1 files changed, 0 insertions(+), 13 deletions(-)
documentation/template/titlepage.templates.xml +0 -13
index ff640fa..f53f147 100644
@@ -140,14 +140,6 @@
 
       <mediaobject/>	     
 
-      <title
-	     t:named-template="division.title"
-	     param:node="ancestor-or-self::book[1]"
-	     text-align="center"
-	     font-size="&hsize5;"
-	     space-before="&hsize5space;"
-	     font-weight="bold"
-	     font-family="{$title.fontset}"/>
       <subtitle
 		text-align="center"
 		font-size="&hsize4;"
@@ -163,11 +155,6 @@
     </t:titlepage-content>
 
   <t:titlepage-content t:side="verso">
-      <title
-	     t:named-template="book.verso.title"
-	     font-size="&hsize2;"
-	     font-weight="bold"
-	     font-family="{$title.fontset}"/>
       <corpauthor/>
       <authorgroup t:named-template="verso.authorgroup"/>
       <author/>
Signature · 1 line
1.7.7.6
#5 lore raw

RFC 5/6 documentation/adt-manual/adt-manual.xml: Added title to bookinfo

From: Timo Mueller <[email protected]>

The title of the document used to create metadata for output formats such as eclipse help.

---
 documentation/adt-manual/adt-manual.xml |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)
documentation/adt-manual/adt-manual.xml +4 -1
index e34dc1c..614a38e 100644
@@ -16,7 +16,10 @@
             </imageobject>    
         </mediaobject>
 
-        <title></title>
+        <title>
+            The Yocto Project Application Development Toolkit (ADT)
+            User's Guide.
+        </title>
 
         <authorgroup>
             <author>
Signature · 1 line
1.7.7.6
#6 lore raw

RFC 6/6 documentation/Makefile: Added eclipse target to adt-manual documentation

From: Timo Mueller <[email protected]>

Eclipse help documents are now created when calling the 'make all' target on the adt-manual. Resulting files are archived into the tarball as well. When calling 'make clean' artefacts of the eclipse documentation build are deleted.

---
 documentation/Makefile |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)
documentation/Makefile +5 -4
index 87e1fde..0537c22 100644
@@ -214,9 +214,10 @@ endif
 
 ifeq ($(DOC),adt-manual)
 XSLTOPTS = --xinclude
-ALLPREQ = html pdf tarball
-TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png
-MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
+ALLPREQ = html pdf eclipse tarball
+TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png \
+			eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
 endif
@@ -329,4 +330,4 @@ publish:
 	fi
 
 clean:
-	rm -f $(MANUALS)
+	rm -rf $(MANUALS)
Signature · 1 line
1.7.7.6
#7 lore raw
In reply to [email protected]

Hi Timo,

Thanks for the patches here. I need to be sure that these patches are based on the most recent documentation files found in the yocto-docs/master branch, which is at http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/log/. Can you confirm this for me?

Thanks,
Scott

-----Original Message-----
From: [email protected] [mailto:[email protected]] On Behalf Of [email protected]
Sent: Thursday, September 06, 2012 2:05 AM
To: [email protected]
Cc: Timo Mueller
Subject: [yocto] [RFC 0/6][yocto-docs] Add eclipse help generation to build system.

From: Timo Mueller <[email protected]>

Hi,

before my vacation I've submitted a patch to the eclipse-poky project integrating the documentation into the eclipse IDE. To enable the integration into eclipse I've manually generated eclipse help from the documentation using the eclipse stylesheet provided by docbook.

I've added the target 'eclipse' to the documentation's build system to automate the process of eclipse help generation. This can help to facilitate the process of keeping the integrated documentation in sync with the yocto documentation.

In this first RFC I've only integrated the adt-manual as a PoC, because I'm also proposing some changes to the existing html generation. These changes add a separation of the options used for the different output formats. They also help to keep the Makefile clean and concise.

Cheers,
Timo

Timo Mueller (6):
documentation/adt-manual: Moved stylesheet parameters to
customization file
documentation/adt-manual/adt-manual-eclipse-customization.xsl: Added
stylesheet for eclipse help
documentation/Makefile: Added eclipse target for generating eclipse
help
documentation/template/titlepage.templates.xml: Remove title from pdf
template
documentation/adt-manual/adt-manual.xml: Added title to bookinfo documentation/Makefile: Added eclipse target to adt-manual
documentation

 documentation/Makefile                             |   36 ++++++++++++++-----
 .../adt-manual/adt-manual-customization.xsl        |    7 +++-
 .../adt-manual-eclipse-customization.xsl           |   22 ++++++++++++
 documentation/adt-manual/adt-manual.xml            |    5 ++-
 documentation/template/titlepage.templates.xml     |   13 -------
 5 files changed, 57 insertions(+), 26 deletions(-)
 create mode 100644 documentation/adt-manual/adt-manual-eclipse-customization.xsl
Signature · 6 lines
1.7.7.6

_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto
#8 lore raw

Hi Scott,

Rifenbark, Scott M wrote, On 06.09.2012 16:50:

Quoted 3 lines

Hi Timo,

Thanks for the patches here. I need to be sure that these patches are based on the most recent documentation

files found in the yocto-docs/master branch, which is at http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/log/. Can you confirm this for me?

Yes, I've tested these patches with the yocto-docs/master branch.
(git://git.yoctoproject.org/yocto-docs)

documentation/yocto-project-qs/yocto-project-qs.xml: Added glib-gettextize (CommitID: c46f8e46ad70bf979d2e51e58d461bcd9456b773)

I've just tested with the current commit and the patches also work with Commit f909a7336ae2f95baa751231beeae08081576e1f.

Quoted 47 lines

Thanks,
Scott

-----Original Message-----
From: [email protected] [mailto:[email protected]] On Behalf Of [email protected]
Sent: Thursday, September 06, 2012 2:05 AM
To: [email protected]
Cc: Timo Mueller
Subject: [yocto] [RFC 0/6][yocto-docs] Add eclipse help generation to build system.

From: Timo Mueller <[email protected]>

Hi,

before my vacation I've submitted a patch to the eclipse-poky project integrating the documentation into the eclipse IDE. To enable the integration into eclipse I've manually generated eclipse help from the documentation using the eclipse stylesheet provided by docbook.

I've added the target 'eclipse' to the documentation's build system to automate the process of eclipse help generation. This can help to facilitate the process of keeping the integrated documentation in sync with the yocto documentation.

In this first RFC I've only integrated the adt-manual as a PoC, because I'm also proposing some changes to the existing html generation. These changes add a separation of the options used for the different output formats. They also help to keep the Makefile clean and concise.

Cheers,
Timo

Timo Mueller (6):
documentation/adt-manual: Moved stylesheet parameters to
customization file
documentation/adt-manual/adt-manual-eclipse-customization.xsl: Added
stylesheet for eclipse help
documentation/Makefile: Added eclipse target for generating eclipse
help
documentation/template/titlepage.templates.xml: Remove title from pdf
template
documentation/adt-manual/adt-manual.xml: Added title to bookinfo documentation/Makefile: Added eclipse target to adt-manual
documentation

Quoted 8 lines
  documentation/Makefile                             |   36 ++++++++++++++-----
  .../adt-manual/adt-manual-customization.xsl        |    7 +++-
  .../adt-manual-eclipse-customization.xsl           |   22 ++++++++++++
  documentation/adt-manual/adt-manual.xml            |    5 ++-
  documentation/template/titlepage.templates.xml     |   13 -------
  5 files changed, 57 insertions(+), 26 deletions(-)

create mode 100644 documentation/adt-manual/adt-manual-eclipse-customization.xsl

Best regards,
Timo