Skip to content

Latest commit

 

History

History
124 lines (81 loc) · 5.61 KB

issues.adoc

File metadata and controls

124 lines (81 loc) · 5.61 KB
Raw

ℹ️ Issues

(TODO: move these to GitHub issues. This was a valiant effort at avoiding vendor lock-in)

Here’s a quick summary of the stuff I’m aware of and working on. IDs start with am to avoid conflicts with IDs that might be generated by some other issue tracker, should I choose one.

id description status details

am55

improve htmlproofer

OPEN

see below

am59

port book/build.sh to Windows

OPEN

am61

port mario/ansible/provision.sh to Windows

OPEN

am62

improve render of titled sidebars in macOS Books

OPEN

title box overlaps sidebar box in Books 3.1 with Gray and Night themes

am63

add auto-hyphenation

OPEN

see below

am64

add Cross references to print PDF

OPEN

see below

am65

fix sidebar deep links in EPUB

OPEN

see this patch

am66

improve Kindle compatibility

OPEN

see below

am67

improve book build: robust, secure

OPEN

see below, also see am59

ℹ️ am55: improve htmlproofer

book/.internal-build.sh runs htmlproofer, which returns some spurious failures. Currently I ignore these failures with an || true statement. It would be better to sqelch or fix them. This is possible by instrumenting links in the text or adjusting the way htmlproofer is configured and run.

Some recent output:

Running 3 checks (Images, Links, Scripts) in steadfast.html on *.html files ...


Checking 173 external links
Checking 94 internal links
Checking internal link hashes in 1 file
Ran on 1 file!


For the Links check, the following failures were found:

* At steadfast.html:6581:

  http://catb.org/jargon/html/G/Good-Thing.html is not an HTTPS link

For the Links > External check, the following failures were found:

* At steadfast.html:5354:

  External link https://github.com/wallabag/docker#upgrading failed: https://github.com/wallabag/docker exists, but the hash 'upgrading' does not (status code 200)

* At steadfast.html:5713:

  External link https://matrix.to/#/#selfhosted:matrix.org failed: https://matrix.to/ exists, but the hash '/#selfhosted:matrix.org' does not (status code 200)

* At steadfast.html:5988:

  External link https://github.com/strukturag/nextcloud-spreed-signaling#running-with-docker failed: https://github.com/strukturag/nextcloud-spreed-signaling exists, but the hash 'running-with-docker' does not (status code 200)


HTML-Proofer found 4 failures!

ℹ️ am63: add auto-hyphenation

I want full justification in the printed book, and I want words reasonably hyphenated. Asciidoctor-PDF can do this! Just add the text-hyphen gem and enable it in the theme. Here’s an example.

Unfortunately for me, URLs and inline code spans are also hyphenated.

See this chat thread and this patch (merged on May 26, 2024).

ℹ️ am64: add Cross references to print PDF

Ideally I’d like a full set of lists of cross-referenced blocks of significant/titled content like figures, tables, sidebars, and listings (code snippets) in the Cross references chapter. This currently relies on the asciidoctor-lists extension.

The print PDF omits the entire Cross references chapter because page numbers are not rendered. See: Alwinator/asciidoctor-lists#14

Links in EPUB output break for anything without an explicit ID—​something about the UUIDs auto-generated by asciidoctor-lists confuses the EPUB3 backend. Otherwise I’d only need explicit IDs for special cases. See: Alwinator/asciidoctor-lists#25

ℹ️ am66: improve Kindle compatibility

The EPUB loads on Kindle devices, but there are a few issues:

  • smooshed SVG: WAN into LAN traffic flow diagram

  • cross-references to sidebars are dead links (not clickable / touchable)

  • no text visible in Pi-hole DNS traffic flow diagram

I don’t use Kindle apps or devices; I’ve only seen these via the Kindle Previewer.

Perhaps related, KDP says a KPF created from Kindle Previewer contains only images, is not reflowable, and fixed format is required.

See "EPUB" → "Kindle" in Readme.adoc for all book format quality rankings.

ℹ️ am67: more resilient, secure book build

sudo book/build.sh fails on Linux at addgroup failure - The group root already exists. This is documented in book/Readme.md but is still annoying and unnecessary.

Even as non-root, building the books appears to fail on Ubuntu 22.04 LTS unless the docker-buildx package is installed.

The main thing making book/build.sh brittle is that it’s trying to be more secure by matching the non-root host user with an in-container non-root user. Does this appreciably help security? I don’t know. If it doesn’t, we should just collapse book/.Dockerfile and book/.Dockerfile.insecure, use root, and simplify book/build.sh.

We should also explore/recommend rootless Docker and user namespaces when we seek to improve book/build.sh.