Auto-build avrdude.pdf from texinfo sources

[ndim]

Originally posted by @stefanrueger in #1842 (comment) but I am creating a new issue as this is very much unrelated to that issue. The following words are from @stefanrueger, not mine.

It occurred to me that the avrdude.pdf documentation is installed somewhere on the user's destination system, but (as far as I am aware!) it isn't available in the avrdude repository for reference.

So, when discussing issues it is not possible for us maintainers to refer to the documentation of the current git-main avrdude other than saying something like "Find out where avrdude.pdf is installed on your system and look at Section 3.2"... This is bizarre.

What would be a good way to keep a current avrdude.pdf document (ideally created automatically when commits/merges happen to git main) in the repository? Ideally this would reside in a top-level directory such as documentation. Thoughts? @ndim @mcuee @dl8dtl @MCUdude

[stefanrueger]

To clarify: I realise that the documentation for releases resides in https://avrdudes.github.io/avrdude/. What I'm after is a current avrdude.pdf somewhere in the repository.

[ndim]

The avrdude manual is written in Texinfo. The info command for Texinfo replaced man pages with hypertext, in a time when neither HTML nor PDF had been invented yet. Since then, conversions to a number of output formats have been added: The original info files for the info command, a PDF file, one HTML file or a set of HTML files, a Postscript file, etc.

There are a few ways to put a generated avrdude.pdf alongside its texinfo source files inside the avrdude git repo, but none is nice.

• Locally regenerate avrdude.pdf whenever the texinfo sources have changed, and include avrdude.pdf changes into every commit which changes the texinfo sources. This can be done with git hooks on the local side, and with server side enforce consistency checks.

  However, e.g. checking that the avrdude.pdf file in the repo is actually the same one which a CI run generates is non-trivial. As soon as some parts of the build tool chains differs between Github workflow runners and the developer's local machine, the bits in the resulting PDF will differ, even if the human visible content will not.

  Reviewing diffs for such commits becomes also a bit more difficult ("binary files differ" does not help much to see what happens inside a PDF file), and the real nightmares start when merging diverged binary files like avrdude.pdf.

• The CI could rebuild avrdude.pdf after every commit which changes the texinfo sources, add a new "Update avrdude.pdf" commit which updates the avrdude.pdf in the avrdude git repo.

  That would mean every time you push such changes, you need to pull again to get the proper state. Such a "Update avrdude.pdf" commit could come dozens of commits after the commit which actually changes the texinfo sources.

  This would require giving the CI write access to the repo.

• The CI could rebuild avrdude.pdf and put it somewhere other than the avrdude git repo for every push to the avrdude git repo.

  The problem now becomes finding that PDF. A small sh script in the avrdude git repo which determines the latest git hash and generates a URL pointing to the corresponding PDF file could help.

Generating a set of HTML pages or a single HTML page version of the info page to replace the PDF version avrdude.pdf could help with some of the problems: No binary diffs to see, no binary diffs to merge. There would still be the issues of different tool versions producing same-but-technically-different outputs.

There is simply no good solution in sight when compiling doc sources into another format and insisting on keeping the result in the same place.

Switching the doc sources to a format with better readability like e.g. markdown could help here. Markdown would give people something which can be easily read and written in any text editor. However, that would mean we lose the info page which is quite convenient on systems which have the info program. I have also not checked how much work that conversion would be, and about other cross-dependencies (where the avrdude info uses special texinfo features, or other texinfo documentation uses avrdude.info). Markdown can still be compiled to PDF and/or HTML, just by using a different toolchain.

[ndim]

And in the mean time, do we really still need to build POSTSCRIPT output avrdude.ps? Is there anybody still using postscript in 2024?

I would like to just build PDF and HTML (and info for systems where that makes sense).

[stefanrueger]

Thanks for the detailed analysis, @ndim. Wow, complete automation sounds difficult with distinct disadvantages...

I was wondering whether a semi-automated mechanism would help. What is involved in having make/cmake/automake update somewhere in the repo with a certain switch (or whenever cmake runs and the sources have changed)? That file could be in .gitignore, so not "seen" when using git. I could imagine using a little shell script that copies that most recent avrdude.pdf version to the repo's /documentation/avrdude.pdf (which would be part of the repo) and committing that version together with NEWS everytime I update NEWS at the end of a mergefest. That way, we'd have a periodically updated documentation of git main.

And yes, I am not aware of anyone using avrdude.ps (I wasn't aware it is produced either). So as far as I am concerned PDF and HTML is just what's needed.