From 1be876fee8df52d3bc330e4b79b06177bd619b35 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Wed, 5 Apr 2023 23:27:31 +0200 Subject: [PATCH] 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 --- .github/workflows/continuous-integration.yaml | 1 + CHANGELOG.adoc | 11 +- .../main/java/org/asciidoctor/Options.java | 16 +- .../java/org/asciidoctor/OptionsBuilder.java | 22 +- .../jruby/internal/AsciidoctorUtils.java | 5 +- .../WhenAsciidoctorLogsToConsole.java | 4 +- .../WhenSourceHighlightingIsUsed.java | 4 +- .../org/asciidoctor/util/TestHttpServer.java | 2 +- .../integrationguide/OptionsTest.java | 6 +- .../extension/YellBlockProcessorTest.java | 6 +- .../HighlightJsHighlighterTest.java | 6 +- .../ROOT/pages/asciidoctor-api-options.adoc | 233 ++++++++++-------- 12 files changed, 183 insertions(+), 133 deletions(-) diff --git a/.github/workflows/continuous-integration.yaml b/.github/workflows/continuous-integration.yaml index 6c7f48066..c521fa2cb 100644 --- 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 index b73997f7b..8c26fc7b2 100644 --- 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 index ede39d98b..5048873b9 100644 --- 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 attributes) { this.options.put(ATTRIBUTES, attributes); } + /** + * Toggle including header and footer into the output. + * + * @param standalone true to generate a standalone output document + * (which includes the shell around the body content, such + * as the header and footer). + * Defaults to true when converting a file only, + * otherwise is false. + */ + public void setStandalone(boolean standalone) { + this.options.put(STANDALONE, standalone); + } + /** * Toggle including header and footer into the output. * @@ -85,7 +97,7 @@ public void setHeaderFooter(boolean headerFooter) { public void setTemplateDirs(String... templateDirs) { if (!this.options.containsKey(TEMPLATE_DIRS)) { - this.options.put(TEMPLATE_DIRS, new ArrayList()); + this.options.put(TEMPLATE_DIRS, new ArrayList<>()); } List allTemplateDirs = (List) this.options.get(TEMPLATE_DIRS); diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java b/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java index f4354d226..df97c7fd4 100644 --- a/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java +++ b/asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java @@ -59,13 +59,28 @@ public OptionsBuilder inPlace(boolean inPlace) { return this; } + /** + * Toggle including header and footer into the output. + * + * @param standalone true to generate a standalone output document + * (which includes the shell around the body content, such + * as the header and footer). + * Defaults to true when converting a file only, + * otherwise is false. + */ + 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); 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 index a684b3106..4829b6999 100644 --- 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 getOptions(Map 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 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 index 00c942dce..6bb27c0ee 100644 --- 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 logRecords = new ArrayList<>(); @@ -274,7 +274,7 @@ public Object process(StructuralNode parent, Reader reader, Map } @Test - public void a_extension_should_be_able_to_log() throws Exception { + public void a_extension_should_be_able_to_log() { final List 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 index 4be249279..038c16999 100644 --- 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 index b9b8948bf..e29b2852e 100644 --- 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 resources) { .channel(NioServerSocketChannel.class) .childHandler(new ChannelInitializer() { @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 index 63443c7fa..db2e33fcc 100644 --- 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/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/YellBlockProcessorTest.java b/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/YellBlockProcessorTest.java index 60bdbdc50..e6885c147 100644 --- a/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/extension/YellBlockProcessorTest.java +++ b/asciidoctorj-documentation/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/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/syntaxhighlighter/HighlightJsHighlighterTest.java b/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/syntaxhighlighter/HighlightJsHighlighterTest.java index 98807eaaa..7a6423014 100644 --- a/asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/syntaxhighlighter/HighlightJsHighlighterTest.java +++ b/asciidoctorj-documentation/src/test/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"); diff --git a/docs/modules/ROOT/pages/asciidoctor-api-options.adoc b/docs/modules/ROOT/pages/asciidoctor-api-options.adoc index 0fb1894a8..7039660b6 100644 --- a/docs/modules/ROOT/pages/asciidoctor-api-options.adoc +++ b/docs/modules/ROOT/pages/asciidoctor-api-options.adoc @@ -20,115 +20,6 @@ include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=simpleOp NOTE: The `convert` method is overloaded so `org.asciidoctor.Options`, `org.asciidoctor.OptionsBuild` or `java.util.Map` can be used. -== toFile - -Via the option `toFile` it is possible to define if a document should be written to a file at all and to which file. - -To make the API return the converted document and not write to a file set `toFile(false)`. - -To make Asciidoctor write to the default file set `toFile(true)`. -The default file is computed by taking the base name of the input file and adding the default suffix for the target format like `.html` or `.pdf`. -That is for the input file `test.adoc` the resulting file would be in the same directory with the name `test.html`. + -*This is also the way the CLI behaves.* - -To write to a certain file set `toFile(targetFile)`. -This is also necessary if you want to convert string content to files. - -The following example shows how to convert content to a dedicated file: - -[source,java,indent=0] -.Example for converting to a dedicated file ----- -include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=optionToFile] ----- -<1> Set the option `toFile` so that the result will be written to the file pointed to by `targetFile`. -<2> Set the safe mode to `UNSAFE` so that files can be written. -See <> for a description of this option. - -[[safemode]] -== safe - -Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. -Each level includes the restrictions enabled in the prior security level. -All safe modes are defined by the enum `org.asciidoctor.SafeMode`. - -include::partial$safe-modes.adoc[] - -So if you want to render documents in the same way as the CLI does you have to set the safe mode to `Unsafe`. -Without it you will for example not get the stylesheet embedded into the resulting document. - -[source,java,indent=0] -.Converting a document in unsafe mode ----- -include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=unsafeConversion] ----- -<1> Sets the safe mode from `SECURE` to `UNSAFE`. -<2> Don't convert the file to another file but to a string so that we can easier verify the contents. - -The example above will succeed with these two asciidoc files: - -[source,asciidoc,indent=0] -.includingcontent.adoc --- - = Including content - - include::includedcontent.adoc[] --- - -[source,asciidoc] -.includedcontent.adoc ----- -This is included content ----- - -== backend - -Defines the target format for which the document should be converted. -Among the possible values are `html5`, `pdf` or `docbook`. - -[source,java,indent=0] -.Converting a document to PDF ----- -include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=optionsPDFBackend] ----- - -== inPlace - -Tells the converter to store the output to a file adjacent to the input file. -This is `true` by default. - -[source,java,indent=0] -.Setting inPlace option ----- -OptionsBuilder optionsBuilder = - Options.builder().inPlace(true); ----- - -== templateDirs - -Specifies a directory of {url-tilt}[Tilt]-compatible templates to be used instead of the default built-in templates. - -[source,java] -.Setting templateDirs option ----- -OptionsBuilder optionsBuilder = - Options.builder().templateDirs(new File("templates_path")); ----- - -[[sourcemap]] -== sourcemap - -Keeps track of the file and line number for each parsed block. -This is useful for tooling applications where the association between the converted output and the source file is important. -The default for this option is `false`. - -[source,java] -.Setting the option sourcemap ----- -OptionsBuilder optionsBuilder = - Options.builder().sourcemap(true); ----- - == attributes This option allows to define document attributes externally. @@ -208,3 +99,127 @@ attributesMap.put("my-attribute", "my-value"); Attributes.builder() .attributes(attributesMap); ---- + +== backend + +Defines the target format for which the document should be converted. +Among the possible values are `html5`, `pdf` or `docbook`. + +[source,java,indent=0] +.Converting a document to PDF +---- +include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=optionsPDFBackend] +---- + +== inPlace + +Tells the converter to store the output to a file adjacent to the input file. +This is `true` by default. + +[source,java,indent=0] +.Setting inPlace option +---- +OptionsBuilder optionsBuilder = + Options.builder().inPlace(true); +---- + +[[safemode]] +== safe + +Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. +Each level includes the restrictions enabled in the prior security level. +All safe modes are defined by the enum `org.asciidoctor.SafeMode`. + +include::partial$safe-modes.adoc[] + +So if you want to render documents in the same way as the CLI does you have to set the safe mode to `Unsafe`. +Without it you will for example not get the stylesheet embedded into the resulting document. + +[source,java,indent=0] +.Converting a document in unsafe mode +---- +include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=unsafeConversion] +---- +<1> Sets the safe mode from `SECURE` to `UNSAFE`. +<2> Don't convert the file to another file but to a string so that we can easier verify the contents. + +The example above will succeed with these two asciidoc files: + +[source,asciidoc,indent=0] +.includingcontent.adoc +-- + = Including content + + include::includedcontent.adoc[] +-- + +[source,asciidoc] +.includedcontent.adoc +---- +This is included content +---- + +[[sourcemap]] +== sourcemap + +Keeps track of the file and line number for each parsed block. +This is useful for tooling applications where the association between the converted output and the source file is important. +The default for this option is `false`. + +[source,java] +.Setting the option sourcemap +---- +OptionsBuilder optionsBuilder = + Options.builder().sourcemap(true); +---- + +== standalone + +If `true`, generates a standalone output document (which includes the shell around the body content, such as the header and footer). +When converting to a file, the default value is `true`. +Otherwise, the default value is `false`. + +[source,java] +.Setting the option sourcemap +---- +OptionsBuilder optionsBuilder = + Options.builder().standalone(false); +---- + +NOTE: This option replaces and works in the same way as the previous `headerFooter`. + +== templateDirs + +Specifies a directory of {url-tilt}[Tilt]-compatible templates to be used instead of the default built-in templates. + +[source,java] +.Setting templateDirs option +---- +OptionsBuilder optionsBuilder = + Options.builder().templateDirs(new File("templates_path")); +---- + +== toFile + +Via the option `toFile` it is possible to define if a document should be written to a file at all and to which file. + +To make the API return the converted document and not write to a file set `toFile(false)`. + +To make Asciidoctor write to the default file set `toFile(true)`. +The default file is computed by taking the base name of the input file and adding the default suffix for the target format like `.html` or `.pdf`. +That is for the input file `test.adoc` the resulting file would be in the same directory with the name `test.html`. + +*This is also the way the CLI behaves.* + +To write to a certain file set `toFile(targetFile)`. +This is also necessary if you want to convert string content to files. + +The following example shows how to convert content to a dedicated file: + +[source,java,indent=0] +.Example for converting to a dedicated file +---- +include::example$org/asciidoctor/integrationguide/OptionsTest.java[tags=optionToFile] +---- +<1> Set the option `toFile` so that the result will be written to the file pointed to by `targetFile`. +<2> Set the safe mode to `UNSAFE` so that files can be written. +See <> for a description of this option.