Somewhat easier to deal with SIMH PDP-11 docs...

[Perry Metzger]

Howdy!

As many of you are aware, the bulk of the SIMH documentation is in
Microsoft Word format, which is not particularly easy to read online or
search.

I'm slowly converting all the docs to clean GitHub Flavored Markdown. I
just finished my first draft of the PDP-11 documentation, and it can be
found here:

https://github.com/pmetzger/simh-docs/blob/main/docs/pdp11_doc.md

And yes, I've contacted the SIMH Steering Group and have offered to
contribute my efforts to SIMH. I don't know if they'll accept or not,
but I intend to leave my stuff available regardless, because I find it
useful.

Help proofreading and checking that everything survived the (arduous)
conversion is actively solicited, as are pull requests.

If you're curious, status of my efforts is in the README at:
https://github.com/pmetzger/simh-docs/

Perry

[Johnny Billquist]

While I don't particularly fancy word, I can't say GitHub flavored
markdown seems like that much better. Even if markdown in general aren't
that hard to work around if needed, I'm not a fan of GitHub, or variants
of formats that are very specific to one platform or another.

Why not just html, if you're going to change things around? That way it
will work no matter where the docs are located, instead if having to go
to github if you want to look at them.
(And if someone answers that you can just create a PDF to view anywhere,
then that is equally true of Word, so then why bother?)

Johnny

--
Johnny Billquist || "I'm on a bus
|| on a psychedelic trip
email: b...@softjar.se || Reading murder books
pdp is alive! || tryin' to stay hip" - B. Idol

[Jacob Ritorto]

Big thank you for the conversion work. I Dreaded dealing with those docs. While not particularly a GitHub fan, I am definitely a markdown fan, so as long as they don’t force me to auth to get to it, I’m good! Excellent move.

> On Aug 21, 2025, at 17:49, Perry Metzger <pe...@piermont.com> wrote:
>
> Howdy!

> --
> You received this message because you are subscribed to the Google Groups "[PiDP-11]" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pidp-11+u...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/pidp-11/4d997cbf-fc82-4964-934c-9d0d7e096d87%40piermont.com.

[Perry Metzger]

On 8/21/25 20:40, Jacob Ritorto wrote:
> Big thank you for the conversion work. I Dreaded dealing with those docs. While not particularly a GitHub fan, I am definitely a markdown fan, so as long as they don’t force me to auth to get to it, I’m good! Excellent move.

You're welcome!

Perry

[Perry Metzger]

On 8/21/25 19:48, Johnny Billquist wrote:
> While I don't particularly fancy word, I can't say GitHub flavored
> markdown seems like that much better. Even if markdown in general
> aren't that hard to work around if needed, I'm not a fan of GitHub, or
> variants of formats that are very specific to one platform or another.
>
> Why not just html, if you're going to change things around?

HTML is much harder to work with, and much harder to submit patches for.

> That way it will work no matter where the docs are located, instead if
> having to go to github if you want to look at them.

You don't have to go to GitHub to look at them. The plain text is quite
readable (Markdown has that property, wich is quite nice), and Pandoc
will convert them to anything you like, and there are dozens of other
Markdown processors and editors that will do the same.

Perry

[Warner Losh]

Indeed. Thank you. Markdown is a great choice. I find the markup is minimal enough not to get in the way.. it's not super expressive relative to some things, but good enough, easy to change and would invite more contributions. And mechanically convertable to lots of different formats..

Warner

Warner

Warner

Perry

--
You received this message because you are subscribed to the Google Groups "[PiDP-11]" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pidp-11+u...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pidp-11/df9413b3-b1d9-44c1-9c4a-3c9ebc57f7be%40piermont.com.

[Perry Metzger]

On 8/21/25 22:06, Warner Losh wrote:
>
> Indeed. Thank you. Markdown is a great choice. I find the markup is
> minimal enough not to get in the way.. it's not super expressive
> relative to some things, but good enough, easy to change and would
> invite more contributions. And mechanically convertable to lots of
> different formats.

Yah, I'd personally prefer something like restructured text in an ideal
world, but we're not in an ideal world, and I wanted to make things as
easy as possible to view and to contribute to.

Perry

[terry-...@glaver.org]

On Thursday, August 21, 2025 at 5:49:32 PM UTC-4 pe...@piermont.com wrote:

I'm slowly converting all the docs to clean GitHub Flavored Markdown. I
just finished my first draft of the PDP-11 documentation, and it can be
found here:

https://github.com/pmetzger/simh-docs/blob/main/docs/pdp11_doc.md

Having done something similar years ago (MS-DOS Kermit to WordStar), I feel it is a

pointless task unless you can get buy-in from the group creating the info. Even if they 

like it, they may reject it on the basis of "but who will maintain it if you stop?"

I'm from a pre-WYSIWYG world myself. I write my manuals in DECdocument to this

day. There's a dated (but still very informational) book, The Art of Technical Documen-

tation* that makes many points which are still valid today. One of which is that content

is separate from presentation - for example, DECdocument can create** PostScript,

plain ASCII text, HTML or Bookreader format output from the same source.

The idea is that the source content doesn't have to be modified to create whatever fla-

vor of output the user wants.

The format of source content is up to the authors (DECdocument is a dead end), but

Word should be able to create output in a variety of formats, from PDF to the worst

HTML coding I have ever seen (run it through the W3C validator for fun). What is lack-

ing right now is support for auto-generated Table of Contents / Index sections. Even

the incredibly convoluted RUNOFF to PDF process manages to get that right.

One of the things I noticed in your latest change is you're now using grey backgrounds 

for things that are not emulator commands - for example, in the list of CPUs in the "set

cpu table". It is important to distinguish between user input to a program, output from

the program, and prose explaining what's going on by using different visual styles.

* Do not buy the ripoff version from Elsevier - it is the first printing. You can find a

PDF of it floating around the Internet. The second printing is somewhat more cur-

rent.

** Most of the DECdocument formats are no longer relevant. I don't think anyone

uses Bookreader these days and the HTML output it creates is definitely "Web 0.9".

It is also old enough that the PostScript it generates uses the "original 35" font names

which will result in font substitutions that make the output look really ugly (wrong

character widths, etc.). I have modified DECdocument to use the modern font names

when it generates a PS file which will be rendered to PDF, and I also have a 'fixup' script

I can run on old DECdocument files to fix up the fonts before converting to PDF.

[Perry Metzger]

On 8/22/25 06:14, terry-...@glaver.org wrote:

On Thursday, August 21, 2025 at 5:49:32 PM UTC-4 pe...@piermont.com wrote:

I'm slowly converting all the docs to clean GitHub Flavored Markdown. I
just finished my first draft of the PDP-11 documentation, and it can be
found here:

https://github.com/pmetzger/simh-docs/blob/main/docs/pdp11_doc.md

Having done something similar years ago (MS-DOS Kermit to WordStar), I feel it is a

pointless task unless you can get buy-in from the group creating the info. Even if they 

like it, they may reject it on the basis of "but who will maintain it if you stop?"

I don't care. I needed this for myself, I was basically unable to work with the Microsoft Word version of the docs and I really wanted to be able to consult them regularly.

If the OpenSIMH project takes the documents back, great. If they don't, I have something I wanted for myself, and other people may find it useful too.

The beauty of Open Source is I didn't need permission, and other people can use it if they want to, and don't have to if they don't want to.

Perry

[Matthew Hume]

The beauty of having the documentation in a markdown (or TeX/TeXinfo/org/groff) is that you can have build steps that output the docs as odt/pdf etc. Best of both worlds. The source for any of these is also very friendly to git (et al.)

--
You received this message because you are subscribed to the Google Groups "[PiDP-11]" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pidp-11+u...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pidp-11/46bfb2b1-c604-4f32-9ba3-b6ffd858bb28%40piermont.com.

[Bert Driehuis]

An additional advantage is that it makes it possible to store docs in the same source tree as the source code, so that documentation can be versioned with the source code. Being able to run a diff is a huge benefit when reviewing document changes, to spot unintended changes as well as errors.

For those who are new to Markdown, it is quite like RUNOFF or troff. It is supported by a ton of tools, and easy to learn (unlike word :-)

For those who dislike Github, there's always Gitlab or the new kid on the black, Codeberg.

-- Bert

To view this discussion visit https://groups.google.com/d/msgid/pidp-11/CAM9_YbRNM%3DhMuyW2m3vq2Eta%3DeSHVWFAQPmc-%2BjZq5-w9xdMZA%40mail.gmail.com.

[Johnny Billquist]

Markdown is just another markup language, just like TeX, runoff, HTML,
XML and god knows what else.
Initially markdown was just one markup language, but of course it forked
and diverged, and there are now multiple dialects and variants, making
it quite a mess when people just say "markdown".

Johnny

On 2025-08-22 15:11, Bert Driehuis wrote:
> An additional advantage is that it makes it possible to store docs in
> the same source tree as the source code, so that documentation canbe
> versioned with the source code. Being able to run a diff is a huge
> benefit when reviewing document changes, to spot unintended changes as
> well as errors.
>
> For those who are new to Markdown, it is quite like RUNOFF or troff. It
> is supported by a ton of tools, and easy to learn (unlike word :-)
>
> For those who dislike Github, there's always Gitlab or the new kid on
> the black, Codeberg.
>
> -- Bert
>
> On Fri, 22 Aug 2025 at 13:12, Matthew Hume <mtt...@gmail.com
> <mailto:mtt...@gmail.com>> wrote:
>
> The beauty of having the documentation in a markdown (or TeX/
> TeXinfo/org/groff) is that you can have build steps that output the
> docs as odt/pdf etc. Best of both worlds. The source for any of
> these is also very friendly to git (et al.)
>
> On Fri, Aug 22, 2025, 07:02 Perry Metzger <pe...@piermont.com

> <mailto:pe...@piermont.com>> wrote:
>
> __

> On 8/22/25 06:14, terry-...@glaver.org

> <mailto:terry-...@glaver.org> wrote:
>> On Thursday, August 21, 2025 at 5:49:32 PM UTC-4

>> pe...@piermont.com <mailto:pe...@piermont.com> wrote:
>>
>> I'm slowly converting all the docs to clean GitHub
>> Flavored Markdown. I
>> just finished my first draft of the PDP-11 documentation,
>> and it can be
>> found here:
>>
>> https://github.com/pmetzger/simh-docs/blob/main/docs/

>> pdp11_doc.md <https://github.com/pmetzger/simh-docs/blob/
>> main/docs/pdp11_doc.md>

>>
>>
>> Having done something similar years ago (MS-DOS Kermit to
>> WordStar), I feel it is a
>> pointless task unless you can get buy-in from the group
>> creating the info. Even if they
>> like it, they may reject it on the basis of "but who will
>> maintain it if you stop?"
>
> I don't care. I needed this for myself, I was basically unable
> to work with the Microsoft Word version of the docs and I really
> wanted to be able to consult them regularly.
>
> If the OpenSIMH project takes the documents back, great. If they
> don't, I have something I wanted for myself, and other people
> may find it useful too.
>
> The beauty of Open Source is I didn't need permission, and other
> people can use it if they want to, and don't have to if they
> don't want to.
>
> Perry
>
>
> --
> You received this message because you are subscribed to the
> Google Groups "[PiDP-11]" group.
> To unsubscribe from this group and stop receiving emails from
> it, send an email to pidp-11+u...@googlegroups.com

> <mailto:pidp-11+u...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/
> pidp-11/46bfb2b1-c604-4f32-9ba3-b6ffd858bb28%40piermont.com

> <https://groups.google.com/d/msgid/pidp-11/46bfb2b1-
> c604-4f32-9ba3-b6ffd858bb28%40piermont.com?
> utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "[PiDP-11]" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to pidp-11+u...@googlegroups.com

> <mailto:pidp-11+u...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/

> pidp-11/CAM9_YbRNM%3DhMuyW2m3vq2Eta%3DeSHVWFAQPmc-%2BjZq5-
> w9xdMZA%40mail.gmail.com <https://groups.google.com/d/msgid/pidp-11/
> CAM9_YbRNM%3DhMuyW2m3vq2Eta%3DeSHVWFAQPmc-%2BjZq5-
> w9xdMZA%40mail.gmail.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "[PiDP-11]" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to pidp-11+u...@googlegroups.com

> <mailto:pidp-11+u...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pidp-11/

> CAN0x2A-pmtiCTbUVmmSa7D%3DGS-%3DkDYX%2B4fEx6O-Lu-
> yQBhCC7w%40mail.gmail.com <https://groups.google.com/d/msgid/pidp-11/
> CAN0x2A-pmtiCTbUVmmSa7D%3DGS-%3DkDYX%2B4fEx6O-Lu-
> yQBhCC7w%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[terry-...@glaver.org]

On Friday, August 22, 2025 at 9:41:24 AM UTC-4 b...@softjar.se wrote:

Markdown is just another markup language, just like TeX, runoff, HTML,
XML and god knows what else.
Initially markdown was just one markup language, but of course it forked
and diverged, and there are now multiple dialects and variants, making
it quite a mess when people just say "markdown".

I'd say that HTML is a presentation descriptor and not an actual markup

language, since you can't then convert it into anything useful. Aside from

Save as PDF and Print to PDF on my computer, I use 4 different online

converters and among these 6 I can sometimes get something usable.

Any text-based markup can be easily stored in GitHub.

And I remember the "markdown wars". Wasn't that another Jeff Atwood

thing?

[Johnny Billquist]

Of course you can convert HTML to something "useful". You just need the
right tools... :-)

But no, HTML really is a markup language. It is used to mark up a
document with formatting, structure and so on. Exactly what mark up means.

To quote wikipedia: "A markup language is a text-encoding system which
specifies the structure and formatting of a document and potentially the
relationships among its parts.[1] Markup can control the display of a
document or enrich its content to facilitate automated processing."

Or just read the whole article.
https://en.wikipedia.org/wiki/Markup_language

Not that I always think wikipedia is an absolute source of truth, but
this is pretty straight forward.

But if I were to pick something to do documentation in, I'd either do
runoff or TeX. But that's just me...

Johnny

> --
> You received this message because you are subscribed to the Google
> Groups "[PiDP-11]" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to pidp-11+u...@googlegroups.com
> <mailto:pidp-11+u...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pidp-11/

> ea8da109-4a40-4650-b4c5-9131c4b0d9c1n%40googlegroups.com <https://
> groups.google.com/d/msgid/pidp-11/ea8da109-4a40-4650-
> b4c5-9131c4b0d9c1n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[terry-...@glaver.org]

With my experience in commercial typography* (which is up there with buggy whip manufacturing as a niche industry these days) I'm quite familiar with various markup methods.

My opinion is you start with HTML if your main concern is format, and something else (RUNOFF, DECdocument, etc.) if your main focus is content.

But I've taken this thread afar afield from the original purpose, so I'll stop now. I might try turning the .md files into SGML for DECdocument, just to see how it goes.

* This is probably why TeX output drives me nuts - the fonts are subtly wrong - like the 'uncanny valley'.

[johntk...@gmail.com]

You might find this  script https://github.com/microsoft/markitdown

[Perry Metzger]

FYI, for those who are VAX afficionados, I've also cleaned up the SIMH
VAX documentation:

https://github.com/pmetzger/simh-docs/blob/main/docs/vax_doc.md

https://github.com/pmetzger/simh-docs/blob/main/docs/vax780_doc.md

The general SIMH documentation (both user and API) is also cleaned up
and available, see the index at:

https://github.com/pmetzger/simh-docs/blob/main/README.md

Perry