[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