Help manual revised

[Richard Russell]

I have (perhaps unwisely) revised the General Information section of the Help manual so that the information is presented in a more 'logical' sequence. Previously the sections were ordered pretty much randomly, which was fine for 'dipping in' but not so much for reading from beginning to end.

All the information is still there, only the order in which it is presented has changed, and hyperlinks to that section of the manual should still work. It's probably the best place to go if you are interested in how my 'modern' versions of BBC BASIC (BB4W, BBCSDL and BBCTTY) differ from Acorn's ARM BASIC 5.

If you spot any typos, or think that the order in which the information is presented is still not optimum, let me know. For those who would have preferred it left well alone, and now can't find what they are looking for because it's moved, sorry.

[JeremyNicoll]

The order is fine.

On my current (5:4) monitor, that page is nearly 50 screenfuls long. It might seem even longer (esp with poor eyesight so zoomed/magnified a bit) on a letterbox-like aspect-ratio laptop screen.

I think it would benefit greatly from an initial table of contents even if that only listed (& had links to) each of the major sections below (those immediately preceded by a horizontal line), eg:

Major sections below:
- Line numbers
- Line continuation
- Variables
- Entire-array operations
- Structures
- Indirection and pointers
- Expressions
- Operators and special symbols
- Procedures and functions
- Keywords
- Program flow control
- Debugging
- Error handling
- Input editing
- Copy key editing
- Hardcopy output to a printer
- Statement separators
- Labelling program lines
- Multilingual (Unicode) text output

[Richard Russell]

I think it would benefit greatly from an initial table of contents

The Table of Contents is here (for BBCSDL) as it always has been. It has to be in a separate file for HTML Help Workshop, I think, so moving it as you suggest would break the creation of both the CHM and PDF versions of the manual.

I'd also point out that the way the manual is split into separate HTML files is largely arbitrary, for example the Keywords section of the manual is split into bbcwin4.html, bbcwin5.html, bbcwin6.html and bbcwin7.html but could equally well have been three or five files.

You can think of the HTML files as the 'source code' of the manual, the CHM and PDF versions are unaffected by how it is split between them, just like a compiled application is unaffected by how the source code is split between individual source files.

On a more general point, the manual's overall structure has remained exactly the same since its original release in 2001. Making a major change after nearly 25 years is never likely to be practical or desirable.

[JeremyNicoll]

I wasn't suggesting moving the entire ToC, just putting a useful list of sections (without links if those would break the chm- & pdf-generation process).

You already have some internal links on this page, eg those just under "Variable types", pointing to sub-sections on:
- Static variables
- Integer numeric variables
- 64-bit integer numeric variables
- Byte numeric variables
- Variant numeric variables
- 64-bit floating-point numeric variables
- String variables
- Arrays
- Structures
- Arrays of structures
- Pseudo-variables
- System variables

If those work, why wouldn't what I suggested?

[Richard Russell]

If those work, why wouldn't what I suggested?

Because if an extra Table of Contents is present in the HTML file it will presumably be visible somewhere in the CHM and PDF too, but you don't want it to be because in the context of those versions of the manual there is nowhere that the appearance of such a table makes sense.

Put another way, the Table of Contents that you propose is specific to the way the manual has been split between different HTML files (it's effectively the 'contents of bbcwin2.html') yet that split is largely arbitrary and 'bbcwin2.html' has no meaning in the context of the CHM and PDF.

It's unfortunate that SDL 2.0 has nothing comparable to Windows' HTML Help that could be used to make the manual available offline in the way that BB4W does - unless you know of something of that kind which will work on all the supported platforms.

[JeremyNicoll]

If those work, why wouldn't what I suggested?

Because if an extra Table of Contents is present in the HTML file it will presumably be visible somewhere in the CHM and PDF too...

We seem to be at cross-purposes here. Maybe you're reading more than I intended into the term "Table of Contents"? If "ToC" has a formal meaning to you (something auto-generated?) then I don't mean that; I just mean a handful of extra links near the top of the page.

Your huge manual single-page already has multiple links to other points in the same page within it (& lots to other pages). If none of those cause a problem for the chm- / pdf-generation, why would adding 12 more be a problem?

[Richard Russell]

We seem to be at cross-purposes here.

Yes, but not for the reason you seem to think. I understood exactly what you were meaning, but you're not understanding what I am saying.

Your huge manual single-page already has multiple links to other points in the same page within it (& lots to other pages).
If none of those cause a problem for the chm- / pdf-generation, why would adding 12 more be a problem?

Because those existing links are inline with content where they are in context. You are proposing a table of links at a place (presumably at the very start of the file) where they are not in context.

Open the BB4W HTML Help (CHM) viewer and tell me exactly where it would be appropriate for your Table of Contents / list of links to appear. Do you see the problem now? It's even worse in the case of the PDF because it doesn't have internal links so your table wouldn't link to anything.

Let's draw this to a close please. This is not something that anybody else has requested in 25 years and I am not going to consider adding it now, especially given that I can't see how to do that without mucking up the CHM and the PDF.

[Richard Russell]

It's unfortunate that SDL 2.0 has nothing comparable to Windows' HTML Help that could be used to make the manual available offline in the way that BB4W does - unless you know of something of that kind which will work on all the supported platforms.

An AI query points me towards eWriter, which I know nothing about, as a cross-platform alternative to CHM:

• eWriter (Modern Single-File Alternative)
  eWriter is considered a modern, cross-platform replacement for CHM, developed by EC Software.
  How it works: It packages a complete set of WebHelp (HTML, CSS, JS) into a single, compact file.
  Cross-Platform: Works on Windows, macOS, and mobile, with viewers available.
  Benefits: Supports modern HTML5/CSS3, high-resolution displays, and is more secure than CHM.

Has anybody here tried it?

[Richard Russell]

An AI query points me towards eWriter, which I know nothing about, as a cross-platform alternative to CHM:

But then another query tells me "The eWriter viewer is not available for Linux, iOS or Android". As is often the case, teasing the truth from the AI Slop isn't easy.

[JeremyNicoll]

Because those existing links are inline with content where they are in context.

Do you mean it's because the links to sub-sections on various types of variables are all part of what (in chm) looks like a single Variables page?

Does whatever generates the chm/pdf also generate the multi-section webpages?

Let's draw this to a close please. This is not something that anybody else has requested in 25 years and I am not going to consider adding it now, especially given that I can't see how to do that without mucking up the CHM and the PDF.

You could post-process the HTML pages; if all of them are like the new one (which I just discovered they're not), you'd just have to find each "<HR>" then the following "<H2>" & extract its text and anchor value, build a list of those & insert it close to the top.

I've done it (by hand, using commands in my text editor to find & copy & manipulate the candidate H2 headings) for two pages here. The effect is:
https://www.dropbox.com/scl/fi/qr299kjn ... f7ilu&dl=0

& the html code change:
https://www.dropbox.com/scl/fi/6gsevpb4 ... bofvm&dl=0