From 5a24379b1b20ebb084b3c320bd5220f1a8058b40 Mon Sep 17 00:00:00 2001 From: Cassandra Targett Date: Tue, 19 Nov 2019 14:54:30 -0700 Subject: [PATCH] SOLR-13782: Remove PDF Ref Guide build (#999) closes #999 --- dev-tools/scripts/jenkins.build.ref.guide.sh | 2 +- solr/solr-ref-guide/README.adoc | 13 +- solr/solr-ref-guide/build.xml | 78 ++---- solr/solr-ref-guide/ivy.xml | 1 - solr/solr-ref-guide/src/_config.yml.template | 5 +- solr/solr-ref-guide/src/_includes/topnav.html | 1 - solr/solr-ref-guide/src/errata.adoc | 4 +- .../solr-ref-guide/src/how-to-contribute.adoc | 13 +- solr/solr-ref-guide/src/js/customscripts.js | 2 +- solr/solr-ref-guide/src/json-facet-api.adoc | 4 - .../src/meta-docs/asciidoc-syntax.adoc | 17 +- solr/solr-ref-guide/src/meta-docs/jekyll.adoc | 5 +- solr/solr-ref-guide/src/meta-docs/pdf.adoc | 145 ---------- .../solr-ref-guide/src/meta-docs/publish.adoc | 236 +++++----------- .../src/pdf/SolrRefGuide-all.adoc | 36 --- .../src/pdf/themes/refguide-theme.yml | 260 ------------------ ...AndPDFBody.java => BuildNavDataFiles.java} | 50 +--- .../tools/CheckLinksAndAnchors.java | 62 ++--- solr/solr-ref-guide/tools/ReducePDFSize.java | 90 ------ 19 files changed, 147 insertions(+), 877 deletions(-) delete mode 100644 solr/solr-ref-guide/src/meta-docs/pdf.adoc delete mode 100644 solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc delete mode 100644 solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml rename solr/solr-ref-guide/tools/{BuildNavAndPDFBody.java => BuildNavDataFiles.java} (84%) delete mode 100644 solr/solr-ref-guide/tools/ReducePDFSize.java diff --git a/dev-tools/scripts/jenkins.build.ref.guide.sh b/dev-tools/scripts/jenkins.build.ref.guide.sh index c3203ee3fe7..34fb7784b51 100755 --- a/dev-tools/scripts/jenkins.build.ref.guide.sh +++ b/dev-tools/scripts/jenkins.build.ref.guide.sh @@ -70,4 +70,4 @@ echoRun "gem install --force --version 1.1.5 concurrent-ruby" cd solr/solr-ref-guide set -x # Re-enable command echoing -ant clean build-site build-pdf +ant clean build-site diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc index 61afa4f4d40..b8112c1a931 100644 --- a/solr/solr-ref-guide/README.adoc +++ b/solr/solr-ref-guide/README.adoc @@ -36,17 +36,15 @@ Use `gem install slim` to install. Use `gem install tilt` to install. *** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine. Use `gem install concurrent-ruby` to install. -* PDF version, via `asciidoctor-ant`: -** None beyond those required to use the main Lucene/Solr build: Java, and Ant. + == Building the Guide For details on building the ref guide, see `ant -p`. There are currently four available targets: -* `ant default`: builds both the PDF and HTML versions of the Solr Ref Guide. -* `ant build-site`: builds only the HTML version. -* `ant build-pdf`: builds only the PDF version. +* `ant default`: builds the HTML versions of the Solr Ref Guide. +* `ant build-site`: also builds the HTML version. * `ant clean`: removes the `../build/solr-ref-guide` directory. The output of all builds will be located in `../build/solr-ref-guide`. @@ -55,11 +53,10 @@ The output of all builds will be located in `../build/solr-ref-guide`. Key directories to be aware of: * `src` - where all human edited `*.adoc` files related to the Guide live, as well as various configuration, theme, and template files. -* `tools` - custom Java code for parsing metadata in our `src/*.adoc` files to produce some `_data/` files for site & pdf navigation purposes. +* `tools` - custom Java code for parsing metadata in our `src/*.adoc` files to produce some `_data/` files for site navigation purposes. * `../build/solr-ref-guide/content` - a copy of the `src` dir generated by ant where: ** `*.template` files are processed to replace ant properties with their runtime values ** some `../build/solr-ref-guide/content/_data` files are generated by our java tools based header attributes from each of the `*.adoc` files * `../build/solr-ref-guide/html-site` - HTML generated version of the ref guide -* `../build/solr-ref-guide/apache-solr-ref-guide-X.Y.pdf` - PDF generated version of the ref guide -See the additional documentation in `src/metadocs` for more information about how to edit files, build for releases, or modifying any Jekyll or PDF templates. +See the additional documentation in `src/metadocs` for more information about how to edit files, build for releases, or modifying any Jekyll templates. diff --git a/solr/solr-ref-guide/build.xml b/solr/solr-ref-guide/build.xml index f8ab3499a5b..2e089820a8d 100644 --- a/solr/solr-ref-guide/build.xml +++ b/solr/solr-ref-guide/build.xml @@ -55,16 +55,16 @@ Basic nightly/local build of the 6.1 guide... - => ant build-pdf + => ant build-site - Official release build of the 6.1 guide... + Official build of the 6.1 guide... - => ant build-pdf -Dsolr-guide-version=6.1 + => ant build-site -Dsolr-guide-version=6.1 Release of a "6.1.1" ref guide, correcting some serious error in the docs - (even if there is no 6.1.1 version - or if we've alreayd released up to 6.1.5 - of Solr itself) + (even if there is no 6.1.1 version - or if we've already released up to 6.1.5 - of Solr itself) - => ant build-pdf -Dsolr-guide-version=6.1.1 + => ant build-site -Dsolr-guide-version=6.1.1 --> @@ -98,17 +98,13 @@ else="https://lucene.apache.org/core/${solr-docs-version-path}/"> - - - - - + @@ -169,9 +165,9 @@ - + - @@ -182,17 +178,16 @@ - - + + + - - - @@ -248,36 +240,6 @@ - - - - - Finished Building ${build.dir}/${pdf-filename} - - - - - - - - - - - - - - - - - @@ -297,7 +259,8 @@ depends="build-init,build-nav-data-files" > Running Jekyll... - + + @@ -305,7 +268,7 @@ Does a very raw converstion of the adoc files to HTML for the purpose of link & anchor checking Unlike the "HTML Site Build" above, this does *NOT* require Jekyll, and can be done entirely - With ivy deps fetched automatically (just like the PDF) + With ivy deps fetched automatically. --> @@ -333,11 +296,8 @@ - - PDF: ${build.dir}/${pdf-filename} + description="Builds an HTML versions of the ref guide" + depends="build-site"> SITE: ${build.dir}/html-site/${main-page}.html diff --git a/solr/solr-ref-guide/ivy.xml b/solr/solr-ref-guide/ivy.xml index d9377e2b020..390eee083f2 100644 --- a/solr/solr-ref-guide/ivy.xml +++ b/solr/solr-ref-guide/ivy.xml @@ -25,7 +25,6 @@ - diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template index 5fc023a6064..fe5335c6518 100755 --- a/solr/solr-ref-guide/src/_config.yml.template +++ b/solr/solr-ref-guide/src/_config.yml.template @@ -11,7 +11,7 @@ gems: [jekyll-asciidoc] destination: ../html-site -# this property is useful for conditional filtering of content that is separate from the PDF. +# this property is useful for conditional filtering of content that is separate from another format (if any). output: web # this appears on the top navigation bar next to the home button @@ -34,7 +34,6 @@ port: 4015 exclude: - .idea/ - .gitignore - - pdf/ # these are defaults used for the frontmatter for these file types defaults: @@ -67,7 +66,7 @@ asciidoc: {} # (see https://github.com/asciidoctor/jekyll-asciidoc/issues/137) # # NOTE: If you add any attributes here for use in adoc files, you almost certainly need to also add -# them to the ant task for building the PDF as well. +# them to the ant task for precommit validation as well. solr-attributes: &solr-attributes-ref solr-root-path: "../../../" solr-guide-draft-status: "${solr-guide-draft-status}" diff --git a/solr/solr-ref-guide/src/_includes/topnav.html b/solr/solr-ref-guide/src/_includes/topnav.html index deeb2fe0a74..03008a0cc5c 100755 --- a/solr/solr-ref-guide/src/_includes/topnav.html +++ b/solr/solr-ref-guide/src/_includes/topnav.html @@ -19,7 +19,6 @@
  • Other Formats diff --git a/solr/solr-ref-guide/src/errata.adoc b/solr/solr-ref-guide/src/errata.adoc index 10f3edba2ea..3076af3543e 100644 --- a/solr/solr-ref-guide/src/errata.adoc +++ b/solr/solr-ref-guide/src/errata.adoc @@ -18,9 +18,7 @@ == Errata For This Documentation -Any mistakes found in this documentation after its release will be listed on the on-line version of this page: - -https://lucene.apache.org/solr/guide/{solr-docs-version}/errata.html +Any mistakes found in this documentation after its release will be listed below. === Errata For Past Versions of This Documentation diff --git a/solr/solr-ref-guide/src/how-to-contribute.adoc b/solr/solr-ref-guide/src/how-to-contribute.adoc index 4a30dbedf13..2d27bc9ac9f 100644 --- a/solr/solr-ref-guide/src/how-to-contribute.adoc +++ b/solr/solr-ref-guide/src/how-to-contribute.adoc @@ -22,13 +22,6 @@ The Lucene/Solr project has made it easy for anyone to contribute to the Solr Re The Guide is written in simple AsciiDoc-formatted files, and the source lives in the main Lucene/Solr source repository, right alongside the code. -// This section only appears in the PDF version of the Ref Guide. -ifdef::backend-pdf[] -Find information on how to contribute to documentation online at https://lucene.apache.org/solr/guide/how-to-contribute.html. -endif::[] - -// This section only appears in the HTML version of the Ref Guide. -ifdef::backend-html5[] The following sections give an overview of how to work with AsciiDoc-format files, how our documentation is generated, and how to do a Ref Guide release. Once you have a patch you'd like to contribute, you can submit it with a JIRA issue, the same as any other patch. See also the Solr wiki section on https://wiki.apache.org/solr/HowToContribute[How To Contribute] for information on submitting patches. @@ -39,12 +32,10 @@ include::meta-docs/asciidoc-syntax.adoc[leveloffset=+2] include::meta-docs/editing-tools.adoc[leveloffset=+2] == Modifying the Publication Formats -The Solr Reference Guide is published in two formats: HTML and PDF. Different tools are used for each. +The Solr Reference Guide is published in HTML format, using Jekyll and some plugins. include::meta-docs/jekyll.adoc[leveloffset=+2] -include::meta-docs/pdf.adoc[leveloffset=+2] - +== How to Publish the Guide // This is the how to publish section: include::meta-docs/publish.adoc[leveloffset=+1] -endif::[] diff --git a/solr/solr-ref-guide/src/js/customscripts.js b/solr/solr-ref-guide/src/js/customscripts.js index 782e45a3dc5..29c4f2ed797 100755 --- a/solr/solr-ref-guide/src/js/customscripts.js +++ b/solr/solr-ref-guide/src/js/customscripts.js @@ -56,7 +56,7 @@ $( document ).ready(function() { } else { // NOTE: using the "inner" HTML of the label... // so by default we can use "bold" (or whatever) in our asciidoc and have that - // be what people see in the PDF or when javascript is disabled, + // be what people see when javascript is disabled, // but when the pills+tabs get active, the pills won't all be bold (or whatever) pill_a.append( label.html() ); // NOTE: Removing the label isn't strictly neccessary, but makes the pills/tabs less redundent diff --git a/solr/solr-ref-guide/src/json-facet-api.adoc b/solr/solr-ref-guide/src/json-facet-api.adoc index f7682ebd77f..10d313fb7d8 100644 --- a/solr/solr-ref-guide/src/json-facet-api.adoc +++ b/solr/solr-ref-guide/src/json-facet-api.adoc @@ -186,8 +186,6 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-json-terms-facet- ==== -- -// TODO: This table has cells that won't work with PDF: https://github.com/ctargett/refguide-asciidoc-poc/issues/13 - [width="100%",cols="20%,90%",options="header",] |=== |Parameter |Description @@ -377,8 +375,6 @@ The output from the range facet above would look a bit like: Range facet parameter names and semantics largely mirror facet.range query-parameter style faceting. For example "start" here corresponds to "facet.range.start" in a facet.range command. -// TODO: This table has cells that won't work with PDF: https://github.com/ctargett/refguide-asciidoc-poc/issues/13 - [width="100%",cols="10%,90%",options="header",] |=== |Parameter |Description diff --git a/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc b/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc index ad9a2a77eeb..776d8b2566c 100644 --- a/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc +++ b/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc @@ -19,7 +19,7 @@ The definitive manual on AsciiDoc syntax is in the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. To help people get started, however, here is a simpler cheat sheet. == AsciiDoc vs Asciidoctor Syntax -We use tools from the Asciidoctor project to build the HTML and PDF versions of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago. +We use tools from the Asciidoctor project to build the HTML version of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago. While much of the syntax between the two is the same, there are many conventions supported by Asciidoctor that did not exist in AsciiDoc. While the Asciidoctor project has tried to provide back-compatibility with the older project, that may not be true forever. For this reason, it's strongly recommended to only use the Asciidoctor User Manual as a reference for any syntax that's not described here. @@ -66,9 +66,9 @@ More info: http://asciidoctor.org/docs/user-manual/#source-code-blocks === Source Block Syntax Highlighting -The PDF and HTML outputs use Pygments to add syntax highlighting to code examples. This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case). +The HTML output uses Rouge to add syntax highlighting to code examples. This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case). -Pygments has a long selection of lexers available. You can see the full list at http://pygments.org/docs/lexers. Use one of the valid short names to get syntax highlighting for that language. +Rouge has a long selection of lexers available. You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers. Use one of the valid short names to get syntax highlighting for that language. Ideally, we will have an appropriate lexer to use for all source blocks, but that's not possible. When in doubt, choose `text`, or leave it blank. @@ -88,7 +88,7 @@ Snippets can be included directly from any file in the Lucene/Solr GIT repo by r ---- -- -When building the PDF or HTML versions of the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `build/solr-ref-guide/content` directory used by Ant. +When building the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `build/solr-ref-guide/content` directory used by Ant. In order for editors (such as ATOM) to be able to offer "live preview" of the `*.adoc` files using these includes, the `solr-root-path` attribute must also be set as a document level attribute in each file, with the correct relative path. @@ -128,7 +128,7 @@ Titles can be added to most blocks (images, source blocks, tables, etc.) by simp == Links === Link to Sites on the Internet -When converting content to HTML or PDF, Asciidoctor will automatically render many link types (such as `http:` and `mailto:`) without any additional syntax. +When converting content to HTML, Asciidoctor will automatically render many link types (such as `http:` and `mailto:`) without any additional syntax. However, you can add a name to a link by adding the URI followed by square brackets: @@ -188,9 +188,8 @@ To link to this section, there are two approaches depending on where you are lin ==== Link to Another Page To link to _another page_ or a section on another page, you must refer to the full filename and refer to the section you want to link to. -Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day. This is due to the PDF conversion - once all the pages are combined into one big page for one big PDF, the lack of a specific reference causes inter-page links to fail. - -So, *you must always link to a specific section*. If all you want is a reference to the top of another page, you can use the implicit `id` of the page -- the filename w/o the `.adoc` extension -- as your anchor reference. +Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day. +*You must always link to a specific section*. If all you want is a reference to the top of another page, you can use the implicit `id` of the page -- the filename w/o the `.adoc` extension -- as your anchor reference. Example:: To construct a link to the `upgrading-solr.adoc` page, we need to refer to the file name (`upgrading-solr.adoc`), then use the page id (`upgrading-solr`) as the anchor reference. As in: @@ -365,7 +364,7 @@ AsciiDoc supports several types of callout boxes, called "admonitions": * CAUTION * WARNING -It is enough to start a paragraph with one of these words followed by a colon (such as `NOTE:`). When it is converted to HTML or PDF, those sections will be formatted properly - indented from the main text and showing an icon inline. +It is enough to start a paragraph with one of these words followed by a colon (such as `NOTE:`). When it is converted to HTML, those sections will be formatted properly - indented from the main text and showing an icon inline. You can add titles to admonitions by making it an admonition block. The structure of an admonition block is like this: diff --git a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc index 0fba944090b..a169ea59901 100644 --- a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc +++ b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc @@ -31,7 +31,7 @@ The following sections describe the main features of Jekyll that you will encoun === 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). +This plugin allows us to use Asciidoctor-style variables with Jekyll. === _config.yml @@ -49,7 +49,7 @@ Many guides to Jekyll also say that defining the layout in the front matter is r The Solr Ref Guide uses the front matter to define some custom attributes on a per page basis: -* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content (and to order the pages in the PDF) +* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content. Other page-level elements can also be defined, such as an Asciidoctor attribute that should apply only to that page, but are not needed on a regular basis. @@ -193,7 +193,6 @@ My content... -- ---- -. Because these tabbed sections are created when the HTML and related JavaScript is loaded, when the PDF is generated it will ignore all the class and ID information in the page because it is meaningless to it (asciidoctor-pdf does not recognize roles/custom classes). In the PDF, this content will be displayed in Example Blocks, which have some formatting rules, but will not be shown as tabs and shouldn't show any other oddities. == Building the HTML Site diff --git a/solr/solr-ref-guide/src/meta-docs/pdf.adoc b/solr/solr-ref-guide/src/meta-docs/pdf.adoc deleted file mode 100644 index b7d4c626888..00000000000 --- a/solr/solr-ref-guide/src/meta-docs/pdf.adoc +++ /dev/null @@ -1,145 +0,0 @@ -= 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 <> 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 <> 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] ----- - - - - - - - - - - - - - - ----- - -There are a lot of options here. Note that some include the `` 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 `` 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 <>. -`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 - -``:: The style of icons. -``:: The icon set to use. We use the Font Awesome font set. -``:: The directory to find PDF themes. See the section <> for more details on themes. -``:: The theme to use. The theme must be saved in the directory referenced with the `pdf-stylesDir` attribute, and must be named `-theme.yml`. -``:: The directory where to find fonts declared in the theme. -``:: 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. -``:: 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. -``:: 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. - -``:: Indicates if this is a `DRAFT` PDF or not. -``:: The version of the Guide itself. -``:: The version of Solr covered by this guide. -``:: Sets the path for Solr javadoc links to include the right path for the current release version. -``:: Sets the path for Lucene javadoc links to the right path for the current release version. -``:: Sets the date of the build to add the date to the footer of each page of the PDF. -``:: Sets the year of the build to add the date to the copyright notice. diff --git a/solr/solr-ref-guide/src/meta-docs/publish.adoc b/solr/solr-ref-guide/src/meta-docs/publish.adoc index 70112ba90c1..3d60233f9b6 100644 --- a/solr/solr-ref-guide/src/meta-docs/publish.adoc +++ b/solr/solr-ref-guide/src/meta-docs/publish.adoc @@ -16,114 +16,77 @@ // specific language governing permissions and limitations // under the License. -The PDF version of the Guide is the *official* release, and requires a vote before release. +This section details how to build the Guide for publication. -The HTML version is considered a "convenience" version, and does not require a vote. +== Guide Publication Overview -It's strongly preferred that both PDF and HTML versions are available during the vote for the PDF. However, since the HTML version is not an official release, it is more of an unwritten rule to publish the HTML at the same time as producing a release candidate for the PDF. - -IMPORTANT: These instructions assume you have the proper dependencies for building HTML and are publishing both versions simultaneously. See <> for details. +. Build and publish the DRAFT version. +. Continue to update docs as needed while Lucene/Solr artifact VOTE thread is ongoing. +. After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages. == Pre-Requisites -The PDF version of the Solr Reference Guide is the *official* version. As such, it is voted on by the community before release, and is treated as an official artifact of the Lucene/Solr project. +In order to build the Ref Guide, you must have the following: -=== Pre-Requisites for PDF +* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. +* You have Subversion installed. This is needed for committing the HTML files to the production website repo. +* You have installed Ruby and several gems described in the README file located at `solr/solr-ref-guide/README.adoc` in your Lucene/Solr checkout. +* All builds must be done from the release branch the Guide is for. -The build process downloads the required .jar to build the PDF version, so the only pre-requisites are for the publication process: +NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing. -* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory. -* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key]. -* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement. -* You have Subversion installed. This is needed for committing the PDF to `dist/dev` and `dist/releases` repos. +== Build the DRAFT Guide -=== Additional Pre-Requisites for HTML +The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined. -To build the PDF locally, you need several required dependencies, listed in `solr-ref-guide/README.adoc`. If you do not have these dependencies locally, you cannot build and publish the Ref Guide. +To build the HTML: -NOTE: Builds are available via Jenkins for several branches. However, these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing. - -== Generate the PDF & HTML - -No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires. - -The build process generates the PDF, including the page hierarchy, and then runs an optimization script on the PDF to make it smaller. - -To build the PDF: - -. Run `ant clean default -Dsolr-guide-version=X.Y`, where `X.Y` is the version you want to publish (i.e., `7.4`). -. The resulting PDF will be in `solr/build/solr-ref-guide`. The HTML files will be in `solr/build/solr-ref-guide/html-site`. - -IMPORTANT: The `-Dsolr-guide-version` system property is optional. By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build. Including this system property ensures the DRAFT watermark and labels are removed from the HTML files. - -== Prepare & Upload Release Candidate - -=== Upload PDF to dist/dev - -The `dist/dev` Subversion repository includes a directory for the Solr Ref Guide at https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/[`lucene/solr/ref-guide`] which can host the release candidate (RC) during the VOTE stage of the process. - -These steps walk through checking out this directory and uploading the Guide to it. - -. Checkout the directory: `svn co https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide solr-ref-guide-rc` -* If you have already checked out this directory, you can simply update it: `svn update solr-ref-guide-rc` -. Change directories so `solr-ref-guide-rc` is your working directory (`cd solr-ref-guide-rc`). - -IMPORTANT: The next step requires that you have already generated your GPG keys. Your GPG passphrase will be required. - -[start=3] -. Run the Prep Ref Guide script to prepare the RC. This script ensures proper naming of the PDF file, generates - `.sha512` and `.asc` files and creates the proper RC sub-directories under `solr-ref-guide-rc`. -.. The structure of the input is: `prep-solr-ref-guide-rc.sh GPGkey`. -.. From the `solr-ref-guide-rc` directory, it will look something like this: +. Navigate to `./solr/solr-ref-guide`, where the Guide's `build.xml` is located. +. Run: + [source,bash] ----- -$ ~/lucene-source/dev-tools/scripts/prep-solr-ref-guide-rc.sh apache-solr-ref-guide-7.0.pdf 7.0-RC0 - -+ mkdir apache-solr-ref-guide-7.0-RC0 -+ mv apache-solr-ref-guide-7.0.pdf apache-solr-ref-guide-7.0-RC0/apache-solr-ref-guide-7.0.pdf -+ cd apache-solr-ref-guide-7.0-RC0 -+ shasum -a 512 apache-solr-ref-guide-7.0.pdf -+ gpg -u DEADBEEF --armor --output apache-solr-ref-guide-7.0.pdf.asc --detach-sig apache-solr-ref-guide-7.0.pdf - -You need a passphrase to unlock the secret key for -user: "Your Name " -4096-bit RSA key, ID DEADBEEF, created 1969-07-04 ----- +$ ant clean default + -. Add and commit the new release candidate to the `dist/dev` with these steps: -.. `svn add apache-solr-ref-guide-7.0-RC0` -.. `svn commit -m "7.0 ref guide RC0"` +This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <> for steps to produce final production-ready HTML pages. +. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`. + +== Upload to the Website -=== Upload HTML Files // A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required. -==== Step 1: Update extpaths.txt in CMS Staging +*Step 1: Update extpaths.txt in CMS Staging* . Checkout CMS trunk: + [source,bash] -svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source +$ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source + * If you already have this repo checked out, you can simply `svn up website-source` to update to the latest revision. -. `cd website-source` -. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt` +. `$ cd website-source` (where you just checked out the repo) +. Add the path for the new Guide version: ++ +[source,bash] +$ echo solr/guide/X_Y >> extpaths.txt ++ +where `X_Y` is the new version (i.e, `7_7`) . Commit changes: + [source,bash] -svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt +$ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt -==== Step 2: Push Guide to Website Production +*Step 2: Push Guide to Website Production* -Go to the checkout directory where you have built the Guide and push the documentation via subversion import. You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/6_5`, you'll use the path as shown in the below example: +Push the Guide directly to production via Subversion `import` from where you built it. + +You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/7_7`, you'll use the path as shown in the below example: [source,bash] -svn -m "Add Ref Guide for Solr 6.5" import /solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/6_5 +svn -m "Add Ref Guide for Solr 7.7" import /solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7 -Confirm you can browse to these URLs manually, and especially that Solr javadocs link back to lucene's correctly. Example: -https://lucene.apache.org/solr/guide/6_5 +Confirm you can browse to Guide manually by going to the new URL. For example: +https://lucene.apache.org/solr/guide/7_7 -==== Step 3: Push Staging extpaths.txt to Production +*Step 3: Push Staging extpaths.txt to Production* The `extpaths.txt` works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in `extpaths.txt` exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in `extpaths.txt`. @@ -131,65 +94,48 @@ After pushing the content to production, check that the `extpaths.txt` in produc Production URL: https://lucene.apache.org/extpaths.txt -== Hold a VOTE -Votes must be sent to the lucene-dev mailing list (`dev@lucene.apache.org`). - -. Send an email to `dev@lucene.apache.org` with subject, "VOTE: Release Apache Solr Ref Guide for Solr X.Y". -. The body of the email should include the full URL of the RC directory in the `dist/dev` repo. Such as: https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-7.0-RC0 -. You can add your own +1 to the vote announcement email. -. If there are issues that need to be resolved, you can start the process over, using RC1, RC2, etc., as needed. - -NOTE: Ideally, the HTML version will also be available for voters to review. - == Publish the Guide -=== Move the PDF to dist/releases +There are two steps to publishing the Guide: first, uploading the DRAFT pages with the production-ready version; and second, updating links to point to the new Guide. -Once at least three PMC members have voted for release (see https://www.apache.org/foundation/voting.html#ReleaseVotes[Apache Voting Process] for details on the rules for votes), the release candidate can be released. +=== Update DRAFT for Release -. Use the Publish Solr Ref Guide script (`publish-solr-ref-guide.sh`) to generate the proper SVN commands to be run to execute a remote move of the RC files to the final `dist/releases` repository. -.. The script takes only the version and _RC number that passed the vote_ as inputs, such as `7.0-RC0`. -.. The input and output of the script will look like this: +Since the Guide has already been published, you need to update the production +website repository and overwrite the existing files: + +*Build Production Guide* + +Build the Guide locally with a parameter for the Guide version. This requires the same <> from above. + +[source,bash] +$ant clean default -Dsolr-guide-version=X.Y + +where `X.Y` is the version you want to publish (i.e., `7.7`). + +IMPORTANT: The `-Dsolr-guide-version` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `lucene/version.properties` file in the current branch and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-Dsolr-guide-version` system property ensures the DRAFT watermark and labels are removed from the HTML files. + +*Pull Production Repo and Upload New Files* + +. Checkout the directory you need to update from the production repo: + [source,bash] ----- -$ ~/lucene-source/dev-tools/scripts/publish-solr-ref-guide-rc.sh X.Y-RCZ - -## Run the following commands when ready... -svn move -m 'publishing apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.asc https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.sha512 https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/ - -svn rm -m 'cleaning up apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ ----- -[start=2] -. The release should propagate to as many mirrors as possible before announcing the release, generally 24 hours is long enough. Use the Poll Mirrors script (`poll-mirrors.py`) to check the status: +$ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/ + -[source,bash] -python3 -u ~/lucene-source/dev-tools/scripts/poll-mirrors.py -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf +* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above. +* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_. +. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/build/solr-ref-guide/html-site 7_7/.` +. Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add ` or `svn rm ` as needed. +. Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"` -* This script requires Python 3 to be installed on your machine. -* If you have over 85% of the mirrors with the file, it's OK to go ahead with the announcement. -. You may get an automated email about updating the ASF release repository; you can safely ignore this email. +*Verify Upload Successful* -=== Archive Old PDF Versions -. The `dist/releases` repo is only meant to keep the latest releases. Shortly after new releases are mirrored, they are copied to `archive.apache.org`, so older releases can safely be deleted from `dist/releases` since they have been backed up in the archives. -.. Run the Archive Ref Guide script (`archive-solr-ref-guide.sh`) using the X.Y version of the Ref Guide that has just been published. Older RCs will also be removed. -.. Again, this script doesn't do any direct removal of files, it only outputs SVN commands for you to copy and paste: -+ -[source,bash] ----- -$ ~/lucene-source/dev-tools/scripts/archive-solr-ref-guide.sh X.Y -## Run the following commands when ready... - -# Delete old releases -svn rm -m 'removing archived ref guide files prior to X.Y' https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.asc https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.sha512 - -# Delete old RC files -svn rm -m 'cleaning up old RCs now that X.Y has been released' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC0/ https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC1/ ----- +Spot-check a few pages to verify that the DRAFT watermark is gone, and also + that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor + page has a lot of Javadoc links). === Make New HTML Version the Default -When the PDF is announced as available, the HTML version should already be available on the Solr website. There are a few steps to take to make the new HTML version the default. +There are a few steps to take to make the new HTML version the default. TIP: You can use the CMS system for these changes, or you can edit the file locally and commit it to the staging repo. @@ -197,46 +143,6 @@ TIP: You can use the CMS system for these changes, or you can edit the file loca . Update the Guide redirect rule that looks like the below in `content/.htaccess` so URLs without a version in the path are redirected to the latest available version. + [source,text] -RedirectMatch temp /solr/guide/(?!index.html)([a-z].*) /solr/guide/7_0/$1 +RedirectMatch temp /solr/guide/(?!index.html)([a-z].*) /solr/guide/7_7/$1 + -In the above example, you would change the `7_0` part of the path to the right version (`7_1`, etc.). - -== Announce the Release - -Announce the availability of the new Ref Guide on `solr-user@lucene.apache.org` and CC `general@lucene.apache.org` and `announce@apache.org`. - -WARNING: You must send the announcement email from your @apache.org email address or announce@apache will reject it. - -Always use the link to the download redirector for the announcement, as it will automatically direct users to the closest mirror for download: `https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf`. - -You should include a link to the HTML version in your announcement. - -.Sample announcement -[source,text] ----- -The Lucene PMC is pleased to announce that the Solr Reference Guide -for 7.0 is now available. - -This 1,035-page PDF is the definitive guide to using Apache Solr, the -search server built on Lucene. - -The PDF Guide can be downloaded from: -https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-7.0.pdf. - -It is also available online at https://lucene.apache.org/solr/guide/7_0. ----- - -If the Guide is being published more than a day or two after the application itself, you should update the Solr website news page with the announcement (https://lucene.apache.org/solr/news.html). - -== Updating HTML Files after Publication - -If you need to re-publish an existing online copy of the Guide, you will need to checkout the directory in production website repository and overwrite the existing files: - -. Build the new HTML files locally (`ant clean build-site`), or download them from Jenkins. -. Checkout the directory you need to update from the production repo: `svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/`. -* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "6_5"). You can provide a better name locally if you prefer by adding it to the end of the command shown above. -* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_. -. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the current Guide for Solr 6.5, we'd do `cp -r /solr/build/html-site 6_5/.` -. Use `svn status` to see the files modified. -. If there are any pages added or deleted, use `svn add ` or `svn rm ` as needed. -. Commit the changes: `svn commit -m "Update production 6.5 Ref Guide"` +In the above example, you would change the `7_7` part of the path to the right version (`8_0`, etc.). diff --git a/solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc b/solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc deleted file mode 100644 index 094e3cdd628..00000000000 --- a/solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc +++ /dev/null @@ -1,36 +0,0 @@ -= Apache Solr Reference Guide: For Solr {solr-guide-version} -:toc: -:toc-title: Table of Contents -:toclevels: 1 -:author: Written by the Apache Lucene/Solr Project -:email: https://lucene.apache.org/solr -:revdate: Published {build-date} -:experimental: -// 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. - -[discrete] -= Licenses -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. - -Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Apache Lucene, Apache Solr and their respective logos are trademarks of the Apache Software Foundation. Please see the http://www.apache.org/foundation/marks/[Apache Trademark Policy] for more information. - -<<< - -include::_data/pdf-main-body.adoc[] diff --git a/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml b/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml deleted file mode 100644 index ef3244a932c..00000000000 --- a/solr/solr-ref-guide/src/pdf/themes/refguide-theme.yml +++ /dev/null @@ -1,260 +0,0 @@ -font: - catalog: - # Noto Sans supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols - # Noto Sans used for body text - Noto Sans: - normal: Noto_Sans/NotoSans-Regular.ttf - bold: Noto_Sans/NotoSans-Bold.ttf - italic: Noto_Sans/NotoSans-Italic.ttf - bold_italic: Noto_Sans/NotoSans-BoldItalic.ttf - # Inconsolata used for monospaced text & code blocks - Inconsolata: - normal: Inconsolata/Inconsolata-Regular.ttf - bold: Inconsolata/Inconsolata-Bold.ttf - italic: Inconsolata/Inconsolata-Regular.ttf - bold_italic: Inconsolata/Inconsolata-Bold.ttf - # M+1mn is from the asciidoctor-pdf project - # Provides the glyphs for callout numbers (see conum section below) - # This is a fallback font, and will only be used when it can fill in missing glyphs from other fonts - M+1mn Fallback: - normal: mplus1mn/mplus1mn-regular-ascii-conums.ttf - bold: mplus1mn/mplus1mn-bold-ascii.ttf - italic: mplus1mn/mplus1mn-italic-ascii.ttf - bold_italic: mplus1mn/mplus1mn-bold_italic-ascii.ttf - fallbacks: - - M+1mn Fallback -# page-level settings apply to the entire page -page: - background_color: '#ffffff' - layout: portrait - margin: [0.5in, 0.75in, 0.75in, 0.67in] - size: LETTER -# base-level settings are defaults for other elements -base: - align: left - # color as hex string (leading # is optional) - font_color: '#333333' - font_family: Noto Sans - font_size: 10 - line_height_length: 11 - line_height: $base_line_height_length / $base_font_size - font_size_large: round($base_font_size * 1.25) - font_size_small: round($base_font_size * 0.85) - font_size_min: $base_font_size * 0.75 - font_style: normal - border_color: '#eeeeee' - border_radius: 4 - border_width: 0.5 -vertical_rhythm: 10 -horizontal_rhythm: $base_line_height_length -vertical_spacing: $vertical_rhythm -link: - font_color: '#428bca' -# literal is used for inline monospaced strings in prose and in table cells -literal: - font_color: '#333333' - font_family: Inconsolata - font_size: 11 - background_color: '#f5f5f5' -# code is used for source code blocks -code: - font_color: $base_font_color - font_family: $literal_font_family - font_size: ceil($base_font_size) - padding: $code_font_size - line_height: 1.25 - background_color: '#f5f5f5' - border_color: '#cccccc' - border_radius: $base_border_radius - border_width: 0.75 -# headings -heading: - font_color: '#d9411e' - font_family: $base_font_family - font_style: bold - # h1 is used for part titles; equivalent to 22pt due to rounding - h1_font_size: floor($base_font_size * 2.1) - # h2 is used for chapter titles; equivalent to 20pt due to rounding - h2_font_size: floor($base_font_size * 1.9) - # equivalent to 16pt due to rounding - h3_font_size: ceil($base_font_size * 1.53) - # equivalent to 13.125pt - h4_font_size: $base_font_size_large - # equivalent to 10.5pt - h5_font_size: $base_font_size - #equivalent to 8.925pt - h6_font_size: $base_font_size_small - line_height: 1.2 - margin_top: $vertical_rhythm * 0.2 - margin_bottom: $vertical_rhythm * 0.8 - padding: [0, 0, 5, 0] -# Applies only to the title page -title_page: - align: right - logo: - top: 10% - image: image:../../images/Solr_Logo_on_white.png[pdfwidth=50%] - align: left - title: - top: 55% - font_size: $heading_h1_font_size - font_color: '#d9411e' - line_height: 0.9 - subtitle: - font_size: $heading_h3_font_size - font_style: bold_italic - line_height: 1 - authors: - margin_top: $base_font_size * 1.25 - font_size: $base_font_size - revision: - margin_top: $base_font_size * 1.25 -block: - margin_top: 0 - margin_bottom: $vertical_rhythm -caption: - align: left - font: - style: italic - color: 7a2518 - margin_inside: $vertical_rhythm / 3 - margin_outside: 0 -lead: - font_size: $base_font_size_large - line_height: 1.4 -abstract: - font_color: '#5c6266' - font_size: $lead_font_size - line_height: $lead_line_height - font_style: italic -admonition: - border_color: $base_border_color - border_width: $base_border_width - padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] - icon: - tip: - name: fa-lightbulb-o - stroke_color: '#428b30' - note: - name: fa-info-circle - stroke_color: '#19407c' - warning: - name: fa-exclamation-triangle - stroke_color: '#bf0000' - caution: - name: fa-fire - stroke_color: '#bf6900' - important: - name: fa-bolt - stroke_color: '#eeea74' -blockquote: - font_color: $base_font_color - font_size: $base_font_size - font_style: italic - border_color: $base_border_color - border_width: 5 - padding: [$vertical_rhythm / 2, $horizontal_rhythm, $vertical_rhythm / -2, $horizontal_rhythm + $blockquote_border_width / 2] - cite_font_size: $base_font_size_small - cite_font_color: '#999999' -#conums are used for inline callouts -conum: - font_family: M+1mn Fallback - font_color: $literal_font_color - font_size: $base_font_size_large - line_height: 4 / 3 -example: - border_color: $base_border_color - border_radius: $base_border_radius - border_width: 0.75 - background_color: transparent - padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] -image: - align: left - border_color: $base_border_color - border_radius: $base_border_radius - border_width: 0.75 -prose: - margin_top: 0 - margin_bottom: $vertical_rhythm -sidebar: - border_color: $page_background_color - border_radius: $base_border_radius - border_width: $base_border_width - background_color: '#eeeeee' - padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] - title: - align: center - font_color: $heading_font_color - font_family: $heading_font_family - font_size: $heading_h4_font_size - font_style: $heading_font_style -thematic_break: - border_color: $base_border_color - border_style: solid - border_width: $base_border_width - margin_top: $vertical_rhythm * 0.5 - margin_bottom: $vertical_rhythm * 1.5 -description_list: - term_font_style: bold - term_spacing: $vertical_rhythm / 4 - description_indent: $horizontal_rhythm * 1.25 -outline_list: - indent: $horizontal_rhythm * 1.5 - # NOTE item_spacing applies to list items that do not have complex content - item_spacing: $vertical_rhythm / 2 -table: - background_color: $page_background_color - head_background_color: '#e6e7e8' - #head_font_color: $base_font_color - head_font_style: bold - even_row_background_color: '#f9f9f9' - #odd_row_background_color: - foot_background_color: '#f0f0f0' - border_color: '#dddddd' - border_width: $base_border_width - cell_padding: [3, 3, 6, 3] -toc: - dot_leader_color: '#dddddd' - #dot_leader_content: '. ' - indent: $horizontal_rhythm - line_height: 1.4 -header: - font: - size: $base_font_size - color: $base_font_color - style: bold_italic - height: $base_line_height_length * 2.5 - recto_content: - left: 'Apache Solr Reference Guide {solr-docs-version}' - right: 'Page {page-number} of {page-count}' - verso_content: - left: 'Page {page-number} of {page-count}' - right: 'Apache Solr Reference Guide {solr-docs-version}' -footer: - font_size: $base_font_size_small - font_color: $base_font_color - # NOTE if background_color is set, background and border will span width of page - border_color: '#dddddd' - border_width: 0.25 - height: $base_line_height_length * 2.5 - line_height: 1 - padding: [$base_line_height_length / 2, 1, 0, 1] - vertical_align: top - #image_vertical_align: or - # additional attributes for content: - # * {page-count} - # * {page-number} - # * {document-title} - # * {document-subtitle} - # * {chapter-title} - # * {section-title} - # * {section-or-chapter-title} - # We have added some custom variables from the build, see _config.yml.template - recto_content: - right: 'Guide Version {solr-guide-version} - Published: {build-date}' - left: '(C) {build-year}, Apache Software Foundation' - verso_content: - left: 'Guide Version {solr-guide-version} - Published: {build-date}' - right: '(C) {build-year}, Apache Software Foundation' -colophon: - font_size: $base_font_size_small diff --git a/solr/solr-ref-guide/tools/BuildNavAndPDFBody.java b/solr/solr-ref-guide/tools/BuildNavDataFiles.java similarity index 84% rename from solr/solr-ref-guide/tools/BuildNavAndPDFBody.java rename to solr/solr-ref-guide/tools/BuildNavDataFiles.java index 1657f8c9bea..dbba9ca3d51 100644 --- a/solr/solr-ref-guide/tools/BuildNavAndPDFBody.java +++ b/solr/solr-ref-guide/tools/BuildNavDataFiles.java @@ -28,7 +28,7 @@ import org.asciidoctor.Asciidoctor; import org.asciidoctor.ast.DocumentHeader; -public class BuildNavAndPDFBody { +public class BuildNavDataFiles { public static void main(String[] args) throws Exception { if (args.length != 2) { @@ -83,53 +83,23 @@ public class BuildNavAndPDFBody { } } - - // Build up the PDF file, - // while doing this also build up some next/prev maps for use in building the scrollnav - File pdfFile = new File(new File(adocDir, "_data"), "pdf-main-body.adoc"); - if (pdfFile.exists()) { - throw new RuntimeException(pdfFile.toString() + " already exists"); - } + // Loop over all files "in order" to build up next/prev maps for use in building the scrollnav final Map nextPage = new HashMap(); final Map prevPage = new HashMap(); - System.out.println("Creating " + pdfFile.toString()); - try (Writer w = new OutputStreamWriter(new FileOutputStream(pdfFile), "UTF-8")) { - // Note: not worrying about headers or anything like that ... - // expecting this file to just be included by the main PDF file. + System.out.println("Looping over pages to build nav data"); - // track how deep we are so we can adjust headers accordingly - // start with a "negative" depth to treat all "top level" pages as same depth as main-page using Math.max - // (see below) - final AtomicInteger depth = new AtomicInteger(-1); - - // the previous page seen in our walk + { // the previous page seen during our walk AtomicReference previous = new AtomicReference(); mainPage.depthFirstWalk(new Page.RecursiveAction() { public boolean act(Page page) { - try { - if (null != previous.get()) { - // add previous as our 'prev' page, and ourselves as the 'next' of previous - prevPage.put(page.shortname, previous.get()); - nextPage.put(previous.get().shortname, page); - } - previous.set(page); - - // use an explicit anchor, since the auto-generated ID from the "title" might not match - // the shortname/filename - w.append("[[").append(page.shortname).append("]]\n"); - // HACK: where this file actually lives will determine what we need here... - w.write("include::../"); - w.write(page.file.getName()); - w.write("[leveloffset=+"+Math.max(0, depth.intValue())+"]\n\n"); - depth.incrementAndGet(); - return true; - } catch (IOException ioe) { - throw new RuntimeException("IOE recursively acting on " + page.shortname, ioe); + if (null != previous.get()) { + // add previous as our 'prev' page, and ourselves as the 'next' of previous + prevPage.put(page.shortname, previous.get()); + nextPage.put(previous.get().shortname, page); } - } - public void postKids(Page page) { - depth.decrementAndGet(); + previous.set(page); + return true; } }); } diff --git a/solr/solr-ref-guide/tools/CheckLinksAndAnchors.java b/solr/solr-ref-guide/tools/CheckLinksAndAnchors.java index 4d505454716..a1641f1c589 100644 --- a/solr/solr-ref-guide/tools/CheckLinksAndAnchors.java +++ b/solr/solr-ref-guide/tools/CheckLinksAndAnchors.java @@ -57,13 +57,10 @@ import org.jsoup.select.NodeVisitor; * *
      *
    • - * Asciidoctor doesn't do a good job of rectifying situations where multiple documents are included in one - * massive (PDF) document may have identical anchors (either explicitly defined, or implicitly defined because of - * section headings). Asciidoctor also doesn't support linking directly to another (included) asciidoc - * document by name, unless there is an explicit '#fragement' used in the link. + * Validates that no file contains the same anchor more then once. *
      • *
    • - * Any "relative" link should point to a file that actually exists. + * Validates that relative links point to a file that actually exists, and if it's part of the ref-guide that the '#fragement' in the link refers to an ID that exists in that file. *
      • *
    • * Our use of "Bootstrap" features leverage some custom javascript @@ -75,8 +72,7 @@ import org.jsoup.select.NodeVisitor; * *

      * This tool parses the generated HTML site, looking for these situations in order to fail the build, since - * (depending on the type of check) these situations will result in inconsistent/broken HTML, or equivalent - * problems in the generated PDF. + * (depending on the type of check) these situations will result in inconsistent/broken HTML. *

      *

      * This tool supports 2 command line options: @@ -158,12 +154,12 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does System.exit(-1); } - final Map> idsToFiles = new HashMap<>(); final Map> filesToRelativeLinks = new HashMap<>(); - final Set idsInMultiFiles = new LinkedHashSet<>(0); + final Map> filesToIds = new HashMap<>(); int totalLinks = 0; int totalRelativeLinks = 0; + int totalIds = 0; for (File file : pages) { //System.out.println("input File URI: " + file.toURI().toString()); @@ -171,6 +167,11 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does assert ! filesToRelativeLinks.containsKey(file); final List linksInThisFile = new ArrayList(17); filesToRelativeLinks.put(file, linksInThisFile); + final Set idsInThisFile = new LinkedHashSet(17); + filesToIds.put(file.getName(), idsInThisFile); + + // use this for error reporting if an ID exists multiple times in a single document + final Map> idsToNodes = new HashMap<>(); final String fileContents = readFile(file.getPath()); final Document doc = Jsoup.parse(fileContents); @@ -183,13 +184,11 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does throw new RuntimeException(file.getName() + " has no main content: " + mainContentSelector); } - // Add all of the IDs in (the content of) this doc to idsToFiles (and idsInMultiFiles if needed) + // All of the ID (nodes) in (the content of) this doc final Elements nodesWithIds = mainContent.select("[id]"); - if (bareBones) { // It's a pain in the ass to customize the HTML output structure asciidoctor's bare-bones html5 backend // so instead we "fake" that the body tag contains the attribute we use in jekyll - // (and what gets added explicitly to each top level section in the PDF) nodesWithIds.add(new Element(Tag.valueOf("body"), "").attr("id", file.getName().replaceAll("\\.html$",""))); } else { // We have to add Jekyll's to the nodesWithIds so we check the main section anchor as well @@ -213,16 +212,16 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does " contains 'preamble' anchor, this is special in jekyll and must not be used in content."); } else { foundPreamble = true; - continue; + continue; // Note: we specifically don't count this in totalIds } } - if (idsToFiles.containsKey(id)) { - idsInMultiFiles.add(id); - } else { - idsToFiles.put(id, new ArrayList(1)); + if (idsInThisFile.contains(id)) { + problems++; + System.err.println(file.toURI().toString() + " contains ID multiple times: " + id); } - idsToFiles.get(id).add(file); + idsInThisFile.add(id); + totalIds++; // Note: we specifically don't count 'preamble' } // check for (relative) links that don't include a fragment @@ -271,15 +270,6 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does problems += validateHtmlStructure(file, mainContent); } - // if there are problematic ids, report them - for (String id : idsInMultiFiles) { - problems++; - System.err.println("ID occurs multiple times: " + id); - for (File file : idsToFiles.get(id)) { - System.err.println(" ... " + file.toURI().toString()); - } - } - // check every (realtive) link in every file to ensure the frag exists in the target page for (Map.Entry> entry : filesToRelativeLinks.entrySet()) { final File source = entry.getKey(); @@ -296,16 +286,14 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does } else { if ( ! path.startsWith("../") ) { // if the dest file is part of the ref guide (ie: not an "up and out" link to javadocs) - // then we validate the fragment is known and unique... + // then we validate the fragment is known and exists in that file... final String frag = link.getFragment(); - if ( ! idsInMultiFiles.contains(frag) ) { // skip problematic dups already reported - if ( ( ! idsToFiles.containsKey(frag) ) || // no file contains this id, or... - // id exists, but not in linked file - ( ! idsToFiles.get(frag).get(0).getName().equals(path) )) { - problems++; - System.err.println("Relative link points at id that doesn't exist in dest: " + link); - System.err.println(" ... source: " + source.toURI().toString()); - } + final Set knownIdsInDest = filesToIds.get(dest.getName()); + assert null != knownIdsInDest : dest.getName(); + if (! knownIdsInDest.contains(frag) ) { + problems++; + System.err.println("Relative link points at id that doesn't exist in dest: " + link); + System.err.println(" ... source: " + source.toURI().toString()); } } } @@ -313,7 +301,7 @@ public class CheckLinksAndAnchors { // TODO: rename this class now that it does } System.err.println("Processed " + totalLinks + " links (" + totalRelativeLinks + " relative) to " + - idsToFiles.size() + " anchors in " + pages.length + " files"); + totalIds + " anchors in " + pages.length + " files"); if (0 < problems) { System.err.println("Total of " + problems + " problems found"); System.exit(-1); diff --git a/solr/solr-ref-guide/tools/ReducePDFSize.java b/solr/solr-ref-guide/tools/ReducePDFSize.java deleted file mode 100644 index 4506cae8391..00000000000 --- a/solr/solr-ref-guide/tools/ReducePDFSize.java +++ /dev/null @@ -1,90 +0,0 @@ -/* - * 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. - */ - -import java.io.File; -import java.io.IOException; -import java.io.OutputStream; -import org.apache.pdfbox.cos.COSBase; -import org.apache.pdfbox.cos.COSName; -import org.apache.pdfbox.cos.COSObject; -import org.apache.pdfbox.cos.COSStream; -import org.apache.pdfbox.pdmodel.PDDocument; -import org.apache.pdfbox.pdmodel.common.PDStream; - -/** - * A simple command line utility for reducing the size of the ref-guide PDF. - *

      - * Currently this script focuses on using {@link COSName#FLATE_DECODE} to compress the (decoded) Objects - * in the source PDF, but other improvements may be possible in the future. - *

      - *

      - * This code is originally based on the WriteDecodedDoc example provided with Apache PDFBox. - *

      - *

      - * NOTE: This class should NOT be considered a general purpose tool for reducing the size of - * any PDF. - * Decisions made in this code can and will be focused explicitly on serving the purpose of reducing the size of the - * Solr Reference Guide PDF, as originally produced by asciidoctor, and may not be generally useful for all PDFs - * "in the wild". - *

      - */ -public class ReducePDFSize { - - public static void main(String[] args) throws IOException { - if (2 != args.length) { - throw new RuntimeException("arg0 must be input file, org1 must be output file"); - } - String in = args[0]; - String out = args[1]; - PDDocument doc = null; - - try { - doc = PDDocument.load(new File(in)); - doc.setAllSecurityToBeRemoved(true); - for (COSObject cosObject : doc.getDocument().getObjects()) { - COSBase base = cosObject.getObject(); - // if it's a stream: decode it, then re-write it using FLATE_DECODE - if (base instanceof COSStream) { - COSStream stream = (COSStream) base; - byte[] bytes; - try { - bytes = new PDStream(stream).toByteArray(); - } catch (IOException ex) { - // NOTE: original example code from PDFBox just logged & "continue;"d here, 'skipping' this stream. - // If this type of failure ever happens, we can (perhaps) consider (re)ignoring this type of failure? - // - // IIUC then that will leave the original (non-decoded / non-flated) stream in place? - throw new RuntimeException("can't serialize byte[] from: " + - cosObject.getObjectNumber() + " " + - cosObject.getGenerationNumber() + " obj: " + - ex.getMessage(), ex); - } - stream.removeItem(COSName.FILTER); - OutputStream streamOut = stream.createOutputStream(COSName.FLATE_DECODE); - streamOut.write(bytes); - streamOut.close(); - } - } - doc.getDocumentCatalog(); - doc.save( out ); - } finally { - if ( doc != null ) { - doc.close(); - } - } - } -}