Sonatype Book Toolset Setup on Mac OSX Using brew.sh

sonatype-books-osx.md

OSX Book Environment - Without the Virtual Machine

This was an experiment to see if you could build the Sonatype Books without a virtual machine, using only OSX Sierra and the book toolset installed directly into the OS.

It seems to be possible, but the caveat is that it is very different than what our CI system uses. Therefore relying on it solely could introduce subtle issues overtime. The CI and Docbuntu approach is going to continue to be the standard to be relied upon for final verification.

Installing Sonatype Book Toolset Onto OSX Sierra

Basic Requirements

OSX Sierra

Bash

Git

Install http://brew.sh/ and make sure it is working

Steps

1. Choose a parent directory and checkout the git source code of our book projects according to the existing instructions. For these instructions, I used ~/dev/sonatype/docs as the location where I checked out all the other projects. Therefore I created a directory a where book documentation will be assembled locally at ~/dev/sonatype/docs/books.sonatype.com

2. Add to your .bash_profile / .profile these lines:

    export NEXUS_DOCUMENTATION=~/dev/sonatype/docs/books.sonatype.com
    export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
   

3. brew install asciidoc

4. brew install ImageMagick

5. Install BASicTeX from https://www.tug.org/mactex/morepackages.html

6. Make yourself the owner of the tex installation directory:

    $ sudo chown -R "$(id -un):$(id -gn)" /usr/local/texlive
   

7. Update tlmgr and install the required packages:

    $ tlmgr update --all
    $ tlmgr install appendix changebar footmisc multirow overpic stmaryrd subfigure titlesec wasysym
    $ tlmgr install symbol eepic rsfs helvetic courier 
   

8. dblatex is needed and in order to install it, you can use brew with a custom formulae:

   1. Create a new brew formulae file at `/usr/local/Library/Formula/dblatex.rb`
   2. Copy and paste content from here into that file: https://gist.github.com/peterlynch/bacf208b864dc6112d291eab7a7ce5c6
   3. Install dblatex: $ `brew install dblatex`
   

9. You should now be able to build the book without errors now:

    $ cd ./nexus-book-internal
    $ ./build.sh`
   

Solving Errors

convert.sh is missing

This comes with ImageMagick - brew install ImageMagick and then it should be found.

xmllint fails with exit status 4

xmllint is invoked by asciidoc to validate xml files. Instead of skipping the xmllint execution, find out why it is failing.

See Debugging a2x.

It the error is "Validation failed: no DTD found" then, you need to add this to ~/.bash_profile or ~/.profile: export XML_CATALOG_FILES=/usr/local/etc/xml/catalog

Debugging a2x ( and the tools it invokes )

Add two -v to the a2x execution - like -v -v

The first flag debugs a2x, the second debugs a tool that a2x invokes.

Solving dblatex errors

If you see any errors about missing *.sty files or fonts, then:

1. Lookup up the tex package that contains the file: tlmgr info <filename>
2. Install the missing package: tlmgr install <packagename>

Example error: overpic.sty: File `epic.sty' not found

pdflatex failed /usr/local/texlive/2016basic/texmf-dist/tex/latex/overpic/overpic.sty: File `epic.sty' not found. /usr/local/texlive/2016basic/texmf-dist/tex/latex/overpic/overpic.sty:39: Emergency stop. /usr/local/texlive/2016basic/texmf-dist/tex/latex/overpic/overpic.sty:39: leading text: ^^M Unexpected error occured

Example error: Could not map source abbreviation for psyr:

/usr/local/texlive/2016basic/texmf-dist/web2c/mktexnam: Could not map source abbreviation for psyr. /usr/local/texlive/2016basic/texmf-dist/web2c/mktexnam: Need to update ?

First locate where this psyr file is

tlmgr info psyr

This tells us it is in the symbol package, so

tlmgr install symbol

Thank you for sharing!