Comments (4)
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.
from avrdude.
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 theavrdude.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.
from avrdude.
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).
from avrdude.
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.
from avrdude.
Related Issues (20)
- Parallel port silently not working HOT 9
- No way to set fuses for ATTiny 1626 / UPDI ? HOT 1
- Bootrow r/w does not work for `-c serialupdi` HOT 7
- Terminal erase command HOT 8
- JTAGICE3 EDBG communication mode relies on hardcoded USBVID HOT 7
- Unable to flash using Avrdude on a 14'' M1 Macbook Pro HOT 2
- JTAG2UPDI: avrdude error: cannot find programmer id jtag2updi HOT 3
- Correct part is not necessarily listed first when establishing connection HOT 7
- avr_opcodes.c: conflicting types for โop16_is_mnemoโ due to enum/integer mismatch HOT 1
- avrdude documentation typo(s) attemps HOT 1
- Unable to write LOCK bit byte to JTAG3_TPI HOT 3
- Does avrdude *have to* run as root in Linux for `-c xplainedmini_updi` (jtag3)? HOT 3
- Unexpected auto-erase consequences HOT 7
- `-E reset` and `-E noreset` support for the USBasp programmer
- Writing BOOTROW for Curiosity Nano HOT 3
- No programmers available
- winbond 25q64fv HOT 2
- AVR32 support HOT 4
- [MacOS] Avrdude built using autotools doesn't work HOT 10
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from avrdude.