Finished first draft revision of README

[IowaDave]

I think I've got here a complete draft to revise README. This draft supersedes one previously submitted on 8/2/22 as a PR and then withdrawn.

More work remains to do. I am not finished. I'm submitting this one as an interim work revising the previous content of README. Future work is intended to add new content rather than to revise previous content. And that will come later after I attend to some other things.

Please look at my discussion of RTC::now(). Invoking the function by its fully qualified name is what has worked for me. There is an example program, now(), that invokes it as a method of the DS3231 object. I just don't see the method being defined within the DS3231 object header. That's why I come at it through the fully qualified function name. Do I understand this bit correctly? What am I missing? Teach me, Obe Wuan.

Thanks, David

[IowaDave]

Note to reviewer/approver: Please consider using the "Squash and merge" alternative for merging this PR. The thing contains a bunch of trivial commits in my fork along the way to understanding how Markdown handles certain internal links. The NorthernWidget repo has no need for that history.

Thanks!

David

[IowaDave]

I pushed an edit to the name of the now() function. The correct fully qualified name is RTClib::now().

Please consider correcting the usage in the Example program named "now". The code in there invokes a "now()" member function of the DS3231 object, which returns a "no member function" error during compilation.

[IowaDave]

Hey guys, my PR is getting really large now that I started creating additional documentation files.

My concern is that it is becoming too large with too many different parts. I don't know how to do separate PRs for separate files, so I think I'll just stop work now and await further developments.

After this PR has been dealt with by the Powers That Be, one way or another, then I could see my way clear to resume work on more documentation.

Meanwhile, it's been a pleasure working with you. Thanks!

[awickert]

This documentation is a huge improvement over the nearly nonexistent docs we had before. I have not gone through and tested it exhaustively (sorry; no time!) but I don't see any reason to hold up its being published. If we notice issues later on, we can always fix them :)

Loads of thanks!

[awickert]

I could "squash and merge", but this will remove @IowaDave's credit for these updates. Since this is cited sometimes in the academic literature, having edit counts helps keep the author list correct and current.