search

eu-digital-identity-wallet / eudi-doc-architecture-and-reference-framework

The European Digital Identity Wallet
https://eu-digital-identity-wallet.github.io/eudi-doc-architecture-and-reference-framework/
Other
431 stars 60 forks source link

Add a Makefile target to include Annexes in (ePub) output #190

Open toonn opened 5 months ago

toonn commented 5 months ago

The ePub output provided is much appreciated. Technical documents such as the ARF are a great use of otherwise hard to productively use commute time and eReaders allow a more comfortable reading experience.

The ARF contains many references to its annexes, which are accessible on the website due to how URLs work and the annexes are hosted. However, after conversion to ePub those links are not functional.

The Markdown annexes can be very easily appended to the ePub output.

diff --git a/Makefile b/Makefile
index 56d2094..3e4b054 100644
--- a/Makefile
+++ b/Makefile
@@ -44,7 +44,7 @@ PANDOC_EPUB_OPTIONS=--to epub3

 %.epub : %.md
        mkdir -p $(BUILD_DIR)/epub
-       $(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_EPUB_OPTIONS) -o $(BUILD_DIR)/epub/$(notdir $@) $<
+       $(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_EPUB_OPTIONS) -o $(BUILD_DIR)/epub/$(notdir $@) $< docs/annexes/*/*.md

 # Targets and dependencies

This is a kludgy implementation as a proof of concept. It would happily append the annexes to any ePub generated with the Makefile, which is undesirable.

However, this does not work for the majority of annexes, which are not in the Markdown format. The PDF figures could be converted to PNG images and included in their own separate Markdown file. This would cover annex 4. Annex 5 contains two PDF documents that might be converted to Markdown if they're being authored as part of this repository. Annex 6 would be the biggest stumbling block since it's a large PDF document authored independently by ENISA, though covering all the annexes but one would still be an improvement.

Note that while I'm particularly interested in the ePub output, this would apply to any non-hosted version of the ARF, such as the PDF and Docx outputs. Even a self-contained version of the HTML output might be useful for those who prefer scrolling through a single page and using browser native find functionality for the ARF and its annexes.

skounis commented 5 months ago

@toonn Could you please review the following PR?