Bug 967678 - RFE: Ability to make books Maven-buildable
RFE: Ability to make books Maven-buildable
Status: CLOSED CURRENTRELEASE
Product: PressGang CCMS
Classification: Community
Component: CSProcessor (Show other bugs)
1.1
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: Lee Newson
mmurray
:
Depends On:
Blocks: 1013895
  Show dependency treegraph
 
Reported: 2013-05-27 21:04 EDT by Misty Stanley-Jones
Modified: 2014-06-18 03:05 EDT (History)
3 users (show)

See Also:
Fixed In Version: 1.0.3
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-11-07 21:14:23 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Misty Stanley-Jones 2013-05-27 21:04:10 EDT
Some projects with with an upstream that requires that the books be buildable using Maven with jDocbook. Is it possible to provide some extra processing instructions which would create the POM files and whatever else is needed so that the exported payload could build this way? This would save some manual work for at least one project (JBDS). The specific processing instructions might be different per product or per book so we would need the ability to specify them.
Comment 1 Lee Newson 2013-05-27 21:55:14 EDT
Definitely looks doable without a great deal of effort, though what needs to be configured will have to be looked at. I assume looking at the PressGang Documentation (https://hudson.jboss.org/jenkins/job/PressGang_Documentation_Guide/lastSuccessfulBuild/artifact/target/docbook/publish/en-US/html_single/index.html) that the pom.xml is the only thing that needs configuration, so as a first step an override might be best until the actual parameters can be incorporated.
Comment 2 Misty Stanley-Jones 2013-05-27 21:59:38 EDT
Michelle, can you update this bug with the changes you have to make to the JBDS docs to make them buildable by jDocbook?

Lee, I need to stress that this would be at least slightly different for different projects or maybe even different books, depending on how the Maven build is set up.
Comment 3 mmurray 2013-05-28 01:05:21 EDT
I do the following with the contents that comes out of Pressgang and csprocessor:
1. Create a pom.xml file in the same directory as publican.cfg. On a per book basis, <docname> and <bookname> need to be configured.
2. Copy a Common_Content directory into en-US to accommodate for Common_Content files only available to Publican.
3. In the Book_Info.xml file, remove the <corpauthor> text (specifically the svg image reference).

Then build with: mvn compile.
And the output can be viewed in target/docbook/publish/en-US/html_single/index.html
Comment 4 Lee Newson 2013-06-07 09:37:17 EDT
I've added an initial preview to 0.33.0 (not released yet)

Notes:

- You can set the following new Content Spec MetaData for jDocbook builds (using examples from Michelle):

  GroupId = org.jboss.tools
  ArtifactId = Red_Hat_JBoss_Developer_Studio_Getting_Started_Guide-en-US

- The defaults for the above values are the escaped "Product" for the groupId and the escaped "Title" for the groupId (along with language). Also note that in the above you can still use maven properties ie: ArtifactId = Red_Hat_JBoss_Developer_Studio_Getting_Started_Guide-${translation}

- The <version> in the POM is populated using the "Version" with "-SNAPSHOT" amended (since we currently don't have a way to publish properly).

- The <docname> and <bookname> properties are set using the book "Title", with <docname> using the escaped "Title". (Note: I've not made these customisable, as they are only used in the pom.xml to set the <artifactId> and <name> elements, the rest of the uses are for build or output parameters.)

- I've added two addition property fields as well, so that they can be used if needed <docproduct> and <bookproduct>, which are set in the same way as <docname> and <bookname> except using the "Product" field.

- The Book_Info.xml also has the <corpauthor> removed (this element causes issues with the build formatting from just trying it quickly).

- The Common Content is copied in the same way as publican, from the publican installation directory and placed inside the book. (That is it will attempt to find the files from the brand directory first, and if they can't be found then they will be loaded from the common brand folder on a per locale basis)

- You can override the default pom.xml in the same way Author_Group.xml or Revision_History.xml can be overridden (ie --override pom.xml=/home/lnewson/pom.xml)

Usage:

  csprocessor build <ID> --format jDocbook

  csprocessor preview <ID> --format jDocbook

New Configuration:

- The following is an example of the configuration to be added to csprocessor.ini (Note: if it isn't added the below defaults will be used):

[jDocbook]
build.parameters=clean compile
preview.format=html_single

Extra Info:

I'll provide a link on Monday where a preview of 0.33.0 can be installed for review.

One thing I did notice in Michelle's examples is that the Common_Content Legal_Notice.xml actually uses a <releaseinfo> element instead of a <legalnotice> element, but in saying that the XML is not valid docbook so I'm assuming this is some other workaround.
Comment 6 Lee Newson 2013-06-27 23:11:31 EDT
0.33.0 has now been released and this has been included as a tech preview.
Comment 7 Misty Stanley-Jones 2013-07-01 22:49:23 EDT
Documented: Add Maven and jDocBook Support [20100]
Comment 8 mmurray 2013-09-17 23:07:08 EDT
Apologies for the delay. Now in a position to test this thoroughly.

Over all it works well.

First tests identified: BZ#1008820 Incorrect ENTITY declaration in Book.xml files

Other thoughts on implementation:
* In pom.xml, <version> is taken from content spec Version parameter (with -SNAPSHOT appended). Instead, I think <version> should be taken from the content spec Edition parameter and when that isn't specified fallback to the Version parameter. For example, some products have the version set to just the major number (e.g., 6) and some to the major and the minor (6.1). Products use Edition to give finer version info (e.g., 6.1.0, 6.1.0.Beta1) and it is this kind of finer detail that is needed in <version> in pom.xml.

* This version might need updating, from 2.3.5 to 2.3.6:
<groupId>org.jboss.maven.plugins</groupId>
<artifactId>maven-jdocbook-plugin</artifactId>
<version>2.3.5</version>
I understand that 2.3.5 has some bugs with injections (not they are used in this pom.xml at this time).
Comment 9 Lee Newson 2013-09-17 23:16:45 EDT
Agreed, with one minor change. It should first use the "Book Version" metadata, then fallback to "Edition" and lastly "Version". We probably also need some form of Meta Data to specify if "-SNAPSHOT" should be appended.

As for the other one that can be changed at anytime by editing the String constant (the ID is 63) via the UI (i've changed it to 2.3.6 now)

Moving it back to MODIFIED until at least the edition part is fixed.
Comment 10 Lee Newson 2013-09-19 01:33:53 EDT
Fixed the edition/version problem in csprocessor 1.0.3. As for the snapshot metadata that will have to be done in another version, as it'll require a server update.
Comment 12 mmurray 2013-09-19 21:27:14 EDT
Maven build failures

maven-jdocbook-plugin version:
* 2.3.5 - didn't include injections (not an issue here as have no injections in pom.xml) but doc builds
* 2.3.6 - throws NPE if don't have at least one (dummy) injection so build fails [https://issues.jboss.org/browse/MPJDOCBOOK-83]
* 2.3.7 - 2.3.6 issue fixed but new ISSUES!! that I haven't had time to investigate, looks like it is trying to use preface text as title of file and then complaining file name is too long?!

So have reverted version back to 2.3.5 in string constant 63.
Comment 13 Lee Newson 2013-09-24 01:47:51 EDT
Thanks for that Michelle.

I've also uploaded version 1.0.3 into the rpm repository now so that it is freely available. This version uses edition over version for the pom version as requested, so I'm going to move this back to ON_QA now.

Note You need to log in before you can comment on or make changes to this bug.