docs: add comprehensive documentation and examples

[simon-pfahler]

This PR adds large parts of the documentation, and adds more example documents for seeing the package in use.

• Tex documentation added to docs/cvd.tex
• HTML documentation extended by chapters about getting-started, usage, commands, images, limitations, examples and theory.
• Example files created in examples/
• Add Simon Pfahler as co-author

[jolars]

Great! Thanks a lot for fleshing out all of the docs, very nice! Mostly nits on my side, except for the blanklines before lists, which are necessary in Pandoc. (Quarto runs the website generator through Pandoc.)

There is also one thing that I have not documented or told you carefully about, so this is my fault, and it's that the manual is actually generated directly from the markdown sources, so there shouldn't even be a cvd.tex document. The manual is built from task build-manual (which had a buggy line, I'm pushing a fix directly), and then used directly in the ctan upload step, so it bypasses the cvd.tex file entirely. But this my fault, you can just leave it, and I'll fix it after we merge. The manual is built entirely from the md source. The reason for this is to have the website and the manual match each other one-to-one, but it might be debatable in our case because we might want to show off the actual package functionality in the package, but... well, what do you think?

I pushed a couple of fixes directly to the repo, but left most as comments or suggestions.

[jolars]

Is quote the right environment for this? We shouldn't just use verbatim (or even use minted instead?).

[jolars]

Not a blocker btw, maybe just revisit later.

[simon-pfahler]

Good catch. A verbatim environment is the cleanest solution I think. Is this how you wanted it to be solved?

[jolars]

I've fixed the CI failure on main, btw, so you can rebase if you'd like the checks to pass.

[simon-pfahler]

Thanks for the feedback, I tried to update everything accordingly.

I do not think that it is necessary to have the online documentation match the pdf one exactly. I would keep them as different documents, with the pdf documentation being oriented towards users, while the online one goes into more technical details.
But I do not have a strong opinion on this, if you prefer them matching exactly, that's also fine by me. The important thing to me is just that users get a good usage guide when they type texdoc cvd in their terminal.

The CI failure seems like it is due to me using the new \DocumentMetadata and a version of TeXLive that is too old. I would urge us to use this, as it adds accessibility tags to the document, which makes the PDF more compatible with screen readers.

[simon-pfahler]

Good catch. A verbatim environment is the cleanest solution I think. Is this how you wanted it to be solved?

[jolars]

Thanks for the feedback, I tried to update everything accordingly.

I do not think that it is necessary to have the online documentation match the pdf one exactly. I would keep them as different documents, with the pdf documentation being oriented towards users, while the online one goes into more technical details. But I do not have a strong opinion on this, if you prefer them matching exactly, that's also fine by me. The important thing to me is just that users get a good usage guide when they type texdoc cvd in their terminal.

Hm, I don't mind having some tex-only documentation, but I very much would like the user guide to be on both the web and in latex. Personally, I find web docs much easier to search and they are also generally just better for accessibility (responsive, high-contrast options, font sizes, etc). And I also want to avoid duplication, having to maintain the same information in two places. I agree that texdoc cvd should just work (but it will even if we run it through the same pipeline.)

What we could instead do is to simply have an additional tex document that shows the package in-action in the current documentation, which we can't do for the HTML docs in any reasonable way.

The CI failure seems like it is due to me using the new \DocumentMetadata and a version of TeXLive that is too old. I would urge us to use this, as it adds accessibility tags to the document, which makes the PDF more compatible with screen readers.

Ah, I see. Yes, I'll see what I can do. I'm building the docs through devenv/nix, but updating might just solve this directly in case texlive 2026 has been included there yet.

[simon-pfahler]

Both your accessibility and your duplication points are very good, so I would just say let's remove the cvd.tex file altogether (if I understood correctly, the CI builds a PDF documentation from the HTML version anyways?).
Will the "implementation documentation" from cvd.dtx be in the PDF documentation automatically? I would favor it being in there, but it's not a big deal if it isn't.

What we could instead do is to simply have an additional tex document that shows the package in-action in the current documentation, which we can't do for the HTML docs in any reasonable way.

I think that's what the examples/ folder is there for, so I don't think we need to add another document showing the package in action.

Ah, I see. Yes, I'll see what I can do. I'm building the docs through devenv/nix, but updating might just solve this directly in case texlive 2026 has been included there yet.

Perfect, thank! What I don't quite understand right now is if this is still relevant if we remove cvd.tex altogether. We do want a PDF documentation, and it will probably compiled by LaTeX (?), so that document should still be compiled using the new tagging support.

[jolars]

Yup, this is what it looks like right now:

cvd.pdf

So it's basically everything that you see in the web docs (including implementation docs).

[jolars]

I think that's what the examples/ folder is there for, so I don't think we need to add another document showing the package in action.

Well, I guess... Yes, as long as it shows up on CTAN I think that's fine.

Perfect, thank! What I don't quite understand right now is if this is still relevant if we remove cvd.tex altogether. We do want a PDF documentation, and it will probably compiled by LaTeX (?), so that document should still be compiled using the new tagging support.

If it's in the default Quarto/Pandoc template, it will. But we can also modify the latex template used directly if it's not there at the moment.

[simon-pfahler]

If it's in the default Quarto/Pandoc template, it will. But we can also modify the latex template used directly if it's not there at the moment.

I briefly looked into this, and set the necessary options in docs/_quarto.yml. It should now produce a tagged PDF if my changes were correct.

[jolars]

sorry for taking so long to merge!

[jolars]

The failure was just related to a missing tagpdf package in the devenv file. So it's solved now!