solr/solr-ref-guide/src/meta-docs/pdf.adoc

= Making Changes to the PDF Version
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The main published artifact of the Solr Reference Guide is a PDF document.

The PDF version of the Ref Guide uses `asciidoctor-pdf` (indirectly) to convert the `.adoc` files to PDF.

In order for all of the various files to be converted into a single, large, PDF file, another `.adoc` file must be created.

== About asciidoctor-pdf

Our PDF build process uses the https://github.com/asciidoctor/asciidoctor-ant[`asciidoctor-ant`] project to integrate Asciidoctor.

The `asciidoctor-ant` project is really an Ant wrapper around https://github.com/asciidoctor/asciidoctorj[`asciidoctorj`]. This is a Java binding of several Asciidoctor projects that produces a .jar that includes Asciidoctor, Asciidoctor PDF and Asciidoctor EPub.

Since it is a binding for the Ruby implementations of these three projects, they each work the same way they would if we were using the Ruby versions.

== Configuring the PDF Theme

Nearly all of the styling and layout of the PDF is controlled by a single YAML file that is called a theme.

See the section <<Modifying the Theme>> for information on how to update the theme.

=== Declaring the Theme to Use

Our theme is `refguide-theme.yml`, found in `solr/solr-ref-guide/pdf/themes`.

New themes must be named to include `-theme.yml` at the end. They must also be in proper YAML format.

The theme to use when generating the PDF is defined with the `pdf-style` attribute. Only the first part of the file name is used. So, a theme file named `refguide-theme.yml` is selected by defining `pdf-style=refguide`.

In the section <<Asciidoctor PDF Attributes>> below, we can see how we've declared this in our Ant target.

=== Modifying the Theme

All of the styling capabilities are described in the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide].

== About the Uber-Document

In order for all of the files in `.adoc` format to be compiled into a single PDF, we need to give the process one `.adoc` file (an "uber-document") that includes all of the content we want in the PDF. In other words, there is no command that says "take all the files in this directory and make one PDF".

Asciidoctor has a nice feature called the _include directive_, which allows you to insert content from another file into the current file (more details in the http://asciidoctor.org/docs/user-manual/#include-directive[Asciidoctor documentation]).

We wanted to make sure we didn't add to the burden of maintaining the PDF by asking everyone to update the uber-document or trying to institute some sort of check on if all the pages are included and in the right place in the hierarchy. Instead, the uber-document is build programmatically at build time.

The uber-document is found in `solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc`. This document is very simple - it includes only the Apache license statement and a single `include` directive to another file:

[source]
\include::_data/pdf-main-body.adoc[]

The Ant target `build-pdf` includes a dependency on another target, `build-nav-data-files`. This target looks at each document and builds the `pdf-main-body.adoc` file with the proper hierarchy of all pages.

NOTE: You will not see the `pdf-main-body.adoc` in `solr/solr-ref-guide/src/_data` directory. This file exists only once it has been built, and it is placed in the build directory, at `solr/solr-ref-guide/build/content_data`.

== Configuring the build-pdf Ant Target

Since most of the styling and layout is defined by the theme, the options that must be configured in the Ant target relate to where to find referenced files, font directories, image directories, and similar top-level document settings.

There are two types of settings at work in our Ant target. First are the settings which are part of the `asciidoctor-ant` jar. Second, we are able to declare any Asciidoctor PDF attribute (setting) that we want to apply to the entire PDF.

Our Ant target (`build-pdf`) uses the following settings:

[source,xml]
----
<asciidoctor:convert
             sourceDirectory="${build.content.dir}/pdf"
             sourceDocumentName="SolrRefGuide-all.adoc"
             baseDir="${build.content.dir}"
             outputDirectory="${build.dir}"
             backend="pdf"
             extensions="adoc"
             sourceHighlighter="coderay"
             embedAssets="true"
             imagesDir="${build.content.dir}"
             doctype="book"
             safemode="unsafe">
  <attribute key="icons" value="font" />
  <attribute key="icon-set" value="fa" />
  <attribute key="pdf-stylesDir" value="./pdf/themes"/>
  <attribute key="pdf-style" value="refguide"/>
  <attribute key="pdf-fontsDir" value="./pdf/fonts"/>
  <attribute key="pagenums" value='' />
  <attribute key="figure-caption!" value='' />
  <attribute key="idprefix" value='' />
  <attribute key="idseparator" value='-' />
  <!-- attributes used in adoc files -->
  <!-- NOTE: If you add any attributes here for use in adoc files, you almost certainly need to also add
      them to the _config.yml.template file for building the jekyll site as well
  -->
  <!-- ... -->
</asciidoctor:convert>
----

There are a lot of options here. Note that some include the `<attribute>` tag and some do not. Those that do not are options provided by `asciidoctor-ant` so don't need any special syntax. The options with the `<attribute>` tag are not provided by `asciidoctor-ant` but are supported by `asciidoctor-pdf` so will be applied when the target is run. A few of these are custom variables that we have defined ourselves.

=== Asciidoctor Ant Attributes

`sourceDirectory="${build.content.dir}/pdf"`:: Defines where to find the source file to build the PDF. The variable is declared earlier in `build.xml`.
`sourceDocumentName="SolrRefGuide-all.adoc"`:: The source file name, which in our case will be built as described in the section <<About the Uber-Document>>.
`baseDir="${build.content.dir}"`:: The root path for any included files.
`outputDirectory="${build.dir}"`:: Defines where the resulting PDF file should go. In this case, the
`backend="pdf"`:: The output format. The `asciidoctor-ant` jar is also capable of outputting DocBook format, so we must declare we want a PDF.
`extensions="adoc"`:: The file extensions to allow for the source document.
`sourceHighlighter="coderay"`:: The library to use for syntax highlighting source code.
`imagesDir="${build.content.dir}"`:: The directory to use to find images referenced in the documents.
`doctype="book"`:: Adds support for book-style format and sections, such as a preface, colophon, glossary, index, etc.
`safemode="unsafe">`:: Allows including resources that are external to the parent directory of the source file. For example, source examples could be pulled from Solr's source code instead of copied to documentation. This setting allows that to happen.

=== Asciidoctor PDF Attributes

`<attribute key="icons" value="font" />`:: The style of icons.
`<attribute key="icon-set" value="fa" />`:: The icon set to use. We use the Font Awesome font set.
`<attribute key="pdf-stylesDir" value="./pdf/themes"/>`:: The directory to find PDF themes. See the section <<Configuring the PDF Theme>> for more details on themes.
`<attribute key="pdf-style" value="refguide"/>`:: The theme to use. The theme must be saved in the directory referenced with the `pdf-stylesDir` attribute, and must be named `<pdf-style>-theme.yml`.
`<attribute key="pdf-fontsDir" value="./pdf/fonts"/>`:: The directory where to find fonts declared in the theme.
`<attribute key="figure-caption!" value='' />`:: Sets caption labels and numbers (such as "Figure 1") to block images. The exclamation at the end of this setting in our config _disables_ figure captioning.
`<attribute key="idprefix" value='' />`:: Sets the prefix for auto-generated section IDs, such as those from headings in a page. In our config, this is effectively "null", so auto-generated section IDs do not have any prefix.
`<attribute key="idseparator" value='-' />`:: Sets the separator between words in auto-generated section IDs to a hyphen (`-`).

=== Custom Attributes

These attributes use variables that are inserted by Ant during the PDF creation process. This allows us to pull from standard Lucene/Solr build files, and not have to update several places for any release. The Ant build process updates the `_config.yml` file from the `_config.yml.template`, then these attributes pull the proper value from that file.

`<attribute key="solr-guide-draft-status" value="${solr-guide-draft-status}" />`:: Indicates if this is a `DRAFT` PDF or not.
`<attribute key="solr-guide-version" value="${solr-guide-version}" />`:: The version of the Guide itself.
`<attribute key="solr-docs-version" value="${solr-docs-version}" />`:: The version of Solr covered by this guide.
`<attribute key="solr-javadocs" value="${solr-javadocs}" />`:: Sets the path for Solr javadoc links to include the right path for the current release version.
`<attribute key="lucene-javadocs" value="${lucene-javadocs}" />`:: Sets the path for Lucene javadoc links to the right path for the current release version.
`<attribute key="build-date" value="$\{DSTAMP}" />`:: Sets the date of the build to add the date to the footer of each page of the PDF.
`<attribute key="build-year" value="${current.year}" />`:: Sets the year of the build to add the date to the copyright notice.