I've started the E8 integration into the pidp8i distribution.

I believe the recommendation was to "create a tu56 image akin to what was done for cc8". I've created the e8-integration branch with the relevant files as well as mods to Makefile.in auto.def to do that.

It showed a bug in cpto (Untested code coverage: Options don't work. Easily fixed.)

It also provokes the following questions:

Q1: What sort of documentation do we want to ship that is usable inside OS/8?

The .svg and .md manual won't render in that environment. AUTHORS.md and COPYING.md will because they have no markdown. (But their names change to the OS/8 name restriction of XXXXXX.YY 6.2 filename length constraint.)

I am attempting to include manual.md, e8Buffer.svg, and css.pdf as image files. (That's how I found the bug in cpto. The manual chokes PIP/A with LINE TOO LONG, and /I to treat it as an image doesn't work yet.)

Q2: What default screen size do we want to set?

My terminal windows open 80x24, but Bill Silver's default is 80x40. It's a compile time option. I'm inclined to create e8defs.pa with 80x24. Does that sound sane?

There's a bit of autodef testing that I'm a bit iffy on. I THINK I've got the right bits in auto.def to let people specify e8 or not.

When the above issues are resolved, I'll update v3d-rk05.os8 and uni-rk05.os8 to incorporate e8, and then we can merge e8-integration into trunk.

I've created the e8-integration branch

I prefer that e8 be merged with pip8i, rather than have a parallel set of files and directories under src:

• docs in /doc, not /src/.../doc
• build tools in /tools, not /src/.../tools
• E8 Makefile rules selectively merged into the PiDP-8/I Makefile.in as we do for SIMH, palbart, etc.

The second two points were moot in your initial checkin, because the Makefile wasn't used, therefore the tools aren't used. I did the merge, taking only the stuff creating and uploading e8-manual.pdf, since I couldn't see any need within the PiDP-8/I project for the rest of it. If you want e8all.pa, for example, you probably want to be working from upstream sources like e8-dist.zip anyway.

Also, src/os8/e8 is wrong. src/os8 contains the source code of OS/8, which doesn't include E8. It should be src/e8.

I've checked all of this in as e4505fd571c0fb and children.

I've also written tools/e8-update to copy things over on-demand after the upstream version changes. Just run it without args from the top source dir after you make changes to E8 that you want copied over.

What sort of documentation do we want to ship that is usable inside OS/8?

Either:

1. None at all because you have a perfectly usable host system running SIMH in which to view docs, which doesn't have a 4 kWord page size to contend with. (Same reason CC8 can't diagnose syntax errors.)

2. A cut-down version of the existing docs, made to fit on an 80x24 glass terminal screen or on 80x60-ish lines of text on continuous-feed teleprinter paper, as output from a TYPE command. Basically, cram as much of manual.md into your README.TX as fits.

   If you like this option, would it be sacrilege include a plain-text hyperlink to the online view of the docs? "For more info, see https://tangentsoft.com/e8"?

It appears that you are copying these docs only to the tape image, then not doing anything with them afterward at build time. I suppose that's useful if you foresee creating real DECtapes from these images in order to get E8 onto a real PDP-8, but within the PiDP-8/I tree, it's questionable. Who would mount this tape and begin browsing it on a Pi vs opening another terminal to the Pi and reading the docs in the host?

This ties the above two threads together: if we expect some users of e8.tu56 to dump the whole contents of the tape onto an RK05 or similar, then we should name the files to avoid conflicting in the flat filesystem. Thus E8MAN.TX instead of README.TX and such.

What default screen size do we want to set?

I think we have two major camps here:

1. Historical accuracy over practicality.

2. "Whatever I want it to do, because it's my computer."

Since only camp 1 is casting a coherent vote, camp 1 wins by plurality. :)

However, it would also be nice to have a configure-time option to override this. e.g. --e8-screen-width=100 --e8-screen-height=56

I THINK I've got the right bits in auto.def to let people specify e8 or not.

Looks sane to me.

Sorry that I made more work for you to put stuff in a better location in the tree. I'm glad to see there's a tool to sync in upstream, though!

The option to do a configure-time option seems reasonable, but a bit beyond my current skill with autodefs. I guess it would involve creating e8defs.pa.in and filling in the requisite bits. As a start, I'll create the e8defs.pa with 24x80, and then one of us can do the add-on.

Meditating on the OS/8 manual needs, I think maybe some "reminders" of commands might be helpful. I.E. reminders of which key commands do which things, especially in cases where Emacs users like me keep hitting the wrong keys. To fit in reasonable screens, this probably means creating several small files. I'll take that action item.

As far as the use of the tu56 image, I'd like to have it be broadly useful, if that can be done without a lot of stuff that is demonstrably superfluous to pidp8i. This brings me to new questions:

COPYING doesn't actually have markdown in it. Perhaps we should rename it?

If so, is there a 6.2 name that makes sense?

Going back to an earlier question,

would it be sacrilege include a plain-text hyperlink to the online view of the docs? "For more info, see https://tangentsoft.com/e8"?

I don't care if others perceive it as sacrilege. I think it's fine. We should include such links where it makes sense. Which brings me to...

Should we shift AUTHORS.md to a more plain text approach, and name the URLs, rather than including them as markdown?

Should we put the .PDF e8 manual on the tu56 image in addition to or instead of the markdown version?

I notice that, although Makefile.in knows how to create e8-manual.pdf, it's not actually depended upon by anything, and so it's not built with all.

I was trying to figure out if I really needed to include the css.pdf and the E8Buffers.svg files on the tape. Oddly, when I run build e8-manual.pdf, the picture associated with the buffer isn't present. Also mine renders in a sans-serif font instead of the serif-font I see on tangentsoft.com.

Here is the output from the build:

wdc-home2:trunk wdc$ make doc/e8-manual.pdf
tools/mkmanpdf doc/e8-manual
Conversion options changed from defaults:
  extra_css: u'doc/e8-manual-pdf.css'
  pdf_serif_family: u'Adobe Garamond Pro'
  pdf_mono_family: u'Source Code Pro'
  page_breaks_before: u'/'
  pdf_sans_family: u'Myriad Pro'
1% Converting input to HTML...
InputFormatPlugin: TXT Input running
on /Users/wdc/src/pidp8i/trunk/doc/e8-manual.md
File extension indicates particular formatting. Forcing formatting type to: markdown
Language not specified
Creator not specified
Building file list...
Normalizing filename cases
Rewriting HTML links
Forcing index-1.html into XHTML namespace
34% Running transforms on e-book...
Merging user specified metadata...
Detecting structure...
Auto generated TOC with 0 entries.
Flattening CSS and remapping font sizes...
Source base font size is 12.00000pt
Removing fake margins...
Cleaning up manifest...
Trimming unused files from manifest...
Creating PDF Output...
67% Running PDF Output plugin
Splitting markup on page breaks and flow limits, if any...
QPainter::begin: Paint device returned engine == 0, type: 2
QPainter::setRenderHint: Painter must be active to set rendering hints
QPainter::translate: Painter not active
QPainter::setPen: Painter not active
QPainter::setBrush: Painter not active
QPainter::setWorldTransform: Painter not active
QPainter::setFont: Painter not active
QPainter::setOpacity: Painter not active
QPainter::save: Painter not active
QPainter::setWorldTransform: Painter not active
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::restore: Unbalanced save/restore
QPainter::end: Painter not active, aborted
QPainter::begin: Paint device returned engine == 0, type: 2
QPainter::setRenderHint: Painter must be active to set rendering hints
QPainter::translate: Painter not active
QPainter::setPen: Painter not active
QPainter::setBrush: Painter not active
QPainter::setWorldTransform: Painter not active
QPainter::setFont: Painter not active
QPainter::setOpacity: Painter not active
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::setBrush: Painter not active
QPainter::brush: Painter not active
QPainter::setOpacity: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::strokePath: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::save: Painter not active
QPainter::setWorldTransform: Painter not active
QPainter::save: Painter not active
QPainter::setOpacity: Painter not active
QPainter::hasClipping: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::setOpacity: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::setPen: Painter not active
QPainter::pen: Painter not active
QPainter::strokePath: Painter not active
QPainter::restore: Unbalanced save/restore
QPainter::end: Painter not active, aborted
100% Rendered index-1.html
Rendered PDF in 0.902038 seconds:
PDF output written to /Users/wdc/src/pidp8i/trunk/doc/e8-manual.pdf
Output saved to   /Users/wdc/src/pidp8i/trunk/doc/e8-manual.pdf
Round-trips: 5   Artifacts sent: 0  received: 10
 done, sent: 1901  received: 18459450  ip: 206.189.175.28

creating e8defs.pa.in and filling in the requisite bits

There's no real need for *.in here, because there is little about the resulting file that is static, such that it's worth putting under separate version control. My checkin for this just emits the E8DEFS.PA file to disk.

Please sanity-check it. It appears to work here, but I'm the guy who took 3 days to solve Project Euler Problem #1 in PAL8. :)

reminders of which key commands do which things

Yes, but very brief and dense. Instead of the big Markdown table as in manual.md, a densely-packed list of stuff like:

  ^A  goto BOL    ^Q  quit to OS/8    A-R  recover chars

…3 or 4 columns wide, much like "man ascii".

COPYING doesn't actually have markdown in it. Perhaps we should rename it?

Fossil uses the file extension to set the MIME type and choose a rendering mode. Whatever you use, it needs to work for file browsing in the Fossil UI view.

Keep in mind that Markdown is intended to be readable on terminals. There's nothing saying we have to have separate files for viewing on the web and viewing in a SIMH terminal window.

Unless OS/8 considers *.MD special, I say leave it alone.

Also, realize that E8 shares the SIMH license, so we should reuse SIMH-LICENSE.md, not copy COPYING.md over redundantly.

is there a 6.2 name that makes sense?

E8LIC.TX or E8LIC.MD, depending on whether it remains plain-text or gets Markdown.

Should we shift AUTHORS.md to a more plain text approach, and name the URLs, rather than including them as markdown?

No. That file is most useful in the web view, by people coming to the project and browsing. The needs of that view should not be subordinate to the limitations of a PDP-8.

Should we put the .PDF e8 manual on the tu56 image in addition to or instead of the markdown version?

Why ever for? There are no PDF viewers for the PDP-8.

The only debate is whether we should include the Markdown version with the assumption that someone's willing to TYPE it out to a teleprinter to produce a paper manual with mostly-readable formatting, or whether we should leave that to the web view, with the online version being much briefer.

...e8-manual.pdf...not built with all.

That's intentional. Look at the contents of tools/mkmanpdf.

Maybe if in some indefinite future this script could be made smart enough to find Calibre or compatible tools wherever they may be and substitute fonts on a cascading basis, then we could talk about making it part of the default build.

This is also why "make pdf" includes a step to upload the generated PDF as unversioned content to tangentsoft.com: so people can just download the latest built PDF instead of trying to generate it locally.

mine renders in a sans-serif font instead of the serif-font I see on tangentsoft.com.

Same answer: the PDF build script depends on things you don't have locally, so it can't work the same everywhere.

It wouldn't matter if you sorted this out, because you haven't got UV push abilities to this repo anyway. You can have them for the asking, but because UV ops are destructive, with no backup, I expect you'll want to think carefully before asking, given your uncertainties about your Fossil skills.

That's why capability "y" is denied to all users by default.

E8 with your e8defs.pa built for me too. The generator for it and the code looked fine to me.

I did check in updates to Makefile.in and e8-tu56.os8 to deal with the demise of COPYING.md. As far as I remember off hand, OS/8 doesn't have a special use for .MD, so we'll leave that alone.

A hyper-condensed table of commands sound like the right thing. I'll get on it.

The current e8-manual.md needs to be copied in as an image because it chokes PIP with a "LINE TOO LONG" error. Do we want to chase after that in the file, or keep copying it in using image mode?

I've just checked in the help files that I think should be sufficient.

The only open question on e8 integration, as far as I know is:

Do we want to chase down the "LINE TOO LONG" issue reported by PIP, and possibly switch to copying it to the tu56 image in ASCII rather than image mode?

I think it's a bug that ^N and ^P in E8 go to the beginning of the line.

I've raised that as an issue in the google forum.

I've pulled the trigger and checked in the change to v3d-rk05.os8 and uni-rk05.os8 to add e8. This gives us a complete draft of the e8 integration.

(And I thought it would "take me an hour." Well, that time estimate was wrong. :-) )

What's our criteria

Utility and stability, which we apparently have, so...