Documentation Issues

[inexorabletash]

This is an issue for collecting problems noted in documentation, including:

• https://a2desktop.com
• README files included in packages
• markdown or text files in the repo

Instead of filing a separate bug, please add comments here. Make the comments as short as possible.

[c0mmander8]

Apple II DeskTop documentation, located at https://www.a2desktop.com/docs, fixes:

Under "Getting Started", under "Compatibility":

"Apple II DeskTop requires an Apple II, compatible, or emulator with at least 128k of RAM and Double-HiRes graphics support." should instead be
"Apple II DeskTop requires an Apple II, compatible, or emulator with at least 128k of RAM and double hi-res graphics support.", with the words "double hi-res" replacing the word "Double-HiRes" in the sentence because that is how "double hi-res" is properly spelled.

"DeskTop uses the double-hires display mode." should instead be
"DeskTop uses the double hi-res display mode.", with the words "double hi-res" replacing the word "double-hires" in the sentence because that is how "double hi-res" is properly spelled.

"The Laser 128 line of computers has a MONO/COLOR switch above the keyboard." should instead be
"The Laser 128 line of computers have a MONO/COLOR switch above the keyboard.", with the word "have" replacing the word "has" in the sentence because "The Laser 128 line of computers" is plural.

Under "Using the DeskTop", under "Working With Disks":

"5.25" floppy icon for 140k disks in Disk II drives" should instead be
"5.25" floppy icon for 140k disks", with the words "in Disk II drives" deleted from the sentence because 140K disks are shown with the 5.25-inch floppy icon regardless of the type of drive used since issue #437 was implemented.

Under "Using the DeskTop", under "Working With Files", under "Folder — DIR":

"ℹ️ NOTE: To automatically close the parent window, hold down ▲ while double-clicking or selecting File > Open." should instead be
"ℹ️ NOTE: To automatically close the parent window, hold down ▲ while double-clicking a folder or hold down △ or ▲ while selecting File > Open.", with the words "a folder or hold down △ or ▲ while" replacing the word "or" in the sentence because either the Open Apple key or the Solid Apple key can be held down to automatically close the parent window when selecting File > Open from the File menu.

Under "Using the DeskTop", under "Working With Files", under "Graphics — FOT/$08, or certain BIN files:":

"BIN files with aux type $2000 or $4000 taking up 17 blocks (Hires) or 33 blocks (Double-Hires)" should instead be
"BIN files with aux type $2000 or $4000 taking up 17 blocks (hi-res) or 33 blocks (double hi-res)", with the word "(hi-res)" replacing the word "(Hires)" and with the words "(double hi-res)" replacing the word "(Double-Hires)" in the sentence because that is how "hi-res" and "double hi-res" are properly spelled.

Under "Using the DeskTop", under "Working With Files", under "BASIC programs — BAS":

"To return to DeskTop, type BYE at the BASIC prompt." should instead be
"To return to DeskTop, type bye or type BYE at the BASIC prompt.", with the words "type bye or" being added to the sentence because either "bye" or "BYE" can be used to dismiss the BASIC prompt and return back to Apple II DeskTop, even on an unenhanced Apple IIe.

Under "Using the DeskTop", under "Moving, Copying, and Deleting Files":

"Drag a volume icon onto a folder or volume icon to copy the contents of the source volume into the destination." should be updated to reference the fact that you can also drag a source volume icon onto a destination window in order to copy the contents of the source volume into the destination window.

[c0mmander8]

Apple II DeskTop "About", located at https://www.a2desktop.com/about, fixes:

"Apple (or compatible) with 128k and Double Hi-Res graphics: Apple IIe, IIc, IIc Plus, IIgs, IIe Option Card for Mac, Laser 128, or Franklin ACE 2X00/500." should instead be
"Apple (or compatible) with 128k and double hi-res graphics: Apple IIe, IIc, IIc Plus, IIgs, IIe Option Card for Mac, Laser 128, or Franklin ACE 2X00/500.", with the words "double hi-res" replacing the words "Double Hi-Res" in the sentence because that is how "double hi-res" is properly capitalized.

[c0mmander8]

Apple II DeskTop "History", located at https://www.a2desktop.com/history, fixes:

"The application was developed using the MouseGraphics ToolKit by Apple, which provided the graphics primitives for drawing shapes and text to the complex double-hires graphics screen, and the windowing primitives such as events, cursors, menus, windows, scrollbars and mouse support." should instead be
"The application was developed using the MouseGraphics ToolKit by Apple, which provided the graphics primitives for drawing shapes and text to the complex double hi-res graphics screen, and the windowing primitives such as events, cursors, menus, windows, scrollbars and mouse support.", with the words "double hi-res" replacing the word "double-hires" in the sentence because that is how "double hi-res" is properly spelled.

[c0mmander8]

Additional Apple II DeskTop documentation, located at https://www.a2desktop.com/docs, fixes:

Under "Troubleshooting", under "The screen has color fringes everywhere and text is difficult to read.":

"Apple II DeskTop uses monochrome double-hires graphics." should instead be
"Apple II DeskTop uses monochrome double hi-res graphics.", with the words "double hi-res" replacing the word "double-hires" in the sentence because that is how "double hi-res" is properly spelled.

[inexorabletash]

Above updates applied, except in cases where optional alternatives (e.g. "BYE or bye") are simply excessive and make the instructions harder to understand.

[c0mmander8]

a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes:

Under "General Enhancements":

"* Mouse Keys mode simplified: (#185)

• OA+SA+Space to enter Mouse Keys mode. A sound will play.
• SA acts as mouse button.
• Escape to exit Mouse Keys mode. A sound will play." should instead be

"* Mouse Keys mode simplified: (#185)

• Open-Apple+Solid-Apple+Space to enter Mouse Keys mode. A sound will play.
• Solid-Apple acts as mouse button.
• Esc to exit Mouse Keys mode. A sound will play." for greater clarity and in order to match the style of all of the other keyboard shortcut entries in the release notes.

Under "DeskTop Enhancements":

Please reduce the amount of empty space between the different entries under "DeskTop Enhancements" in order to match the amount of empty space between the different entries throughout the rest of the release notes.

"* New file type icons: graphics, IIgs-specific, AppleWorks, relocatable, command, fonts, music, and DAs. (#105, #116)" should instead be
"* New file type icons: graphics, IIgs-specific, AppleWorks, relocatable, command, fonts, DAs, music, and archives. (#105, #116)" with the words "DAs, music, and archives." replacing the words "music, and DAs." because support for archives has been added to Apple II DeskTop and I prefer that "DAs, music, and archives." be listed in that order because that way all of the icons that appear in issue #105 are listed first, in the order that they appear in the comments in issue #105, then DAs, which appear in issue #116, are listed and finally music and archives which were added later and appear in no issue are listed last.

"* Icons for volumes positioned more predictably and sensibly. (#94, #375, #540)" should instead be
"* Icons for volumes positioned more predictably and sensibly. (#94, #375, #468, #540, #658, #663)" because issue #468, issue #658 and issue #663 also relate to this entry.

"* Show appropriate error when copying a file onto itself. (#630)

• Show appropriate error when trying to replace an item with itself or an item it contains. (#634, #635, #636)" should instead be

"* Show appropriate error when trying to replace an item with itself or an item it contains. (#630, #634, #635, #636)" to consolidate these entries because issue #630 is very closely related to issue #634, issue #635 and issue #636.

Please add an entry to the "DeskTop Enhancements" section stating that desk accessories, directories and previewable files can now be launched from the Shortcuts menu and from the Shortcuts > Run a Shortcut... dialog box.

Under "DeskTop Enhancements", under "Keyboard-related changes:":

"* Shift key works as modifier to extend selection, on IIgs and systems with shift key mod. (#340)" should instead be
"* Shift key works as modifier to extend selection, on IIgs and systems with Shift key mod. (#340)" with the words "Shift key" replacing the words "shift key" because the "S" in the phrase "Shift key" is always capitalized and in order to match the style of all of the other keyboard shortcut entries in the release notes.

"* Apple+` or Apple+Tab cycles through open windows; Shift+Apple+` (and Shift+Apple+Tab, when detectable) cycles in reverse. (#143, #230)" should instead be
"* Apple+` or Apple+Tab cycles through open windows; Shift+Apple+` (or Shift+Apple+Tab, when detectable) cycles in reverse. (#143, #230)", with the word "or" replacing the word "and", in order to match the style of all of the other keyboard shortcut entries in the release notes.

"* Tab/Shift+Tab (or `/Shift+`) change selected icon in alphabetical order. (#275, #671)" should instead be
"* Tab or ` changes selected icon in alphabetical order; Shift+` (or Shift+Tab, when detectable) changes selected icon in reverse. (#275, #671)" for greater clarity and in order to match the style of all of the other keyboard shortcut entries in the release notes.

Under "DeskTop Enhancements", under a proposed new "File Picker Dialogs:" subsection:

Please add an entry to a proposed new "File Picker Dialogs:" subsection in the "DeskTop Enhancements" section referencing issue #598 and issue #605 that you can now press the Apple-Tab (or Shift-Tab, when detectable) keyboard shortcuts or hold down the Apple key (or Shift key, when detectable) while clicking Change Drive to reverse changing the order of drives in the file picker dialog boxes.

Under "Desk Accessory Enhancements":

The "Desk Accessory Enhancements" section should be renamed "Desk Accessory and Apple Menu Enhancements" because this section also includes Apple menu enhancements that do not just relate to desk accessories and Apple menu enhancements that do not relate to desk accessories at all.

"* Show Text File DA: Keyboard support. Esc quits, arrows scroll, Space toggles modes. (#4, #403)" should instead be
"* Show Text File: Keyboard support. Esc quits, arrows scroll, Space toggles modes. (#4, #403)" with the initials "DA" deleted in order to match the style of all of the other entries in the release notes.

Under "Additional Desk Accessories", under "Control Panels":

"* Control Panels

• Sounds
  • Allows selecting different alert sounds (#283)." should instead be

"* Control Panels

• Sounds
  • Allows selecting different alert sounds. (#283)" with a period (.) added after the word "sounds" and a period (.) deleted after the phrase "(#283)" in order to match the style of all of the other entries in the release notes.

Under "Additional Desk Accessories", under "Screen Savers":

"* Screen Savers

• Matrix
  • Digital rain effect, inspired by https://github.com/neilk/apple-ii-matrix" should instead be

"* Screen Savers

• Matrix
  • Digital rain effect, inspired by https://github.com/neilk/apple-ii-matrix." with a period (.) at the end of the sentence in order to match the style of all of the other entries in the release notes.

Under "Additional Desk Accessories":

"The Show Text File DA is now part of the file preview functionality (see below)." should instead be
"Show Text File is now part of the file preview functionality (see below)." with the word "The" deleted and with the initials "DA" deleted in order to match the style of all of the other entries in the release notes.

Under "Notable Fixes":

"* Fix inconsistencies around maximum number of icons allowed. (#529, #537, and more)" should instead be
"* Fix inconsistencies around maximum number of icons allowed. (#529, #537)", because there are no other inconsistencies around maximum number of icons allowed and in order to match the style of all of the other entries in the release notes.

"* Control-Reset quits cleanly back to ProDOS (except buggy emulators). (#141)" should instead be
"* Control+Reset quits cleanly back to ProDOS (except buggy emulators). (#141)", with the word "Control+Reset" replacing the word "Control-Reset", in order to match the style of all of the other keyboard shortcut entries in the release notes.

"* Disk Copy moved to a separate file that can be optionally removed, allowing other components to fit on a floppy disk. #216" should instead be
"* Disk Copy moved to a separate file that can be optionally removed, allowing other components to fit on a floppy disk. (#216)" in order to match the style of all of the other entries in the release notes and then this entry should be moved from under "Notable Fixes" to the "DeskTop Enhancements" section because this entry contains an Apple II DeskTop enhancement, not a notable fix.

Under "Notable Fixes", under "File Picker Dialogs:":

Please move the entry
"* File Picker Dialogs:

• Type-down selection (while holding Apple) is supported. (#610)" from under "Notable Fixes", under "File Picker Dialogs:" to a proposed new "File Picker Dialogs:" subsection in the "DeskTop Enhancements" section because this entry contains an Apple II DeskTop enhancement, not a notable fix.

Under "Notable Fixes", under "Desk Accessories:":

Please move the entries
"* Desk Accessories:

• Date and Time:
  • Expanded to include both date and time. (#11)
  • Read-only on systems with a clock. On systems without a clock, date is saved for next session. (#30, #39)
  • Shows 12/24hr setting. (#220)" from under "Notable Fixes", under "Desk Accessories:" to the "Desk Accessory Enhancements" section because these entries contain desk accessory enhancements, not notable fixes.

"* Desk Accessories:

• Sort Directory: Don't need to click before sorting. (#17)
• Sort Directory: Support as many entries as DeskTop supports. (#86)" should instead be

"* Desk Accessories:

• Sort Directory:
  • Don't need to click before sorting. (#17)
  • Support as many entries as DeskTop supports. (#86)" in order to match the style of the new "Date and Time" entry under "Notable Fixes", under "Desk Accessories:" in the release notes and then these entries should be moved from under "Notable Fixes", under "Desk Accessories:" to the "DeskTop Enhancements" section because these entries contains Apple II DeskTop enhancements, not a notable fixes.

Please move the entry
"* Desk Accessories:

• Prevent files in list from disappearing in certain cases. (#487)" from under "Notable Fixes", under "Desk Accessories:" to the root section of "Notable Fixes" because this entry has nothing to do with desk accessories.

Under "Notable Fixes", under "Hardware/Emulator Specific:":

"* Hardware/Emulator Specific:

• IIgs: Color DHR is re-enabled on exit. (#43)
• IIgs: Mono DHR is re-enabled when returning from system control panel. (#193, #440)
• IIgs: /RAM5 is now correctly recognized as a RAMCard. (#438, #439)" should instead be

"* Hardware/Emulator Specific:

• IIgs:
  • Color DHR is re-enabled on exit. (#43)
  • Mono DHR is re-enabled when returning from system control panel. (#193, #440)
  • /RAM5 is now correctly recognized as a RAMCard. (#438, #439)" in order to match the style of the new "Date and Time" entry under "Notable Fixes", under "Desk Accessories:" in the release notes.

"* Hardware/Emulator Specific:

• Macintosh LC PDS IIe Option Card: Doesn't crash on startup. (#93)
• Macintosh LC PDS IIe Option Card: Correct problems with interrupts affecting AppleTalk. (#129)" should instead be

"* Hardware/Emulator Specific:

• Macintosh LC PDS IIe Option Card:
  • Doesn't crash on startup. (#93)
  • Correct problems with interrupts affecting AppleTalk. (#129)" in order to match the style of the new "Date and Time" entry under "Notable Fixes", under "Desk Accessories:" in the release notes.

Under "Notable Fixes":

"A full list of fixes in 1.2 can be found at: https://github.com/a2stuff/a2d/issues?q=is%3Aissue+is%3Aclosed+milestone%3A1.2" should instead be
"A full list of fixes in Apple II DeskTop 1.2 can be found at https://github.com/a2stuff/a2d/issues?q=is%3Aissue+is%3Aclosed+milestone%3A1.2" with the words "Apple II DeskTop" added and with the colon (:) deleted for greater clarity and in order to match the style of all of the other entries in the release notes.

[c0mmander8]

Additional a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes:

Under "Notable Fixes":

"* Fix inconsistencies around maximum number of icons allowed. (#529, #537, and more)" should instead be
"* Fix inconsistencies around maximum number of icons allowed. (#528, #529, #537, #539) because issue #528 and issue #539 also relate to this entry, because there are no other issues relating to inconsistencies around the maximum number of icons allowed and in order to match the style of all of the other entries in the release notes.

[c0mmander8]

Corrections for Additional a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes:

Under "Notable Fixes":

"* Fix inconsistencies around maximum number of icons allowed. (#529, #537, and more)" should instead be

"* Fix inconsistencies around maximum number of icons allowed. (#528, #529, #537, #539)" because issue #528 and issue #539 also relate to this entry, because there are no other issues relating to inconsistencies around the maximum number of icons allowed and in order to match the style of all of the other entries in the release notes.

[inexorabletash]

I think I captured most of the above, except for adding additional issue numbers to lists. In most cases, the issue numbers omitted are intentional, because they describe issues not present in 1.1. For example, if a change was made from 1.1 to 1.2 that resulted in a new bug in 1.2, the new bug should not be listed in the release notes.

Also, completeness is not necessary; the full history of the issue tracker is available for anyone that is truly interested.

[inexorabletash]

Thanks especially for noticing where I'd lost track of the difference between the Enhancements and Notable Fixes section.

[c0mmander8]

a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes, part 1:

Under "General Enhancements":

"* Mouse Keys mode simplified: (#185)

• Open-Apple+Solid-Apple++Space to enter Mouse Keys mode. A sound will play." should instead be

"* Mouse Keys mode simplified: (#185)

• Open-Apple+Solid-Apple+Space to enter Mouse Keys mode. A sound will play.", with the phrase "Open-Apple+Solid-Apple+Space", with 1 plus sign ("+) between the word Solid-Apple and the word Space, replacing the phrase "Open-Apple+Solid-Apple++Space", with 2 plus signs ("++) between the word Solid-Apple and the word Space.

I am dividing the a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes into multiple parts because some of my proposed changes involve backticks (`s) which might mess up the appearance of my other proposed a2d/RELEASE-NOTES.md release notes string changes.

[c0mmander8]

/a2d/blob/main/RELEASE-NOTES.md, string changes, part 2:

Under "DeskTop Enhancements", under "File Picker Dialogs:":

"* Pressing Apple+Tab (or Shift+Tab, when detectable), or holding Apple (or Shift, when detectable) while clicking Change Drive reverses the order. (#598, #605)" should instead be
"* Pressing Apple+Tab (or Shift+Tab, when detectable), or holding Apple (or Shift, when detectable) while clicking Change Drive reverses the order in which the drive changes. (#598, #605)", with the phrase "in which the drive changes" added to the end of the sentence.

I am dividing the a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes into multiple parts because some of my proposed changes involve backticks (`s) which might mess up the appearance of my other proposed a2d/RELEASE-NOTES.md release notes string changes.

[c0mmander8]

a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes, part 3:

Under "DeskTop Enhancements", under "Keyboard-related changes:":

"* Tab or ` changes selected icon in alphabetical order; Shuft+` (or Shift+Tab, when detectable) changes selected icon in reverse. (#275, #671)" should instead be
"* Tab or ` changes selected icon in alphabetical order; Shift+` (or Shift+Tab, when detectable) changes selected icon in reverse. (#275, #671)", with the phrase Shift+`, with a backslash () before the backtick (`), replacing the phrase Shuft+`, without a backslash () before the backtick (`).

I am dividing the a2d/RELEASE-NOTES.md release notes, located at https://github.com/a2stuff/a2d/blob/main/RELEASE-NOTES.md, string changes into multiple parts because some of my proposed changes involve backticks (`s) which might mess up the appearance of my other proposed a2d/RELEASE-NOTES.md release notes string changes.