WIP Initial draft of DocBook build instructions

terales commented 6 years ago

Closes #5

Here is a suggested workflow for this PR:

[x] I created a draft of DocBook building instructions (WIP prefix at PR means work in progress, do not merge).
[x] 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.
[x] I would follow the instruction and verify that it could be reproduced from the clean machine by a person who just follows the instruction.
[x] 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.

DavidFatDavidF commented 6 years ago

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 commented 6 years ago

Thanks for resources! Let me check

terales commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

JanHusarcik commented 6 years ago

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

DavidFatDavidF commented 6 years ago

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

rmraya commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

Great!

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

terales commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

JanHusarcik commented 6 years ago

Hi @terales

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

J.

JanHusarcik commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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.

terales commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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 commented 4 years ago

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

GALAglobal / TAPICC

WIP Initial draft of DocBook build instructions #7