avrdude documentation improvement

[mcuee]

https://avrdudes.github.io/avrdude/7.3/avrdude.html

Some of the information are a bit outdated.

1. Windows installation -- maybe we want to point to the Wiki. We do not really recommend using Cygwin. We do not really support MinGW.org now (website down) but rather MSYS2 mingw project.
   https://avrdudes.github.io/avrdude/7.3/avrdude_34.html#Windows-Installation

2. Windows Configuration File Location -- I guess we can forget about 16bit Windows NT now. avrdude only works under Windows 7 and later.
   https://avrdudes.github.io/avrdude/7.3/avrdude_37.html#Windows-Configuration-File-Location

3. Windows port name -- no more parallel port support.
   https://avrdudes.github.io/avrdude/7.3/avrdude_39.html#Serial-Ports --> not so sure we want to mention libserialport improvement (only for MinGW build).
   https://avrdudes.github.io/avrdude/7.3/avrdude_40.html#Parallel-Ports

4. We need to remove Windows Parallel Port info here as well.
   https://avrdudes.github.io/avrdude/7.3/avrdude_4.html#Option-Descriptions

[mcuee]

Status: Done. PR #1689 merged.

---

I think some of the info below about serialupdi needs updates as well.
https://avrdudes.github.io/avrdude/7.3/avrdude_21.html#SerialUPDI-Programmer

@dbuchwald
Would you be able to help here? Thanks.

[mcuee]

• Documentation current avrdude limitations in pdf/html documentation #1672

More documentation update

• avrdude 7.3 release discussion #1473 (comment)

From @stefanrueger

I still think it would be wonderful if we had a short section in the .pdf/.html documentation about (current) limitations.

I have documented the knows limitations here and I just did some updates to list down the issues I know of.
https://github.com/avrdudes/avrdude/wiki/Known-limitations-of-avrdude

FAQ page may need some updates.
https://github.com/avrdudes/avrdude/wiki/FAQ

[dbuchwald]

Sorry, took me a while, but you can find updates to SerialUPDI documentation in PR #1689

[mcuee]

Sorry, took me a while, but you can find updates to SerialUPDI documentation in PR #1689

You are very fast already. Thanks.
PR #1689 looks good to me.

• Updated section about NVM models support #1689

[mcuee]

I think some of the info below about serialupdi needs updates as well. https://avrdudes.github.io/avrdude/7.3/avrdude_21.html#SerialUPDI-Programmer

@dbuchwald Would you be able to help here? Thanks.

Done. PR #1689 has been merged.

[mcuee]

@stefanrueger @ndim @dl8dtl @MCUdude

My suggestion is totally remove Section A from the documentation as it does not provide much value to the user. Windows section is completely outdated as well.

https://avrdudes.github.io/avrdude/7.3/avrdude_23.html#Platform-Dependent-Information

[stefanrueger]

totally remove Section A

Hugely controversial b/c I just spend a couple of hours the other day to add info in USB permissions 😄. Check out the current live documentation. But yes, I agree to remove outdated or wrong information. Only problem: I don't know what is. But you do @mcuee and could help?

[stefanrueger]

Windows section is completely outdated as well

I disagree. The location of configuration files, eg, should be correct. And how should a user know where their avrdude.rc goes?

[mcuee]

Windows section is completely outdated as well

I disagree. The location of configuration files, eg, should be correct. And how should a user know where their avrdude.rc goes?

Good point. We can keep this one and remove others Windows related info.

Sorry but no, I can not help to create the PR myself. I do not know anything and I will refuse to learn anything about Tex.

[ndim]

The two things texinfo and TeX have in common is they both are decades old and they both use the letters tex. But point taken, texinfo is not a nice thing to handle.

[mcuee]

The two things texinfo and TeX have in common is they both are decades old and they both use the letters tex. But point taken, texinfo is not a nice thing to handle.

Thanks for the correction. Somehow I mixed the two. Tex was huge last time I played Linux on a 486 machine back in 1998 so the first thing was to remove it.

Somehow we need to install Tex in order to build avrdude documentation. You can see we need the following three packages installed under Linux to build avrdude documentation.

https://github.com/avrdudes/avrdude/blob/main/.github/workflows/build.yml
texinfo
texlive
texi2html

[mcuee]

For the Unix section, at least the section on Installation needs to be updated now that we support CMake. But I tend to think it is a good idea to remove the installation section.
https://avrdudes.github.io/avrdude/7.3/avrdude_25.html#Unix-Installation

[mcuee]

Windows section is completely outdated as well

I disagree. The location of configuration files, eg, should be correct. And how should a user know where their avrdude.rc goes?

@stefanrueger
It is already in the main section. So better remove as well.
https://avrdudes.github.io/avrdude/7.3/avrdude_10.html#Configuration-Files

[stefanrueger]

@mcuee Happy to remove the installation section. I still would like a link with info how to install. What's my best best?
BTW, the project needs the info what's outdated and what to replace it with. Seeing that you know way more about the platform-dependent issues that everyone else on the team, it would be great if you could contribute that info. Once the info is there it's relatively easy to drop that into the documentation.

[mcuee]

@mcuee Happy to remove the installation section. I still would like a link with info how to install. What's my best best? BTW, the project needs the info what's outdated and what to replace it with. Seeing that you know way more about the platform-dependent issues that everyone else on the team, it would be great if you could contribute that info. Once the info is there it's relatively easy to drop that into the documentation.

Let me work on the changes to the Appendix over the weekend.

[mcuee]

Ideas of changes to Appendix A using the latest pdf as the reference.
https://github.com/avrdudes/avrdude/blob/main/avrdude.pdf

A.1.1 --> A.1.1 Unix Installation

• To remove

A.1.2 --> A.1.2 Unix Configuration Files
Will need to keep as it is referenced from Ch 4 "4 Configuration Files".

• To add macOS Homebrew and macPorts.
• To add OpenBSD and NetBSD

A.1.3 Unix Port Names

• To mention Parallel port is not supported by macOS
• To mention that the user may need to check the USB serial port name
• To mention that libserialport enabled installation has alternatives to mention the port name.

A.1.4 Unix USB Permissions

• To add a reference for macOS, USB HID device needs to use HIDAPI and not libusb. When using libusb, need to have no kernel driver attached to the USB interface of interests.
• To add information for OpenBSD and NetBSD if I can find a good reference.

A.1.5 Unix Documentation

• No changes needed.

[mcuee]

Ideas of changes to Appendix A using the latest pdf as the reference.
https://github.com/avrdudes/avrdude/blob/main/avrdude.pdf

A.2.1 Installation

• To remove.

A.2.2 Windows Configuration Files

• To keep.

A.2.3 Windows Port Names

• To include the alternative way to name a serial port if libserialport is used.
• To mention that Parallel port is not supported
• For USB HID device, HIDAPI needs to be used. PICkit 2 is an exception which uses native Windows API.
• For USB device, libusb-win32 or libusb-compat-0.1 or libusb or avrdude-libusb need to be used. Mention the prefer driver is WinUSB even though libusb0.sys or libusbK.sys should work as well.

[mcuee]

Further improvements for Appendix A.

Need to see if we can incorporate some of the info from here. Maybe post avrdude-8.0 release because of time constraints.
https://github.com/avrdudes/avrdude/wiki/Known-limitations-of-avrdude

[stefanrueger]

Thanks @mcuee of breaking this down in smaller tasks

To add macOS Homebrew and macPorts.
To add OpenBSD and NetBSD

If this is going to happen the project needs the text of what to add!

[stefanrueger]

Same with all the other points. I won't be able to provide the text that is needed.

[stefanrueger]

Have rerun the boxed examples in the documentation and put the new look and feel to work.

@mcuee I have replaced the Installation sections with a reference to the wiki. For the rest I need text.

[mcuee]

I will see what I can do over the weekend. Still recovering from Covid-19.

[mcuee]

@stefanrueger

I looked at the current avrdude.pdf, I think it is quite an improvement over the 7.3 release version. Thanks.

I will suggest a few changes below.

Two must-have changes for Windows.

1. Remove Section A.2.3.2 Windows Parallel Ports will do. Or we can keep the section and say that Parallel Ports are not suppoted by avrdude under Windows.

2. Remove item 5 of Section A.2.2.2 (no more 16bit Windows subsytem.

A.2.2.2 Windows Configuration File Location
AVRDUDE on Windows has a different way of searching for the system and user configuration
files. Below is the search method for locating the configuration files:
1. Only for the system configuration file: <directory from which application
loaded>/../etc/avrdude.conf
2. The directory from which the application loaded.
3. The current directory.
4. The Windows system directory. On Windows NT, the name of this directory is SYSTEM32.
<del> 5. Windows NT: The 16-bit Windows system directory. The name of this directory is SYSTEM. </del>
6. The Windows directory.
7. The directories that are listed in the PATH environment variable.

[mcuee]

@stefanrueger

Optional changes.

1. Add a note in Section A.1.3 Unix Port Names saying that Please take note that parallel port is not supported by macOS.

[mcuee]

@stefanrueger

For Appendix B, I'd like to suggest the changes for the first sentence.

In general, please report any bugs encountered via
https://github.com/avrdudes/avrdude/issues.

-->

In general, please report any bugs encountered via
https://github.com/avrdudes/avrdude/issues.

Please also consult the Wiki to learn more about avrdude.
https://github.com/avrdudes/avrdude/wiki

In paticular the FAQ and  the known limitation of avrdude are worth reading.
https://github.com/avrdudes/avrdude/wiki/FAQ
https://github.com/avrdudes/avrdude/wiki/Known-limitations-of-avrdude

[mcuee]

@stefanrueger

I looked at the current avrdude.pdf, I think it is quite an improvement over the 7.3 release version. Thanks.

I will suggest a few changes below.

Two must-have changes for Windows.

1. Remove Section A.2.3.2 Windows Parallel Ports will do. Or we can keep the section and say that Parallel Ports are not suppoted by avrdude under Windows.
2. Remove item 5 of Section A.2.2.2 (no more 16bit Windows subsytem.

A.2.2.2 Windows Configuration File Location
AVRDUDE on Windows has a different way of searching for the system and user configuration
files. Below is the search method for locating the configuration files:
1. Only for the system configuration file: <directory from which application
loaded>/../etc/avrdude.conf
2. The directory from which the application loaded.
3. The current directory.
4. The Windows system directory. On Windows NT, the name of this directory is SYSTEM32.
<del> 5. Windows NT: The 16-bit Windows system directory. The name of this directory is SYSTEM. </del>
6. The Windows directory.
7. The directories that are listed in the PATH environment variable.

@stefanrueger

I take the liberty to commit two changes to git main for the above changes.

Also removed another places where Windows parallel ports are mentioned.

[stefanrueger]

Thanks, very helpful.

[mcuee]

@stefanrueger and @MCUdude

Two minor updates for macOS in PR#1902. Please review. Thanks.

• Document: use macOS to replace MacOS, no support of Parallel Port under macOS #1902

[mcuee]

@stefanrueger

For Appendix B, I'd like to suggest the changes for the first sentence.

In general, please report any bugs encountered via
https://github.com/avrdudes/avrdude/issues.

-->

In general, please report any bugs encountered via
https://github.com/avrdudes/avrdude/issues.

Please also consult the Wiki to learn more about avrdude.
https://github.com/avrdudes/avrdude/wiki

In paticular the FAQ and  the known limitation of avrdude are worth reading.
https://github.com/avrdudes/avrdude/wiki/FAQ
https://github.com/avrdudes/avrdude/wiki/Known-limitations-of-avrdude

@stefanrueger

Please help here. You can modify the text as you see fit. I do not know how to add the URLs properly. Thanks.

[mcuee]

I think we have done the improvements.

[stefanrueger]

I think we have done the improvements.

Looks like this and that is not fully addressed.

It sounds like it should be, but I for one don't know how and no one else has been chipping in. For example

• "the user may need to check the USB serial port name" is insufficient info for me to put in a manual. I really don't know what that means. Is that a graphic user interface with a box they check? Do they need to investigate something?
• "libserialport enabled installation has alternatives to mention the port name". I can write something to the effect of If AVRDUDE was compiled with the @code{libserialport} library ports will also have alternative names that are derived form the used USB to serial chip, e.g., XYZ but I am missing a crucial example here that was taken from a real Windows system.
• " USB HID device needs to use HIDAPI and not libusb": Is that advice to the user to recompile? How would they know which device is USB HID? Which errors would they see?
• "When using libusb, need to have no kernel driver attached to the USB interface of interests." Remember this is a user manual. How would they know which library avrdude uses? How would they see a problem? Which commands would they issue to figure out kernel drivers being attached? Etc

I am not trying to be difficult. I simply don't know and think someone who does should give it a go.

Reflecting on above, some could go into the Troubleshooting session, and some into the wiki for how to compile.