2nd edition revision

[dansanderson]

Goals for this revision:

1. Focus on the MEGA65 production model. The 1st edition pre-dated the first production model and was written with early project participants in mind. Speculations about how the production model would behave have been corrected, and information that does not apply to the production model has been removed.
2. Focus on new users. 1st edition bounced between new-user material and obscure technical topics. Emphasis has been streamlined, including the removal of material irrelevant to new users. Topics are task-oriented and prioritize common user goals.
3. Update procedures and screenshots to represent the most recent best practices and v0.96 release behaviors.
4. Enhance information about upgrading the platform components, including how to register with Filehost and get the latest release package.
5. Extend information about using disks and disk images.

Still to do: a short chapter on Ethernet file transfer. This will necessarily involve introducing M65Connect and/or mega65-tools. This feels like an expansion of scope, but I'm eager to take the position that Ethernet file transfer will be a major mode of operation for many users. It's faster and more reliable than hassling with SD cards. M65Connect should support Ethernet file transfers by the time this goes to press.

In general, this draft pushes the frame of reference of the User's Guide closer to our everyday experience, including more references to Internet resources. It's difficult to balance describing the MEGA65 in isolation as if it were a Commodore product and describing it as a living project with an online community. The more reality we bring into the printed books, the faster that information will go stale on the page. We could alternatively consider setting up new mega65.org short links to wiki pages for some of these topics and direct readers to web resources instead of trying to capture them in the User Guide.

[gurcei]

Will jot some general thoughts here, and after that, I'll drop my other notes inline with the change-diffs:

• parts of our manual preferred manually adding line-breaks at a certain line-width, and on other occasions it makes lengthy lines that only line-break at the end of a paragraph. Maybe the style-guide should specify one way or the other. Just find that when commits switch from one way to the other it adds a bit of noise in the diff. (for me, I lean towards manual line-breaks at a certain width, but maybe it's something we can discuss in the manuals channel in discord.

• For commit#7f421bf7717033db129f43dade3c109798e419de

  • cosmetic page breaks make me a little nervous, as while they likely look great in the present state, they might not look so great in future when new text is added, or text is moved/removed. (could lead to unsightly page-breaks with pages of mostly empty space).
  • I haven't had a chance to assess the intent behind these page-breaks yet. So just wondering if there are any other means to achieve what you set out to do?
  • were you trying to group a set of content together on a single page? if so, I think we've encountered this scenario before and might have alternate solutions for it (to group various elements together to assure that they stay on the same page)

[gurcei]

I'll also aim for my 1st review to drop notes relating to main chapters. I'll try do this tonight.

Then on my 2nd review, I'll focus on your BASIC changes and drop those comments in.

[gurcei]

A side-note, could be a good time to update "introduction.tex" to say:

• FROM: ...1080 pages and growing!
• TO: ...1200 pages and growing!

[gurcei]

Also, I noticed in the user-guide's chapter 2 blue page, the "Switching the MEGA65 on for the First Time" heading gets broken into two lines, with the 2nd line jutting out awkwardly:

Interestingly, the same page in the mega65-book.pdf doesn't suffer from this problem (perhaps the font is smaller there and it fits on a single line?)

Not sure if there's anything we can do to remedy this to look a bit nicer? Maybe with some latex-fu?

[dansanderson]

• parts of our manual preferred manually adding line-breaks at a certain line-width, and on other occasions it makes lengthy lines that only line-break at the end of a paragraph. Maybe the style-guide should specify one way or the other. Just find that when commits switch from one way to the other it adds a bit of noise in the diff. (for me, I lean towards manual line-breaks at a certain width, but maybe it's something we can discuss in the manuals channel in discord.

I agree that ideally we'd pick a style, document it specifically, and be consistent. Hard wrap and soft wrap both have advantages, and I don't have a strong opinion. Something we can encode in .vscode/settings.json for the project would be ideal.

I went with soft wrap for the new material because with VSCode LaTeX Workshop I was spending too much time re-formatting paragraphs (Alt-Q) to match style with hard wraps, and it didn't seem worth it because our existing hard-wrapped content is wildly inconsistent. You have to touch every paragraph after every change because it won't do it automatically, presumably to avoid re-wrapping something it shouldn't. If there's a way to get it to behave fully automatically with hard wraps, I'll take it. Note that with soft wraps you do have to activate soft wraps each time you open the file (Alt-Z), but so far that's been less hassle than reformatting each paragraph after a change.

• cosmetic page breaks make me a little nervous, as while they likely look great in the present state, they might not look so great in future when new text is added, or text is moved/removed. (could lead to unsightly page-breaks with pages of mostly empty space). I haven't had a chance to assess the intent behind these page-breaks yet. So just wondering if there are any other means to achieve what you set out to do? were you trying to group a set of content together on a single page? if so, I think we've encountered this scenario before and might have alternate solutions for it (to group various elements together to assure that they stay on the same page)

I was borrowing the current practice already in place throughout the 1st ed. We might be able to avoid some cases with \nopagebreak. I'm not sure that's always better than page breaks, in general. Grouping decisions may be appropriate for today's text and inappropriate for tomorrow's, just like the page breaks. I would expect to tweak layout—and tweak content to fit layout—whenever preparing text for print. (For example, I've already reorganized section headings to prevent the chapter intro page from spilling over to two pages, even if the original section layout made sense logically.)

Also, I noticed in the user-guide's chapter 2 blue page, the "Switching the MEGA65 on for the First Time" heading gets broken into two lines, with the 2nd line jutting out awkwardly:

Interestingly, the same page in the mega65-book.pdf doesn't suffer from this problem (perhaps the font is smaller there and it fits on a single line?)

Not sure if there's anything we can do to remedy this to look a bit nicer? Maybe with some latex-fu?

I thought we had modeled this specifically after Commodore's C64 books, including this indentation style on the chapter intro page. I'm looking at the PDFs now and am surprised to see that their chapter intro pages use much smaller text. Maybe I'm looking at the wrong editions? I'm not personally bothered by this example but I don't object to seeing it changed.

[dansanderson]

Thank you so much for the detailed review, @gurcei ! I have incorporated all of these.

[gurcei]

No problem :-) Also, feel like some of the comments got hidden by github within a textbox saying "45 hidden conversations" (somewhere between the visible conversation above). Just thought I'd mention it, in-case they were overlooked. They expand once you click on that textbox a few times (they seem to expand by 20 per click of the textbox)

[dansanderson]

No problem :-) Also, feel like some of the comments got hidden by github within a textbox saying "45 hidden conversations" (somewhere between the visible conversation above). Just thought I'd mention it, in-case they were overlooked. They expand once you click on that textbox a few times (they seem to expand by 20 per click of the textbox)

Oh dang, I thought it was just hiding previously resolved comments. I'll do these now. 😅

[dansanderson]

OK, I have addressed the comments so far. Still pending:

• Slot 0 flashing. lydon to review slot 0 flashing instructions when the feature is finished.
• Cart selection of cores. To be written once the feature is finished.
• M65Connect and Etherload. To be written once the feature is finished. The latest mega65_ftp is now in a good state to be used by M65Connect as a dependency for a reasonable UI wrapper.
• Soft wrap vs. hard wrap. I'll try to figure out if there are better best practices with LaTeX Workshop around this. I tend to agree that source files should be easy to edit in simple text editors and not require specific IDEs if possible, and soft wraps are less friendly to common reading experiences (but more friendly to common editing experiences).
• Consider replacing \em with \underline throughout.
• Short URL for ROM FAQ.

[dansanderson]

FYI LaTeX Workshop uses latexindent.pl for auto-formatting. I'll have to test it to see if it's destructive to our custom listing environments (e.g. \screenoutput), and it'll make a huge change the first time it runs. I'd like to do this outside this PR. If it's workable, I'll install it and use it, and hopefully we'll get hard-wrapped source that's easy to manage.

[gurcei]

PS. I also think @Impakt might not have had a chance to review your new Chapter 7 and all your changes to appendix-basic65.tex, as I think you made those commits after his proof-read run.

(In the case of the latter, I think he reviewed your initial basic65 changes from an earlier commit, but significantly more changes came in a later commit)

So just in-case, will put them on his radar in case he wants to look them over.

I'm working my way through them now too.

[gurcei]

PS. Maybe it was a little hasty to merge this in, feel like it would've been better to wait until I had finished my chapter 7 and basic review and added my notes for it into this PR too.

Ah well, it's done now, but feel like in future, it'd be worth waiting for green ticks from the reviewers on this, especially when the changes are significant and meaty.

[dansanderson]

I apologize if merging to master looked like I was closing off further feedback, that wasn't my intention. I was expecting that we'd continue the review on this PR. Github should allow us to post more comments here. Let me know if there are issues with that. We can also leave comments directly on the merged commit.

If it feels like I'm rushing the schedule a bit, it's because we were given a looming but unspecified deadline. 😵‍💫 Trenz Electronic needs some number of months of lead time for printing ("1-3 months" was deft's guess), and I have no idea what date they want to use as the final if our plan is still to ship batch #3 in Q4. I wanted to open the review more widely via the Digest and assumed the October Digest would be too late, and I didn't want to do that from a branch. (It would not have been a big deal to do it from a branch, it just seemed nicer to clean up the branch and encourage the wider audience to submit Issues instead of everyone piling into this PR.)

I'm very interested in your feedback on Chapter 7 and the BASIC reference editing pass. As noted above, we'll add more material on M65Connect and core slot configuration when those features have been completed. If we hit our print deadline before the features are ready, then we can remove material and direct people to short URLs linking to Filehost articles for more information.

The intro to the BASIC reference has been reworked for clarity, so that deserves some scrutiny. The changes to the reference itself are minor factual corrections and style polish. I normalized reference styles primarily based on the dominant existing styles for consistency. If it helps with the review, this describes most of the changes:

• Keyword definitions are a single sentence with the keyword as an implied subject.
• Commands are verb phrases; functions and operators are noun phrases that describe the return value; parameters are noun phrases that describe the parameter value.
• In parameter lists, trailing period only used when the definition uses multiple sentences; everything in a list consistent.
• Exceptions made for control flow keywords where the existing descriptions were more useful.
• Bitmap graphics keywords say "Bitmap graphics:" at the beginning of the description. (I remember being routinely disappointed when I first started using the BASIC reference when a useful-sounding command turned out to be limited to bitmap graphics mode. 😅)
• Use the \index term as the \label term, for the few cross-references into the BASIC reference. (I discovered that index terms can contain a \$ but labels cannot, so a reference to CHR\$ had to be spelled slightly differently.)
• Use LaTeX n-dashes (--) for value ranges.

I also resolved all of the existing doc bugs pertaining to the BASIC reference, only a few.

[dansanderson]

@gurcei Thanks again for the detailed review! I have incorporated and addressed all of these. Change: https://github.com/MEGA65/mega65-user-guide/commit/23c74b931ac5820e563c5401c6baa0730447876a

"un-shifted" vs. "punctuation" characters deserves another look, I agree that my attempted improvement could go further but I don't think "un-shifted" is appropriate. Let me know if you think of a better term or explanation.

I'm interested in your reaction to my EDMA change explanation.