[GitHub] [logging-log4j-tools] vy opened a new issue, #38: Support running `ChangelogExporter` against a single release+template combination

["vy (via GitHub)" <gi...@apache.org>]

vy opened a new issue, #38:
URL: https://github.com/apache/logging-log4j-tools/issues/38

   While making a new release, it is pretty common to generate _the release notes_ for different use cases: website, binary distribution, announcement email, etc. In order to cater the exported changelogs to all these use cases, `ChangelogExporter` should ideally support to be run against a single release+template combination, e.g., _"run `ChangelogExporter` against `2.20.0` release using `.changelog-email.txt.ftl`"_.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [logging-log4j-tools] vy closed issue #38: Support running `ChangelogExporter` against a single release+template combination

["vy (via GitHub)" <gi...@apache.org>]

vy closed issue #38: Support running `ChangelogExporter` against a single release+template combination
URL: https://github.com/apache/logging-log4j-tools/issues/38


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [logging-log4j-tools] vy commented on issue #38: Support running `ChangelogExporter` against a single release+template combination

["vy (via GitHub)" <gi...@apache.org>]

vy commented on issue #38:
URL: https://github.com/apache/logging-log4j-tools/issues/38#issuecomment-1466862414

   ### Short story
   
   Reverted this work and implemented #44 instead.
   
   ### Long story
   
   I have tried to use this feature exactly as it is advertised: created `.changelog.txt.ftl` and `.changelog.adoc.ftl` files. The _content_ overlap between two files were big: the entire section of release notes. Hence I created a `.changelog.common.ftl` and included it in both `.changelog.txt.ftl` and `.changelog.adoc.ftl`. Yet this did not work out either for various reasons:
   
   * TXT requires certain formatting, e.g., max 80 characters in a line. Adopting this in ADOC breaks [one-sentence-per-line](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line) convention. Yet, it is doable.
   * ADOC syntax (`xref:#foo[var]`, `= H1`, `== H2`, etc.) simply doesn't work for TXT and renders the generated TXT file unreadable.
   
   Two files containing identical information, yet formatted differently... I sort of realized trying to solve this problem using two templates is not a smart move. What I need is a translation tool. And the following ADOC to TXT magic worked like a charm:
   
   ```
   # Generate DocBook XML from AsciiDoc using `asciidoc`
   asciidoc -b docbook changelog.adoc
   
   # Generate plain text from DocBook XML using `pandoc`
   pandoc -f docbook -t plain changelog.xml -o changelog.txt
   
   # Generate GitHub-flavored Markdown from DocBook XML using `pandoc`
   pandoc -f docbook -t markdown_gfm changelog.xml -o changelog.md
   ```
   
   We just need to make this `asciidoc`+`pandoc` combo a part of the release process.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org