Deprecate 'headerFooter' in favour of 'standalone'

* Replace headerFooter methods in OptionsBuild & Options * Added 'standalone' description to docs Other changes included: * Re-ordered options in docs to follow alphabetical order * Remove some unnecessary throws from tests * Add missing '@deprecated' to templateDir method * Add v2.5.x branch to run GH actions Fixes #1160
asciidoctor · Apr 7, 2023 · 665660d · 665660d
1 parent b76d453
commit 665660d
Show file tree

Hide file tree

Showing 12 changed files with 183 additions and 133 deletions.
diff --git a/.github/workflows/continuous-integration.yaml b/.github/workflows/continuous-integration.yaml
@@ -6,6 +6,7 @@ on:
   pull_request:
     branches:
       - main
+      - v2.5.x
   schedule:
     - cron: '0 0 * * *'
 

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -13,6 +13,14 @@ For a detailed view of what has changed, refer to the {url-repo}/commits/main[co
 
 == Unreleased
 
+Improvement::
+
+* Add 'standalone' option, deprecates 'headerFooter' (#1160) (@abelsromero)
+
+Bug Fixes::
+
+* Fix destinationDir not having effect. Deprecate destinationDir in favour of toDir (#853, #941) (@abelsromero)
+
 == 2.5.7 (2022-10-21)
 
 Improvement::
@@ -21,9 +29,6 @@ Improvement::
 * Upgrade to asciidoctorj-diagram 2.2.4 (#1140)
 * Upgrade to jruby 9.3.10.0 (#1138) (@alexlevinfr)
 
-Bug Fixes::
-* Fix destinationDir not having effect. Deprecate destinationDir in favour of toDir (@abelsromero) (#853, #941)
-
 Build / Infrastructure::
 
 * Replace use of deprecated 'numbered' attribute by 'sectnums' (#1127) (@abelsromero)

diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/Options.java b/asciidoctorj-api/src/main/java/org/asciidoctor/Options.java
@@ -1,6 +1,5 @@
 package org.asciidoctor;
 
-import java.io.File;
 import java.io.OutputStream;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -71,6 +70,19 @@ public void setAttributes(Map<String, Object> attributes) {
         this.options.put(ATTRIBUTES, attributes);
     }
 
+    /**
+     * Toggle including header and footer into the output.
+     *
+     * @param standalone <code>true</code> to generate a standalone output document
+     *                   (which includes the shell around the body content, such
+     *                   as the header and footer).
+     *                   Defaults to <code>true</code> when converting a file only,
+     *                   otherwise is <code>false</code>.
+     */
+    public void setStandalone(boolean standalone) {
+        this.options.put(STANDALONE, standalone);
+    }
+
     /**
      * Toggle including header and footer into the output.
      *

diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java b/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java
@@ -59,15 +59,30 @@ public OptionsBuilder inPlace(boolean inPlace) {
         return this;
     }
 
+    /**
+     * Toggle including header and footer into the output.
+     *
+     * @param standalone <code>true</code> to generate a standalone output document
+     *                   (which includes the shell around the body content, such
+     *                   as the header and footer).
+     *                   Defaults to <code>true</code> when converting a file only,
+     *                   otherwise is <code>false</code>.
+     */
+    public OptionsBuilder standalone(boolean standalone) {
+        this.options.setStandalone(standalone);
+        return this;
+    }
+
     /**
      * Sets header footer attribute.
-     * 
-     * @param headerFooter
-     *            value.
+     *
+     * @param headerFooter value.
      * @return this instance.
+     * @deprecated Use {@link #standalone(boolean)} instead.
      */
+    @Deprecated
     public OptionsBuilder headerFooter(boolean headerFooter) {
-        this.options.setHeaderFooter(headerFooter);
+        this.options.setStandalone(headerFooter);
         return this;
     }
 
@@ -80,6 +95,7 @@ public OptionsBuilder headerFooter(boolean headerFooter) {
      *            directory where templates are stored.
      * @return this instance.
      */
+    @Deprecated
     public OptionsBuilder templateDir(File templateDir) {
         this.options.setTemplateDirs(templateDir.getAbsolutePath());
         return this;

diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/internal/AsciidoctorUtils.java b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/internal/AsciidoctorUtils.java
@@ -86,7 +86,8 @@ private static List<String> getOptions(Map<String, Object> options) {
             optionsAndAttributes.add(options.get(Options.ERUBY).toString());
         }
 
-        if (options.containsKey(Options.HEADER_FOOTER)) {
+        // Check HEADER_FOOTER in case it's set directly
+        if (options.containsKey(Options.STANDALONE) || options.containsKey(Options.HEADER_FOOTER)) {
             optionsAndAttributes.add(AsciidoctorCliOptions.NO_HEADER_FOOTER);
         }
 
@@ -144,7 +145,7 @@ private static List<String> getAttributeSyntax(String attributeName,
 
         if (attributeValue != null && !"".equals(attributeValue.toString().trim())) {
             argument.append("=");
-            argument.append(attributeValue.toString());
+            argument.append(attributeValue);
         }
 
         if(attributeValue == null) {

diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/WhenAsciidoctorLogsToConsole.java b/asciidoctorj-core/src/test/java/org/asciidoctor/WhenAsciidoctorLogsToConsole.java
@@ -188,7 +188,7 @@ public void shouldOnlyNotifyFromRegisteredAsciidoctor() throws Exception {
     }
 
     @Test
-    public void shouldNoLongerNotifyAfterUnregisterOnlyNotifyFromRegisteredAsciidoctor() throws Exception {
+    public void shouldNoLongerNotifyAfterUnregisterOnlyNotifyFromRegisteredAsciidoctor() {
 
         final List<LogRecord> logRecords = new ArrayList<>();
 
@@ -274,7 +274,7 @@ public Object process(StructuralNode parent, Reader reader, Map<String, Object>
     }
 
     @Test
-    public void a_extension_should_be_able_to_log() throws Exception {
+    public void a_extension_should_be_able_to_log() {
 
         final List<LogRecord> logRecords = new ArrayList<>();
 

diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/WhenSourceHighlightingIsUsed.java b/asciidoctorj-core/src/test/java/org/asciidoctor/WhenSourceHighlightingIsUsed.java
@@ -27,7 +27,7 @@ public class WhenSourceHighlightingIsUsed {
     private Asciidoctor asciidoctor;
 
     @Test
-    public void should_render_with_rouge() throws Exception {
+    public void should_render_with_rouge() {
         String html = asciidoctor.convert(DOCUMENT,
             OptionsBuilder.options()
                 .headerFooter(true)
@@ -43,7 +43,7 @@ public void should_render_with_rouge() throws Exception {
     }
 
     @Test
-    public void should_render_with_coderay() throws Exception {
+    public void should_render_with_coderay() {
         String html = asciidoctor.convert(DOCUMENT,
             OptionsBuilder.options()
                 .headerFooter(true)

diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/util/TestHttpServer.java b/asciidoctorj-core/src/test/java/org/asciidoctor/util/TestHttpServer.java
@@ -46,7 +46,7 @@ private TestHttpServer(Map<String, File> resources) {
                 .channel(NioServerSocketChannel.class)
                 .childHandler(new ChannelInitializer<Channel>() {
                     @Override
-                    protected void initChannel(Channel ch) throws Exception {
+                    protected void initChannel(Channel ch) {
                         ChannelPipeline pipeline = ch.pipeline();
                         pipeline.addLast("codec", new HttpServerCodec());
                         pipeline.addLast("aggregator", new HttpObjectAggregator(MAX_MESSAGE_LENGTH));

diff --git a/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/OptionsTest.java b/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/OptionsTest.java
@@ -66,7 +66,7 @@ public void options_for_pdf_document() throws Exception {
     }
 
     @Test
-    public void convert_in_unsafe_mode() throws Exception {
+    public void convert_in_unsafe_mode() {
 //tag::unsafeConversion[]
         File sourceFile =
 //end::unsafeConversion[]
@@ -113,7 +113,7 @@ public void convert_to_dedicated_file() throws Exception {
     }
 
     @Test
-    public void use_font_awesome_icons() throws Exception {
+    public void use_font_awesome_icons() {
 //tag::attributeFontIcons[]
         String result =
             asciidoctor.convert(
@@ -122,7 +122,7 @@ public void use_font_awesome_icons() throws Exception {
                     "{foo}",
                     Options.builder()
                             .toFile(false)
-                            .headerFooter(false)
+                            .standalone(false)
                             .attributes(
                                     Attributes.builder()                                          // <1>        
                                             .icons(Attributes.FONT_ICONS)                         // <2>

diff --git a/...tion/src/test/java/org/asciidoctor/integrationguide/extension/YellBlockProcessorTest.java b/...tion/src/test/java/org/asciidoctor/integrationguide/extension/YellBlockProcessorTest.java
@@ -24,7 +24,7 @@ public class YellBlockProcessorTest {
     private ClasspathResources classpathResources;
 
     @Test
-    public void should_invoke_block_processor() throws Exception {
+    public void should_invoke_block_processor() {
 //tag::include[]
         File yellblock_adoc = //...
 //end::include[]
@@ -41,7 +41,7 @@ public void should_invoke_block_processor() throws Exception {
     }
 
     @Test
-    public void should_invoke_block_processor_with_attributes() throws Exception {
+    public void should_invoke_block_processor_with_attributes() {
         File yellblock_adoc = //...
             classpathResources.getResource("yell-block-attributes.adoc");
 
@@ -53,7 +53,7 @@ public void should_invoke_block_processor_with_attributes() throws Exception {
     }
 
     @Test
-    public void should_invoke_block_processor_with_positional_attributes() throws Exception {
+    public void should_invoke_block_processor_with_positional_attributes() {
         File yellblock_adoc = //...
             classpathResources.getResource("yell-block-positional.adoc");
 

diff --git a/...t/java/org/asciidoctor/integrationguide/syntaxhighlighter/HighlightJsHighlighterTest.java b/...t/java/org/asciidoctor/integrationguide/syntaxhighlighter/HighlightJsHighlighterTest.java
@@ -33,7 +33,7 @@ public class HighlightJsHighlighterTest {
     public TemporaryFolder tempDir;
 
     @Test
-    public void should_invoke_syntax_highlighter() throws Exception {
+    public void should_invoke_syntax_highlighter() {
 //tag::include[]
         File sources_adoc = //...
 //end::include[]
@@ -56,7 +56,7 @@ public void should_invoke_syntax_highlighter() throws Exception {
     }
 
     @Test
-    public void should_invoke_syntax_highlighter_with_3_params() throws Exception {
+    public void should_invoke_syntax_highlighter_with_3_params() {
         File sources_adoc =
             classpathResources.getResource("sources.adoc");
 
@@ -75,7 +75,7 @@ public void should_invoke_syntax_highlighter_with_3_params() throws Exception {
     }
 
     @Test
-    public void should_invoke_formatting_syntax_highlighter() throws Exception {
+    public void should_invoke_formatting_syntax_highlighter() {
         File sources_adoc =
             classpathResources.getResource("sources.adoc");