Use correct file locations in the documentation

[ndim]

The avrdude documentation (avrdude.1 man page, avrdude.info page, html+pdf docs) contains references to file locations.

Some of those file locations have changed over time without the documentation completely reflecting those changes, and this PR wants to fix that.

[stefanrueger]

@ndim Thanks for looking carefully through the source and matching that with the documentation. Do you want to further progress this PR? I'd be happy to merge this in its current state.

[ndim]

At this time, this only fixes a single place. That one commit does not depend on anything and can therefore be cherry-picked or merged immediately for 7.3.

There is still the main 95% of the work to be done, and I do plan on doing that work, but that will take me several weeks at the minimum, aiming for the next release after 7.3.

[ndim]

The texinfo documentation documents avrdude, and does so for two different audiences:

• The texinfo documentation describes avrdude to the general public, so people can read up on avrdude with or without having it installed. That documentation should be general, describing avrdude on BSDs, Linuxes, OSX, Windows. That means many OS specific file locations, so a more general description might be helpful.

• The texinfo documentation describes avrdude to the person using avrdude on a specific machine. If that documentation (think "info avrdude" info page) containing the specific file location for this specific avrdude installation would be helpful.

  Having the file locations from the general documentation is still OK for the installation specific documentation, but the installation specific file location from the system which builds the general documentation should be left out.

So a lot of preprocessing and changing the documentation source is needed. So much work, so little time.

[ndim]

Side note: if something is difficult to document, perhaps that thing is too difficult and could be simplified.

[stefanrueger]

Yes, there is a tension between documenting exactly what's the case on a particular installation, but we as AVRDUDE maintainers cannot know where a distro/user puts the files and how they build AVRDUDE. So out of necessity we cannot do much more than handwaving and giving a few general hints...

I personally would suggest giving up on this and only correct factual errors in our docu.

[ndim]

We can definitely put @docdir@/avrdude.pdf inside the texinfo source instead of /usr/local/share/doc/avrdude/avrdude.pdf and then have the doc build process substitute whatever docdir is in use.

However, I agree that this is too much effort to put in at this time to solve this in a general way.

I came to this because I foolishly put the avrdude.conf into a different place in the Fedora avrdude package a LONG time ago, and therefore I have needed to adapt the avrdude documentation (which is shipped as part of the avrdude package) to point to another location ever since. Well, I have to continue to suffer for my own mistake.

Anyway, for here right now... that one commit in this PR changes /usr/doc to /usr/share/doc, a change which happened on GNU/Linux 10 to 20 years ago, and applies to Linux and BSD today, and is not installation dependent.

Merge and close, please?

[stefanrueger]

Thanks, will merge at next mergefest.

[stefanrueger]

avrdude.conf into a different place in the Fedora avrdude package

@ndim Have you considered a PR that details where avrdude.conf can be found on Fedora? Currently A.1.2.2 Linux Configuration Files claims it will always be /etc/avrdude.conf. We might want to weaken that strong claim by saying will normally be ... but distributions might have chosen a different place. For example, Fedora ... That would also be a good opportunity to replace from an rpm package with from packages or similar.

This would document where it is in Fedora, remove the necessity to create a Fedora-specific docu, and best of all, remove the risk that the Fedora-specific docu finds its way online where the Fedora context would no longer hold.

[ndim]

I am patching the avrdude docs which become part of the Fedora package, so I am fine with the docs as they are.

I have considered an issue or PR generally about where avrdude.conf is installed and where it is being looked for. I think that avrdude.conf should be installed to /usr/lib/avrdude/avrdude.conf, and avrdude/libavrdude should look for avrdude.conf first in /etc/avrdude.conf and use that if it exists, then try /usr/lib/avrdude/avrdude.conf. Rationale: The avrdude code warns if the version number for the avrdude executable and the avrdude.conf config file differ, so avrdude.conf is a bit more like an internal resource file than a config file e.g. /etc/sudoers which is expected to not change significantly with updates of the sudo package. I even have some code for that, but that still needs a bit of work.

[stefanrueger]

The avrdude code warns if the version number for the avrdude executable and the avrdude.conf config file differ,

We've introduced that b/c a number of issues were raised that simply came about by using .conf files that were ahead of the avrdude version or by using massively outdated .conf files...