WIP Initial draft of DocBook build instructions #7

terales · 2018-01-25T19:19:10Z

Closes #5

Here is a suggested workflow for this PR:

I created a draft of DocBook building instructions (WIP prefix at PR means work in progress, do not merge).
Someone who can build the DocBook comes and either answer my questions in comments so I would update instruction or commit fixed instruction by himself.
I would follow the instruction and verify that it could be reproduced from the clean machine by a person who just follows the instruction.
If there are any troubles I'll ask for clarifications or missing files there.
I remove the WIP suffix and ask to verify the instruction inside this PR.
After positive feedback, I or someone else will merge it into the master branch.

terales

I need some help from someone who can successfully build DocBook.

terales · 2018-01-25T19:20:16Z

docbook/README.md

+### Prerequisites
+
+* [Java 8](https://www.java.com/en/download/)
+* [Saxon-PE](http://www.saxonica.com/download/java.xml)


@DavidFatDavidF you've mentioned in #3 (comment):

So far we are using only preliminary, built-in oXygen transforms but Jano is working on modified stylesheets for HTML and PDF

Can you provide direct links to the missing prerequisites, please?

terales · 2018-01-25T19:20:30Z

docbook/README.md

+### Prerequisites
+
+* [Java 8](https://www.java.com/en/download/)
+* [Saxon-PE](http://www.saxonica.com/download/java.xml)


What edition of Saxon do we use? Can we use a community edition?

I would go for HE.

terales · 2018-01-25T19:20:56Z

docbook/README.md

+Run from the project root folder:
+```
+java -jar saxon9pe.jar -xsl:./docbook/T1/WG3/XLIFF-EM-BP.xml_xslt -s:./docbook/T1/WG3/ -o:./docs/
+```


The command with these parameters returns error:

Static error at fo:root on line 1 column 375 of XLIFF-EM-BP.xml_xslt: XTSE0150: The supplied file does not appear to be a stylesheet The supplied file does not appear to be a stylesheet

What commands and params are you using?

DavidFatDavidF · 2018-01-25T20:00:46Z

Hi @terales can u try and build with the xslt resources I committed?
These seem all that are needed locally when I am building. There's however apparently an unresolved dependency to a Saxon connector. You will need to resolve that locally with the free Saxon ur running and later by referencing the Saxon run as part of the Travis build.. I hope this helps..

terales · 2018-01-25T20:02:31Z

Thanks for resources! Let me check

terales · 2018-01-25T20:13:59Z

Running with either -xsl:.\docbook\xsl\oxygen_custom.xsl or -xsl:.\docbook\xsl\oxygen_custom.xsl throws this error:

Static error at xsl:call-template on line 18 column 65 of oxygen_custom.xsl:
  XTSE0650: Cannot find a template named add-xml-base
Errors were reported during stylesheet compilation

DavidFatDavidF · 2018-01-29T18:53:47Z

sorry swamped, now will try to address this before I leave for vacation on Wed.. @JanHusarcik could you please look into the xsls and prehaps provide @terales with a working and self-contained set?

terales · 2018-01-29T22:50:44Z

If it works for you we can set up a quick call to address all issues in one try

JanHusarcik · 2018-01-30T11:52:56Z

@terales could you pls try building using https://sourceforge.net/projects/docbook/?

DavidFatDavidF · 2018-01-30T18:57:13Z

I won't manage to help here b4 I leave tomorrow.. Perhaps @rmraya can help?

rmraya · 2018-01-30T19:16:37Z

I can help if you tell me what the problem is. This morning I started playing with the content uploaded to GitHub and it looked fine, except for a problem with fonts not being fully Unicode aware when creating a PDF (this is something I have to change in my local XEP configuration). Rodolfo

…

-- Rodolfo M. Raya rmraya@maxprograms.com Maxprograms https://www.maxprograms.com From: dF <notifications@github.com> Reply-To: GALAglobal/TAPICC <reply@reply.github.com> Date: Tuesday, January 30, 2018 at 3:57 PM To: GALAglobal/TAPICC <TAPICC@noreply.github.com> Cc: "Rodolfo M. Raya" <rmraya@maxprograms.com>, Mention <mention@noreply.github.com> Subject: Re: [GALAglobal/TAPICC] WIP Initial draft of DocBook build instructions (#7) I won't manage to help here b4 I leave tomorrow.. Perhaps @rmraya can help? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

DavidFatDavidF · 2018-01-30T19:27:07Z

@rmraya we can build HTML and pdf from Docbook locally with Oxygen with the framework xsl and FO resources. @terales is trying to determine a set of XSL that would allow for an automated HTML build on GitHub. We are now trying for HTML but eventually we would also like to automate the pdf build..
At some point the xsls will need adjusted to display all as we want, the Oxygen framework layouts are not ideal and are not displaying everything we need as we need..

terales · 2018-01-30T19:30:07Z

Hey guys,
I'm not that experienced with DocBook but if I follow this guide than all things are working fine on Ubuntu:

sudo apt-get install default-jre fop xsltproc docbook docbook-xsl docbook-dsssl
xsltproc -o ./docs/T1/WG3/XLIFF-EM-BP-ED.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl ./docbook/T1/WG3/XLIFF-EM-BP.xml
fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml ./docbook/T1/WG3/XLIFF-EM-BP.xml -pdf ./docs/T1/WG3/XLIFF-EM-BP-ED.pdf

Do you know about any problems or missing features with this approach?
These commands are enough to have an automated build and I can use them if you don't see any drawbacks

Please, find example output attached: example-output.zip

It seems the same for me with current version in master except the title style

rmraya · 2018-01-30T20:12:55Z

Two details come to my mind: You are using the default XSL stylesheets from Norman Walsh. Those are too generic and the ones from Oxygen that David uploaded to GitHub should look better PDF from Fop does not look as good as PDF from XEP or Antenna House (AH). You can use Fop for testing but for real publishing, we should use XEP or AH. Regards, Rodolfo

…

-- Rodolfo M. Raya rmraya@maxprograms.com Maxprograms https://www.maxprograms.com From: Alexander <notifications@github.com> Reply-To: GALAglobal/TAPICC <reply@reply.github.com> Date: Tuesday, January 30, 2018 at 4:30 PM To: GALAglobal/TAPICC <TAPICC@noreply.github.com> Cc: "Rodolfo M. Raya" <rmraya@maxprograms.com>, Mention <mention@noreply.github.com> Subject: Re: [GALAglobal/TAPICC] WIP Initial draft of DocBook build instructions (#7) Hey guys, I don't any experienced with DocBook but if I follow this guide than all things are working fine on Ubuntu: sudo apt-get install default-jre fop xsltproc docbook docbook-xsl docbook-dsssl xsltproc -o ./docs/T1/WG3/XLIFF-EM-BP-ED.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl ./docbook/T1/WG3/XLIFF-EM-BP.xml fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml ./docbook/T1/WG3/XLIFF-EM-BP.xml -pdf ./docs/T1/WG3/XLIFF-EM-BP-ED.pdf Do you know about any problems or missing features with this approach? It's enough to have an automated environment — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

terales · 2018-01-30T20:37:17Z

Thanks for the feedback!

You are using the default XSL stylesheets from Norman Walsh. Those are too generic and the ones from Oxygen that David uploaded to GitHub should look better

I'll try it tomorrow.

PDF from Fop does not look as good as PDF from XEP or Antenna House (AH). You can use Fop for testing but for real publishing, we should use XEP or AH.

I suggest to split our efforts:

I'll prepare basic Travis CI config and installation of all dependencies which are required to prepare an HTML,
you will continue from there to build a PDF,
I will set up automated commits to the gh-pages branch

@rmraya what do you think?

rmraya · 2018-01-30T20:49:40Z

I can build PDF using XEP as often as needed. XEP and AH are commercial products, I don’t think we can use our licenses in a GitHub build process. Regards, Rodolfo

…

-- Rodolfo M. Raya rmraya@maxprograms.com Maxprograms https://www.maxprograms.com From: Alexander <notifications@github.com> Reply-To: GALAglobal/TAPICC <reply@reply.github.com> Date: Tuesday, January 30, 2018 at 5:37 PM To: GALAglobal/TAPICC <TAPICC@noreply.github.com> Cc: "Rodolfo M. Raya" <rmraya@maxprograms.com>, Mention <mention@noreply.github.com> Subject: Re: [GALAglobal/TAPICC] WIP Initial draft of DocBook build instructions (#7) Thanks for the feedback! You are using the default XSL stylesheets from Norman Walsh. Those are too generic and the ones from Oxygen that David uploaded to GitHub should look better I'll try it tomorrow. PDF from Fop does not look as good as PDF from XEP or Antenna House (AH). You can use Fop for testing but for real publishing, we should use XEP or AH. I suggest to split our efforts: I'll prepare basic Travis CI config and installation of all dependencies which are required to prepare an HTML, you will continue from there to build a PDF, I will set up automated commits to the gh-pages branch @rmraya what do you think? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

terales · 2018-01-31T16:07:45Z

Great!

So I'll configure only HTML version this week. Thanks a lot for your input

terales · 2018-02-04T22:26:08Z

Hello all,

I've just pushed initial Travis CI configuration for automated HTML builds which would be deployed into gh-pages branch.

It's not ready for merging because I have trouble with special character encodings:
https://terales.github.io/tapicc-test/T1/WG3/XLIFF-EM-BP.html

Can you suggest how to fix it, please?

JanHusarcik · 2018-02-07T18:19:03Z

Hi @terales
looking at docbook\xsl\html\docbook.xsl, I see

<xsl:output method="html" encoding="ISO-8859-1" indent="no"/>

This should be ideally changed to utf-8. More details in xsl:output.

Jan

PS. could you please @ me, to make sure I get notified :)

terales · 2018-02-07T19:38:09Z

Thanks, @JanHusarcik ! As I found we have to change encoding in docbook/xsl/html/profile-docbook.xsl

Here is a result:

// custom
https://terales.github.io/tapicc-test/T1/WG3/XLIFF-EM-BP-ED.html

// automated
https://terales.github.io/tapicc-test/T1/WG3/XLIFF-EM-BP.html

I hope there is the last difference (custom on the left, automated on right):

Do you have any idea why T1/WG3 is missing in the automated build?

terales · 2018-02-15T17:16:36Z

@JanHusarcik do you have any idea about the fix? Or it's better to start using it as it is and fix later?

JanHusarcik · 2018-02-15T17:42:21Z

Hi @terales

there is something seriously wrong with my GH notifications. Looking into this.

J.

JanHusarcik · 2018-02-19T12:37:32Z

@terales It would seem that automated build does not resolve entities stored in docbook\T1\WG3\dbgenent.mod. Do you have any logs? It should complain about not defined entities.

J

simonech · 2018-05-10T12:59:00Z

Hi, how is the process on this task?
At a conference I had a chat with @DavidFatDavidF and I can help if needed.
I'm not an expert in docbook tho.
But referring to issue #15 it might be a good idea to build artefacts outside of the repository. Probably the best would be to create a gh-pages branch, and commit them over there, so they don't pollute the repo.
This way we can also fix the links from the homepage of the github pages site, which points outside of the pages folder (#16)

terales · 2018-07-07T21:25:38Z

Hi @simonech ,
I was absent for a long time. Now I'm back for a volunteering work and I would finish the automated publishing in the gh-pages branch until July 13.

…-instructions

terales · 2018-07-07T23:22:41Z

@JanHusarcik can you help me with loading external entities, please?

I'm having a hard time loading external entities.

Your manually published document has a line:

Extraction and merging examples from https://galaglobal.github.io/TAPICC/T1/WG3/wd01/extraction_examples/

Automatically generated and published document miss entities:

Extraction and merging examples from https://galaglobal.github.io/TAPICC////extraction_examples/
                                                                        ^^^^

DocBook build logs:

$ xsltproc --encoding utf-8 -o ./../../../docs/T1/WG3/XLIFF-EM-BP.xhtml ./../../xsl/tapicc.xsl ./XLIFF-EM-BP.xml
Note: namesp. cut : stripped namespace before processing           XLIFF 2 Extraction and Merging Best Practice, Version 1.0
Writing docbook.css for article

terales · 2018-08-01T14:58:51Z

Thanks to Jan, we're able to automatically build the DocBook!

Here is a result from the test repo:
https://terales.github.io/tapicc-test/T1/WG3/XLIFF-EM-BP.xhtml

If it seems OK, we could safely merge this PR.
The next steps are:

configure Travis CI for this repo (I would do it).
change the versioning scheme: we would always build the master branch and separate releases would be published in GitHub Releases section with appropriate links from "Top level page for TAPICC deliverables" (I think @JanHusarcik is aiming to that)

JanHusarcik · 2018-08-06T19:27:01Z

There are still minor issues with the results of the automated build, trying to identify the cause.

Re "change the versioning scheme", it's related to #15; still working on it.

terales · 2020-04-16T11:11:22Z

I wasn't able to replicate settings from paid publishing software within scripting open-source environment.

WIP Initial draft of DocBook build instructions

cd9ff74

terales added enhancement help wanted labels Jan 25, 2018

terales self-assigned this Jan 25, 2018

terales requested review from DavidFatDavidF and JanHusarcik January 25, 2018 19:19

terales commented Jan 25, 2018

View reviewed changes

terales mentioned this pull request Jan 25, 2018

Configure an automated build into HTML #3

Closed

committed the xsl resources to the WIP branch

8a369b4

DavidFatDavidF assigned JanHusarcik Jan 29, 2018

WIP Add initial Travis CI configuration

40747a6

Fix custom HTML encoding

e49662c

terales added 2 commits July 8, 2018 00:30

Merge remote-tracking branch 'origin/master' into 5-add-docbook-build…

687553b

…-instructions

Use docbook as working directory to load external entities

d2ddc16

terales added 3 commits July 8, 2018 02:26

Use /docbook/T1/WG3 to build deliverables

da986fb

Merge branch 'master' into 5-add-docbook-build-instructions

2a1a346

Fix images in automated build (thanks @JanHusarcik)

9e5e060

terales closed this Apr 16, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP Initial draft of DocBook build instructions #7

WIP Initial draft of DocBook build instructions #7

terales commented Jan 25, 2018 •

edited

Loading

terales left a comment

terales Jan 25, 2018

terales Jan 25, 2018

JanHusarcik Jan 30, 2018

terales Jan 25, 2018

DavidFatDavidF commented Jan 25, 2018

terales commented Jan 25, 2018

terales commented Jan 25, 2018

DavidFatDavidF commented Jan 29, 2018

terales commented Jan 29, 2018

JanHusarcik commented Jan 30, 2018

DavidFatDavidF commented Jan 30, 2018

rmraya commented Jan 30, 2018 via email

DavidFatDavidF commented Jan 30, 2018

terales commented Jan 30, 2018 •

edited

Loading

rmraya commented Jan 30, 2018 via email

terales commented Jan 30, 2018

rmraya commented Jan 30, 2018 via email

terales commented Jan 31, 2018

terales commented Feb 4, 2018

JanHusarcik commented Feb 7, 2018

terales commented Feb 7, 2018

terales commented Feb 15, 2018

JanHusarcik commented Feb 15, 2018

JanHusarcik commented Feb 19, 2018

simonech commented May 10, 2018

terales commented Jul 7, 2018 •

edited

Loading

terales commented Jul 7, 2018

terales commented Aug 1, 2018

JanHusarcik commented Aug 6, 2018

terales commented Apr 16, 2020

WIP Initial draft of DocBook build instructions #7

WIP Initial draft of DocBook build instructions #7

Conversation

terales commented Jan 25, 2018 • edited Loading

terales left a comment

Choose a reason for hiding this comment

terales Jan 25, 2018

Choose a reason for hiding this comment

terales Jan 25, 2018

Choose a reason for hiding this comment

JanHusarcik Jan 30, 2018

Choose a reason for hiding this comment

terales Jan 25, 2018

Choose a reason for hiding this comment

DavidFatDavidF commented Jan 25, 2018

terales commented Jan 25, 2018

terales commented Jan 25, 2018

DavidFatDavidF commented Jan 29, 2018

terales commented Jan 29, 2018

JanHusarcik commented Jan 30, 2018

DavidFatDavidF commented Jan 30, 2018

rmraya commented Jan 30, 2018 via email

DavidFatDavidF commented Jan 30, 2018

terales commented Jan 30, 2018 • edited Loading

rmraya commented Jan 30, 2018 via email

terales commented Jan 30, 2018

rmraya commented Jan 30, 2018 via email

terales commented Jan 31, 2018

terales commented Feb 4, 2018

JanHusarcik commented Feb 7, 2018

terales commented Feb 7, 2018

terales commented Feb 15, 2018

JanHusarcik commented Feb 15, 2018

JanHusarcik commented Feb 19, 2018

simonech commented May 10, 2018

terales commented Jul 7, 2018 • edited Loading

terales commented Jul 7, 2018

terales commented Aug 1, 2018

JanHusarcik commented Aug 6, 2018

terales commented Apr 16, 2020

terales commented Jan 25, 2018 •

edited

Loading

terales commented Jan 30, 2018 •

edited

Loading

terales commented Jul 7, 2018 •

edited

Loading