search

AgentD / squashfs-tools-ng

A new set of tools and libraries for working with SquashFS images
Other
194 stars 30 forks source link

Convert format.txt to asciidoc #88

Closed Dr-Emann closed 2 years ago

Dr-Emann commented 2 years ago

I've given a first pass at translating the format.txt into asciidoc format. I wanted to be able to read the format documentation on my e-reader, but the raw txt was pretty hard to read and navigate.

I played around with markdown, LaTeX, and asciidoc (having only used markdown before). LaTeX made beautiful PDFs, but html output seemed lacking, and it looked the least like plain text. Markdown was familiar, but lacked some of the features for e.g. tables, the toc, etc. Asciidoc seemed like a good mix: It mostly looks like plain text, but had some more powerful features like automatic table of contents, and mostly reasonable nested tables. And the default asciidoctor html theme doesn't look bad.

Rendered Output Raw Also github does an okay job at rendering it directly without converting to html

I'm not sure if this is a route you'd be interested in, but since I made it, I thought I'd offer it up in case you want it. If you're not, I'd probably do my best to keep it up to date with the format.txt anyway (it already includes the extra info about the "file size" of directories being offset by 3).

Dr-Emann commented 2 years ago

Also, in doing so, I found a questionable reference: In the File Inodes section, the block offset and block sizes fields reference "section 3". Section 3 is "The superblock", and it's not clear to me how the two are related. I'm thinking this is a case of things moving around, and references not getting updated?

AgentD commented 2 years ago

Hi,

thanks for taking the effort! I originally thought about doing a LaTeX version as well, but eventually gave up on that. While I am a fan of RFC style plain ascii text, the websites generated from the asciidoc do look quite impressive. If you open a pull request for that, I would gladly merge it.

I also fixed the back reference. It should be section 4, which outlines the data block layout. The error certainly resulted from shifting around the sections while drafting the document. I fixied that for now in commit 08067c6fe2a57c8746508e8eace189b0f99126ee.