search

B-Lang-org / bsc

Bluespec Compiler (BSC)
Other
902 stars 141 forks source link

Add release notes for 2024.01 #667

Closed quark17 closed 3 months ago

quark17 commented 5 months ago

In the generated PDF (downloaded from the GitHub CI artifact generated on Ubuntu 22.04), I notice that the unicode ring operator character is not properly displayed, when viewed on my Mac. Is anyone else seeing that? Is that a failure in the document or just in my viewer?

mieszko commented 5 months ago

i think they're just missing in the font asciidoctor is using. running asciidoctor like this worked for me:

asciidoctor-pdf --theme=default-with-font-fallbacks ReleaseNotes.adoc
quark17 commented 5 months ago

Thank you! That change also worked for me, so I have a pushed a commit which updates the Makefile. The command in the Makefile was not specifying an explicit theme and so it was using default. A list of the built-in themes that can be chosen is here. That's the "Theming" section of the Asciidoctor PDF documentation; there's a subsection "Fonts" underneath that, which talks about the built-in and bundled fonts that are available and adding custom fonts. But it looks like choosing default-with-font-fallbacks is enough for us. FYI, there are also attributes that can be set which affect the output (such as scripts=cjk) as documented in the "AsciiDoc Attributes for PDF" section.

quark17 commented 5 months ago

Hm, that change works on my mac but broke on the Ubuntu VM:

asciidoctor-pdf --theme=default-with-font-fallbacks ReleaseNotes.adoc
asciidoctor: invalid option: --theme=default-with-font-fallbacks

However, the following syntax works for older Asciidoctor as well as newer, so I'll push a commit that uses that:

asciidoctor-pdf -a pdf-theme=default-with-font-fallbacks ReleaseNotes.adoc

The version of Asciidoctor PDF that is installed by the Ubuntu 22.04 package manager is an old version:

$ asciidoctor-pdf -V
Asciidoctor PDF 1.6.2 using Asciidoctor 2.0.16 [https://asciidoctor.org/]

whereas on my macOS 11 I have:

$ asciidoctor-pdf -V
Asciidoctor PDF 2.3.7 using Asciidoctor 2.0.20 [https://asciidoctor.org]

We could change the CI to install a newer version of Asciidoctor PDF, if we think it makes a difference to the quality of the output.

quark17 commented 5 months ago

I spoke too soon. The version of asciidoctor-pdf being installed by the Ubuntu package manager was too old to have the theme we wanted. So I pushed a commit that updates asciidoctor-pdf in the GitHub CI job (by calling gem to install the latest version).

krame505 commented 4 months ago

Since the release has ended up being delayed somewhat, should it be named 2024.3 instead of 2024.1?

quark17 commented 4 months ago

Since the release has ended up being delayed somewhat, should it be named 2024.3 instead of 2024.1?

I can ask around, but our policy has been to not rename the two planned releases each year (YYYY.01 and YYYY.07) even if they are delayed.