SUSE Manager/Documentation Packaging

From MicroFocusInternationalWiki
Jump to: navigation, search

Packaging SUSE Manager Documentation

The spec file: %build and %install

I do not mention lines that I consider as absolete.

%build

0. For Java programs, increase the stack size. ATM, we set two variables (different values):

  export ADDITIONAL_OPTIONS="-Xss3072K"
  export FOP_STACK="-Xss2048K"

Todo: Check what's actually required.

1. Create an HTML bundle and remember where daps stores it:

  # directory where you will find the HTML bundle:
  package_dir=$(daps -d DC-create-all-adoc package-html-dir-name)
  # create the HTML bundle (we do it this way because pagefiles for
  # the GNOME help system are wanted and --xsltparam="'--stringparam
  # build.for.web=0'" to disable features required for
  # suse.com/documentation only):
  daps -d DC-create-all-adoc package-html --xsltparam="'--stringparam build.for.web=0'" --pagefiles

2. Unpack the created HTML bundle. Later needed for installation:

  tar xvf $package_dir/create-all-adoc_en-html.tar.bz2

3. Save the .page file (in case we want to support the GNOME help system):

  cp $package_dir/*.page %name.page

(Remembering the files of the HTML bundle for the %files sections is probably not needed because we we can add them literaly to these sections.)

4. Create JSP files for SUSE Manager online help

  daps -d DC-susemanager-jsp html --jsp

5. Create the PDFs with the build_pdf function; create a filelist for every PDF subpackage:

  build_pdf () {
    book=$(echo ${1} | tr [:upper:] [:lower:])
    pkg_pdf=$(daps -d DC-${1} package-pdf --formatter=fop --name=$book)
    pdfname=$(find $pkg_pdf -name '*.pdf')
    echo $pdfname > ${book}_en-pdf.filelist
  }
  for b in susemanager-getting-started susemanager-reference \
      susemanager-best-practices susemanager-advanced-topics; do
    build_pdf $b
  done


%install

1. Provide files for the GNOME help system:

 cd %{_builddir}/%{name}-%{version}/create-all
 mkdir -p %{buildroot}%{_defaultdocdir}
 # GNOME help system
 # update the RPM filelist
 cp -a --dereference $(head -n 1 %{name}.filelist) \
   %{buildroot}/%{_defaultdocdir}/%{name}
 gnome_help_dir=%{_datadir}/help/C/gnome-help
 mkdir -p %{buildroot}$gnome_help_dir
 cp %name.page %{buildroot}$gnome_help_dir/%name.page
 {
   echo "%dir $gnome_help_dir"
   echo "$gnome_help_dir/%name.page"
 } > %name.filelist
 # Create the link to make the book visible in yelp; bnc#866668
 pushd %{buildroot}%{_datadir}/help/C
 ln -s ../../doc/manual/%{name} create-all
 popd
 echo "%{_datadir}/help/C/create-all" >> %name.filelist

2. Install JSP files:

 # JSP files
 %define jsp_root /srv/tomcat/webapps/rhn/help
 mkdir -p ${RPM_BUILD_ROOT}%{jsp_root}
 pushd build/susemanager-jsp/jsp/susemanager-jsp
 cp -a * ${RPM_BUILD_ROOT}%{jsp_root}
 # css confuses jsp output; remove it
 rm -f ${RPM_BUILD_ROOT}%{jsp_root}/static/css/susebooks.css
 rm -f ${RPM_BUILD_ROOT}%{jsp_root}/index.jsp
 popd

3. Install PDF files (create a filelist for every PDF subpackage and provide proper jsp index files; this way, we can list them in the Help menu of the Web UI). Create symlinks for the PDF in the Web server directory:

 for f in *-pdf.filelist; do
   # create a directory for the PDF, for example:
   # /usr/share/doc/manual/susemanager-reference_en-pdf
   mkdir %{buildroot}/%{_defaultdocdir}/${f%\.filelist}
   # copy the PDF first to the created directory,
   # it's listed in the first line of the filelist
   cp -a --dereference $(head -n 1 $f) \
     %{buildroot}/%{_defaultdocdir}/${f%\.filelist}
   # remove first line in the filelist and append the location of the
   # end of the filelist
   sed -i 1d $f
   echo "%{_defaultdocdir}/${f%\.filelist}" >> $f
   # for tomcat, create a short directory name, e.g. "reference"
   # first shorten susemanager-reference_en.pdf.filelist to
   # "susemanager-reference"
   bb=${f%_en-pdf\.filelist}
   # then shorten "susemanager-reference" to "reference"
   b=${bb#susemanager-}
   # this is the wanted tomcat directory for "reference"
   sub_dir=${RPM_BUILD_ROOT}/srv/tomcat/webapps/rhn/help/$b
   # here we need the "pdf" subdirectory in the language directory ("en-US")
   subpdf_dir=$sub_dir/en-US/pdf
   mkdir -p $subpdf_dir
   # copy the index file ("susemanager-reference.index.jsp") to the
   # tomcat directory as just "index.jsp"
   cp %{_sourcedir}/$bb.index.jsp $sub_dir/index.jsp
   # create a link from the tomcat pdf directory to actual PDF file
   pushd $subpdf_dir
   pkgpdf_dir=usr/share/doc/manual/${bb}_en-pdf
   mkdir -p ${RPM_BUILD_ROOT}/$pkgpdf_dir
   ln -sf ../../../../../../../../$pkgpdf_dir/${bb}_en.pdf
   popd
   # track the installed directories and files in the filelist of the
   # PDF subpackage
   {
     echo "%dir /srv/tomcat/webapps/rhn/help/$b"
     echo "%dir /srv/tomcat/webapps/rhn/help/$b/en-US"
     echo "/srv/tomcat/webapps/rhn/help/$b/index.jsp"
     echo "/srv/tomcat/webapps/rhn/help/$b/en-US/pdf"
   } >> $f
 done

More detailed background information

Documenting the current way of packaging the product documentation in all the details is questionable because the Documentation Team no longer creates those packages of all the other system or product documentation. Only the SUSE Manager documentation is still packaged.

The documentation packaging system of the past allowed us (me) to submit many books and guides in many languages in many package layouts for many consumers. I accomplished it with a simple template and macro system, control files, and a driver script (bash).


Abbreviated version

My script (with switches) reads the DEF file in the github checkout of the documentation sources and the values of the attributes file in the OBS or IBS package. Such a procedure was needed because SUSE like to rename products, books, and packages; I just had to adjust the values in the DEF file or in the attributes files to meet new requirements.

Then my script builds the .spec file and submits the packaged documentation sources to the BS, etc. pp.

The .spec is rather complex because it does some sanity checks and installs the intra structure for integrating our documenation in desktop help system. In the past, I supported several KDE help systems, the SUSE help system and various incarnations of the GNOME help system. SUSE help system is gone. Integration in the KDE help system is defunct and mostly disabled. Last time I checked, GNOME help was still fine.

I can provide more details if wanted. But I think, we better spend time on simplifying the current way of creating SUSE Manager documentation (the .spec file).


The current .spec file

daps package-src -d DC-foo --def-file DEF-bar creates a tar file of the documentation sources (XML and image files). We use this as the main source file.


I now remove superfluous markers etc. from the spec and instead add background info (comments). In the package source directory doc_pre_checkin.sh and attributes can be deleted. Here is the .spec:

 #
 # spec file for package susemanager-docs_en
 #
 # Copyright (c) 2018 SUSE LINUX GmbH, Nuernberg, Germany.
 #
 # All modifications and additions to the file contributed by third parties
 # remain the property of their copyright owners, unless otherwise agreed
 # upon. The license for this file, and modifications and additions to the
 # file, is the same license as for the pristine package itself (unless the
 # license for the pristine package is not an Open Source License, in which
 # case the license is the MIT License). An "Open Source License" is a
 # license that conforms to the Open Source Definition (Version 1.9)
 # published by the Open Source Initiative.
 
 # Please submit bugfixes or comments via http://bugs.opensuse.org/
 #
 
 
 Name:           susemanager-docs_en
 %define my_lang en
 Version:        3.2
 Release:        0
 Provides:       locale(desktop-data-SLE:en)
 Source:         create-all_en_src_set.tar.bz2
 Source12:       susemanager-getting-started.index.jsp
 Source22:       susemanager-reference.index.jsp
 Source32:       susemanager-best-practices.index.jsp
 Source42:       susemanager-advanced-topics.index.jsp
 BuildRequires:  daps > 1.99999
 BuildRequires:  docbook5-xsl-stylesheets
 BuildRequires:  fdupes
 BuildRequires:  jing
 BuildRequires:  libXmu6
 BuildRequires:  suse-xsl-stylesheets > 1.99999
 BuildRequires:  tomcat
 BuildRequires:  update-desktop-files
 BuildRequires:  xerces-j2
 BuildRequires:  java >= 1.8
 BuildRequires:  java-devel >= 1.8
 Requires:       release-notes-susemanager
 Requires:       dejavu-fonts
 Requires:       google-opensans-fonts
 BuildRoot:      %{_tmppath}/%{name}-%{version}-build
 BuildArch:      noarch
 ExcludeArch:    aarch64
 Summary:        SUSE Manager Documentation (English)
 License:        GFDL-1.2 and CC-BY-SA-3.0
 Group:          Documentation/SUSE
 Url:            http://doc.opensuse.org
 %define _defaultdocdir %{_datadir}/doc/manual
 %define _docdir %{_datadir}/doc/manual
 
 %description
 SUSE Manager Documentation (English).
 
 # Create subpackages for all the PDFs and the JSP bundle
 
 %package -n susemanager-jsp_en
 Summary:        SUSE Manager Online Documentation (English, JSP)
 License:        CC-BY-SA-3.0
 Group:          Documentation/SUSE
 
 %description -n susemanager-jsp_en
 SUSE Manager Online Documentation (English, JSP) for the Web UI.
 
 %package -n susemanager-getting-started_en-pdf
 Summary:        SUSE Manager Getting Started (English, PDF)
 License:        CC-BY-SA-3.0
 Group:          Documentation/SUSE
 
 %description -n susemanager-getting-started_en-pdf
 SUSE Manager Getting Started (English, PDF).
 
 %package -n susemanager-reference_en-pdf
 Summary:        SUSE Manager Reference (English, PDF)
 License:        CC-BY-SA-3.0
 Group:          Documentation/SUSE
 
 %description -n susemanager-reference_en-pdf
 SUSE Manager Reference (English, PDF).
 
 %package -n susemanager-best-practices_en-pdf
 Summary:        SUSE Manager Best Practices (English, PDF)
 License:        CC-BY-SA-3.0
 Group:          Documentation/SUSE
 
 %description -n susemanager-best-practices_en-pdf
 SUSE Manager Best Practices (English, PDF).
 
 %package -n susemanager-advanced-topics_en-pdf
 Summary:        SUSE Manager Advanced Topics (English, PDF)
 License:        CC-BY-SA-3.0
 Group:          Documentation/SUSE
 
 %description -n susemanager-advanced-topics_en-pdf
 SUSE Manager Advanced Topics (English, PDF).
 
 %prep
 %setup -c -q -n %{name}-%{version}/create-all
 %setup -c -q -T -D -n %{name}-%{version}
 find -name '*.png' -o -name '*.svg' | xargs chmod 644 || :
 
 %build
 cd %{_builddir}/%{name}-%{version}/create-all
 # Create a bundle of the HTML output.
 # In the past, only this rather complex command used to work reliably.
 # Also produce .page files for HTML (GNOME help system).
 # Command switches according to bnc#883820
 package_dir=$(daps -d DC-create-all-adoc package-html-dir-name)
 export ADDITIONAL_OPTIONS="-Xss3072K"
 daps -d DC-create-all-adoc package-html --xsltparam="'--stringparam build.for.web=0'" --pagefiles
 my_ll=$(echo %{my_lang} | tr [:upper:] [:lower:])
 bookhtml=$(echo $package_dir/*_${my_ll}-html.tar.bz2)
 bookhtml=${bookhtml##*/}
 # untar it for installation
 tar xvf $package_dir/$bookhtml
 bk=${bookhtml%%_${my_ll}-html.tar.bz2}
 [ -d $bk ] || bk=${bk}_draft
 echo $bk > %{name}.filelist
 cp $package_dir/*.page %name.page
 
 # create JSP files for SUSE Manager online help
 daps -d DC-susemanager-jsp html --jsp
 export FOP_STACK="-Xss2048K"
 # use this function to build the PDFs
 build_pdf () {
   book=$(echo ${1} | tr [:upper:] [:lower:])
   pkg_pdf=$(daps -d DC-${1} package-pdf --formatter=fop --name=$book)
   pdfname=$(find $pkg_pdf -name '*.pdf')
   echo $pdfname > ${book}_en-pdf.filelist
 }
 for b in susemanager-getting-started susemanager-reference susemanager-best-practices susemanager-advanced-topics; do
   build_pdf $b
 done
 
 %install
 cd %{_builddir}/%{name}-%{version}/create-all
 mkdir -p %{buildroot}%{_defaultdocdir}
 # GNOME help system
 # product is name without language code
 # update the RPM filelist
 install -d %{buildroot}%{_datadir}/gnome/help/susemanager-docs
 cp -a --dereference $(head -n 1 %{name}.filelist) \
   %{buildroot}/%{_defaultdocdir}/%{name}
 gnome_help_dir=%{_datadir}/help/C/gnome-help
 mkdir -p %{buildroot}$gnome_help_dir
 cp %name.page %{buildroot}$gnome_help_dir/%name.page
 {
   echo "%dir $gnome_help_dir"
   echo "$gnome_help_dir/%name.page"
 } > %name.filelist
 # Create the link to make the book visible in yelp; bnc#866668
 pushd %{buildroot}%{_datadir}/help/C
 ln -s ../../doc/manual/%{name} create-all
 popd
 echo "%{_datadir}/help/C/create-all" >> %name.filelist
 # JSP files
 %define jsp_root /srv/tomcat/webapps/rhn/help
 mkdir -p ${RPM_BUILD_ROOT}%{jsp_root}
 pushd build/susemanager-jsp/jsp/susemanager-jsp
 cp -a * ${RPM_BUILD_ROOT}%{jsp_root}
 # css confuses jsp output; remove it
 rm -f ${RPM_BUILD_ROOT}%{jsp_root}/static/css/susebooks.css
 rm -f ${RPM_BUILD_ROOT}%{jsp_root}/index.jsp
 popd
 
 # update the PDF file lists
 for f in *-pdf.filelist; do
   mkdir %{buildroot}/%{_defaultdocdir}/${f%\.filelist}
   # PDF first
   cp -a --dereference $(head -n 1 $f) \
     %{buildroot}/%{_defaultdocdir}/${f%\.filelist}
   # remove first line and append the new location
   sed -i 1d $f
   echo "%{_defaultdocdir}/${f%\.filelist}" >> $f
   bb=${f%_en-pdf\.filelist}
   b=${bb#susemanager-}
   sub_dir=${RPM_BUILD_ROOT}/srv/tomcat/webapps/rhn/help/$b
   subpdf_dir=$sub_dir/en-US/pdf
   mkdir -p $subpdf_dir
   cp %{_sourcedir}/$bb.index.jsp $sub_dir/index.jsp
   pushd $subpdf_dir
   pkgpdf_dir=usr/share/doc/manual/${bb}_en-pdf
   mkdir -p ${RPM_BUILD_ROOT}/$pkgpdf_dir
   ln -sf ../../../../../../../../$pkgpdf_dir/${bb}_en.pdf
   popd
   {
     echo "%dir /srv/tomcat/webapps/rhn/help/$b"
     echo "%dir /srv/tomcat/webapps/rhn/help/$b/en-US"
     echo "/srv/tomcat/webapps/rhn/help/$b/index.jsp"
     echo "/srv/tomcat/webapps/rhn/help/$b/en-US/pdf"
   } >> $f
 done
 
 %fdupes '%{buildroot}%{_docdir}'
 
 # remove offending white papers; leftovers
 rm -fr %{buildroot}/srv/tomcat/webapps/rhn/help/white-papers
 
 %post -n susemanager-jsp_en
 # bnc#726100
 rm -fr /var/cache/tomcat/Catalina/localhost/rhn/org/apache/jsp/help
 
 %files -n susemanager-getting-started_en-pdf -f create-all/susemanager-getting-started_en-pdf.filelist
 %defattr(-, root, root)
 
 %files -n susemanager-reference_en-pdf -f create-all/susemanager-reference_en-pdf.filelist
 %defattr(-, root, root)
 
 %files -n susemanager-best-practices_en-pdf -f create-all/susemanager-best-practices_en-pdf.filelist
 %defattr(-, root, root)
 
 %files -n susemanager-advanced-topics_en-pdf -f create-all/susemanager-advanced-topics_en-pdf.filelist
 %defattr(-, root, root)
 
 %files -f create-all/%{name}.filelist
 %defattr(-, root, root)
 %dir %{_defaultdocdir}
 %{_defaultdocdir}/%{name}
 
 %files -n susemanager-jsp_en
 # bnc#776374
 %defattr(-, root, root)
 %{jsp_root}/advanced-topics/en-US
 %{jsp_root}/best-practices/en-US
 %{jsp_root}/getting-started/en-US
 %{jsp_root}/reference/en-US
 %{jsp_root}/images
 %{jsp_root}/static
 %{jsp_root}/*.jsp
 %attr(775, tomcat, tomcat) %dir /srv/tomcat/webapps/rhn
 %attr(775, tomcat, tomcat) %dir %{jsp_root}
 
 %changelog