This repository exists as a place to store OpenSIMH's documentation as it is converted from Microsoft Word to Markdown. The conversion is being done partially using Pandoc, but generally requires extensive hand cleanup of the Pandoc output to get a usable result.
Pull requests against this repository are welcome.
The hope is that these files will eventually be merged into https://github.com/open-simh/simh, but this repository will be maintained even if it is not merged into OpenSIMH.
These documentation files are considered to be in good shape. They have been hand fixed following the Pandoc conversion but might still contain proofreading errors:
| filename | documentation contents |
|---|---|
| altairz80_doc.md | Altair Z80 simulator |
| gri_doc.md | GRI-909 simulator |
| ka10_doc.md | DEC PDP-10 (KA10) simulator |
| ki10_doc.md | DEC PDP-10 (KI10) simulator |
| kl10_doc.md | DEC PDP-10 (KL10) simulator |
| ks10_doc.md | DEC PDP-10 (KS10) simulator |
| pdp1_doc.md | DEC PDP-1 simulator |
| pdp8_doc.md | DEC PDP-8 simulator |
| pdp6_doc.md | DEC PDP-6 simulator |
| pdp10_doc.md | DEC PDP-10 (KS10) simulator |
| pdp11_doc.md | DEC PDP-11 simulator |
| simh.md | Writing a SIMH simulator |
| simh_breakpoints.md | SIMH Breakpoints |
| simh_doc.md | SIMH User’s Guide |
| simh_faq.md | SIMH FAQ |
| simh_magtape.md | SIMH Magtape docs |
| simh_swre.md | SIMH Sample Software |
| simh_vmio.md | Adding an I/O device to SIMH |
| simulators_acm_queue_2004.md | ACM Queue article on SIMH |
| ssem_doc.md | SSEM simulator |
| vax_doc.md | DEC VAX simulator |
| vax780_doc.md | DEC VAX 11/780 simulator |
Files that are nearly untouched. Generally, the raw output of Pandoc is unlikely to be readable:
| filename | status |
|---|---|
| b5500_doc.md | ❌ raw pandoc |
| h316_doc.md | ❌ raw pandoc |
| h316_imp.md | ❌ raw pandoc |
| h316_imp_IO_Device_Codes.md | ❌ raw pandoc |
| hp2100_doc.md | ❌ raw pandoc |
| hp3000_doc.md | ❌ raw pandoc |
| i1401_doc.md | ❌ raw pandoc |
| i1620_doc.md | ❌ raw pandoc |
| i650_doc.md | ❌ raw pandoc |
| i7010_doc.md | ❌ raw pandoc |
| i701_doc.md | ❌ raw pandoc |
| i7070_doc.md | ❌ raw pandoc |
| i7080_doc.md | ❌ raw pandoc |
| i7090_doc.md | ❌ raw pandoc |
| i7094_doc.md | ❌ raw pandoc |
| ibm1130.md | ❌ raw pandoc |
| id_doc.md | ❌ raw pandoc |
| lgp_doc.md | ❌ raw pandoc |
| nova_doc.md | ❌ raw pandoc |
| pdp18b_doc.md | ❌ raw pandoc |
| sds_doc.md | ❌ raw pandoc |
| sel32_doc.md | ❌ raw pandoc |
| sigma_doc.md | ❌ raw pandoc |
| swtp6800_doc.md | ❌ raw pandoc |
| tx0_doc.md | ❌ raw pandoc |
The SIMH documentation has previously been kept in Microsoft Word format.
Unfortunately, this format makes it difficult to view the documentation online except as pre-formatted PDFs.
Word it also makes it hard to use modern code development practices; it is not a "git friendly" format because:
- You cannot view changes to documentation under source control as diffs.
- You cannot automatically merge distinct development branches using source control.
- You cannot easily accept pull requests.
Easier development of SIMH's documentation requires that it be moved to a plain text-based format that is both viewable online and which can be maintained using modern source control.
Markdown is the most commonly used format for such documentation these days, and so this effort is using GitHub Flavored Markdown.
Markdown is imperfect, and there are certainly better formats that allow better semantic markup and better control over the appearance of the output.
However, Markdown works well enough, is very readable even without formatting, can be viewed in its formatted form directly on GitHub without requiring any tools at all, requires almost no effort for newcomers to learn, and is in widespread use.