You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2017/03/28 20:59:50 UTC
[1/2] lucene-solr:jira/solr-10290: SOLR-10298: remove some PDF build
params that are not used
Repository: lucene-solr
Updated Branches:
refs/heads/jira/solr-10290 017b890f7 -> 9bb9568b6
SOLR-10298: remove some PDF build params that are not used
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/a214ff8c
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/a214ff8c
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/a214ff8c
Branch: refs/heads/jira/solr-10290
Commit: a214ff8c79a19f1babbea530caf2536a7e7f425e
Parents: 017b890
Author: Cassandra Targett <ct...@apache.org>
Authored: Tue Mar 28 15:58:00 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Tue Mar 28 15:58:00 2017 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/build.xml | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/a214ff8c/solr/solr-ref-guide/build.xml
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/build.xml b/solr/solr-ref-guide/build.xml
index 82a3905..47e87e4 100644
--- a/solr/solr-ref-guide/build.xml
+++ b/solr/solr-ref-guide/build.xml
@@ -15,7 +15,7 @@
"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.
+ under the License.
-->
<project name="solr-ref-guide" default="default" xmlns:asciidoctor="antlib:org.asciidoctor.ant" >
@@ -124,7 +124,7 @@
<arg value="${build.dir}/html-site"/>
</java>
</target>
-
+
<!-- ====== PDF Build ======= -->
<target name="build-pdf"
depends="build-nav-data-files,resolve"
@@ -139,17 +139,14 @@
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="docinfo!" value='' />
<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='-' />
[2/2] lucene-solr:jira/solr-10290: SOLR-10300: add docs on building
PDF and HTML versions
Posted by ct...@apache.org.
SOLR-10300: add docs on building PDF and HTML versions
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/9bb9568b
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/9bb9568b
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/9bb9568b
Branch: refs/heads/jira/solr-10290
Commit: 9bb9568b65cfec495d3effb570a65ba84fd2d9a3
Parents: a214ff8
Author: Cassandra Targett <ct...@apache.org>
Authored: Tue Mar 28 15:58:47 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Tue Mar 28 15:58:47 2017 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/meta-docs/jekyll.adoc | 61 ++++++++++++
solr/solr-ref-guide/meta-docs/pdf.adoc | 131 +++++++++++++++++++++++++
2 files changed, 192 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/9bb9568b/solr/solr-ref-guide/meta-docs/jekyll.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/jekyll.adoc b/solr/solr-ref-guide/meta-docs/jekyll.adoc
new file mode 100644
index 0000000..e1ba129
--- /dev/null
+++ b/solr/solr-ref-guide/meta-docs/jekyll.adoc
@@ -0,0 +1,61 @@
+= Working with Jekyll
+:toc:
+
+The Solr Ref Guide uses Jekyll to build the HTML version of the site.
+
+== What is Jekyll?
+
+Jekyll is a static site generator, meaning that it takes some set of documents and produces HTML pages. It allows for templating of the pages, so each page has the same look and feel without having to code headers, footers, logos, etc., into every page.
+
+Jekyll is an open source project written in Ruby, online at https://jekyllrb.com/.
+
+== Jekyll-Asciidoctor Plugin
+We use a plugin for Jekyll from the Asciidoctor project to integrate Jekyll with Asciidoc formatted content. The source for the plugin is available at https://github.com/asciidoctor/jekyll-asciidoc.
+
+This plugin allows us to use Asciidoctor-style variables with Jekyll, instead of having to maintain two sets of the same variables (one for HTML version and another for PDF version).
+
+== Jekyll Basics
+
+The following sections describe the main features of Jekyll that you will encounter while working with the Solr Ref Guide.
+
+=== _config.yml
+
+The `_config.yml` is a global configuration file that drives many of the options used when building the site (particularly in our use of Jekyll).
+
+We have templatized `_config.yml` so in our use of Jekyll you will find it as `solr-ref-guide/_config.yml.template`. This allows us to define some variables during the build, and use common Lucene/Solr build parameters (such as versions, etc.).
+
+=== Front Matter
+
+Front matter for Jekyll is like a header that defines the title of the page, and any other variables that may be helpful or even required when rendering the page.
+
+Every document that will be converted to HTML *must* include at least the page title at the top of the page.
+
+The Solr Ref Guide uses the front matter to define the "short name" and permanent URL of a page, and to define the children of a page. The list of children is used to build the site navigation menu that appears to the left of each page's content.
+
+Many guides to Jekyll also say that defining the layout in the front matter is required. However, since we only have one layout for all pages, we have defined this as a default.
+
+=== Layouts
+
+Layouts define the "look and feel" of each page.
+
+Jekyll uses Liquid for page templates.
+
+For our implementation of Jekyll, layouts are found in `solr-ref-guide/src/_layouts`
+
+=== Includes
+
+Include files are usually small files that are pulled into a layout when a page is being built. They are Liquid templates that define an area of the page. This allows flexibility across layouts - all pages can have the same header without duplicating code, but different pages could have different menu options.
+
+Include files that we use define the top navigation, the page header, the page footer, and tables of contents.
+
+For our implementation of Jekyll, include files are found in `solr-ref-guide/src/_includes`.
+
+=== Data Files
+
+Data files include data such as lists, that should be included in each page. The left-hand navigation is an example of a data file.
+
+For our implementation of Jekyll, data files are found in `solr-ref-guide/src/_data`.
+
+== Building the HTML Site
+
+An Ant target `build-site` will build the full HTML site. This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/9bb9568b/solr/solr-ref-guide/meta-docs/pdf.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/meta-docs/pdf.adoc b/solr/solr-ref-guide/meta-docs/pdf.adoc
new file mode 100644
index 0000000..fda8139
--- /dev/null
+++ b/solr/solr-ref-guide/meta-docs/pdf.adoc
@@ -0,0 +1,131 @@
+= Generating PDF
+
+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.
+
+Our theme is `refguide-theme.yml`, found in `solr/solr-ref-guide/pdf/themes`.
+
+New themes must be named so they include `-theme.yml` at the end. They must also be in proper YAML format.
+
+See the section <<Modifying the Theme>> for more about how to update the theme.
+
+=== Declaring the Theme to Use
+
+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
+ -->
+ <attribute key="solr-docs-version" value="${solr-docs-version}" />
+ <attribute key="solr-javadocs" value="${solr-javadocs}" />
+ <attribute key="lucene-javadocs" value="${lucene-javadocs}" />
+ <attribute key="build-date" value="${DSTAMP}" />
+ <attribute key="build-year" value="${current.year}" />
+</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 <<Creating 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-docs-version" value="${solr-docs-version}" />`:: Sets the version to the current release version.
+`<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.