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.
OSX Sierra
Bash
Git
Install http://brew.sh/ and make sure it is working
-
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
-
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 -
brew install asciidoc -
brew install ImageMagick -
Install BASicTeX from https://www.tug.org/mactex/morepackages.html
-
Make yourself the owner of the tex installation directory:
$ sudo chown -R "$(id -un):$(id -gn)" /usr/local/texlive -
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 -
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` -
You should now be able to build the book without errors now:
$ cd ./nexus-book-internal $ ./build.sh`
This comes with ImageMagick - brew install ImageMagick and then it should be found.
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
Add two -v to the a2x execution - like -v -v
The first flag debugs a2x, the second debugs a tool that a2x invokes.
If you see any errors about missing *.sty files or fonts, then:
- Lookup up the tex package that contains the file:
tlmgr info <filename> - Install the missing package:
tlmgr install <packagename>
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
/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
These steps were really helpful, thank you!
To get latex to install using brew, I had to put the rb file here: /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/
which was recommended by: https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md
If I put it anywhere else, brew deleted the rb file then threw an error that it was missing:
brew install dblatex
Updating Homebrew...
To restore the stashed changes to /usr/local/Homebrew run:
'cd /usr/local/Homebrew && git stash pop'
Error: No available formula with the name "dblatex"
==> Searching for similarly named formulae...
Error: No similarly named formulae found.
==> Searching taps...
Error: No formulae found in taps.