documentation rework

Discussion of development and patch submission.
Post Reply
User avatar
gen_angry
Posts: 127
Joined: Sat 25 Feb, 2017 6:48 am

documentation rework

Post by gen_angry »

Hello,

I have started a documentation rework here: https://github.com/gen-angry/docs-pcem/ ... /README.md

Before I continue, just wanted to poke Sarah to ask if this is something that would be added? I understand either way :) best to make a sample then ask before finishing it all and getting "na".

If so, also wish to ask if you wanted the machine links in the table as well (not to rom files, just to webpages throughout talking about that machine - can see a sample on the doc).

Cheers!
User avatar
SarahWalker
Site Admin
Posts: 2054
Joined: Thu 24 Apr, 2014 4:18 pm

Re: documentation rework

Post by SarahWalker »

Yeah, that's looking good to me. I know documentation has been an issue for many people so an alternative perspective on it is good!

Links are mostly okay, but note one of them links to a site with ROM images, which is something I'd rather not have.
User avatar
gen_angry
Posts: 127
Joined: Sat 25 Feb, 2017 6:48 am

Re: documentation rework

Post by gen_angry »

SarahWalker wrote: Mon 20 Jul, 2020 6:30 am Yeah, that's looking good to me. I know documentation has been an issue for many people so an alternative perspective on it is good!

Links are mostly okay, but note one of them links to a site with ROM images, which is something I'd rather not have.
I missed that, I apologize. Will be more diligent and fix that when I hit it up next.

Thanks for the feedback :)
User avatar
leilei
Posts: 1039
Joined: Fri 25 Apr, 2014 4:47 pm

Re: documentation rework

Post by leilei »

Dunno if it's too much visual clutter or usefulness, but maybe country flags for each computer model's availability in the table (where applicable i.e. US/EU for Packard Bells, UK for Amstrads, but nothing at all for Xi8088/anonymous XT or so)?

Just a little idea since the formatted list so far has me thinking about Dolphin's dressed up game list.
User avatar
gen_angry
Posts: 127
Joined: Sat 25 Feb, 2017 6:48 am

Re: documentation rework

Post by gen_angry »

leilei wrote: Tue 21 Jul, 2020 7:48 am Dunno if it's too much visual clutter or usefulness, but maybe country flags for each computer model's availability in the table (where applicable i.e. US/EU for Packard Bells, UK for Amstrads, but nothing at all for Xi8088/anonymous XT or so)?

Just a little idea since the formatted list so far has me thinking about Dolphin's dressed up game list.
Not a bad idea actually, I think github has country flag display support.

Will see if I can add it easily - I have an idea how it would work.
User avatar
gen_angry
Posts: 127
Joined: Sat 25 Feb, 2017 6:48 am

Re: documentation rework

Post by gen_angry »

just a question, would you be ok with an MD5/SHA1 of the correct ROM files on it?
User avatar
omarsis81
Posts: 945
Joined: Thu 17 Dec, 2015 6:20 pm

Re: documentation rework

Post by omarsis81 »

gen_angry wrote: Fri 24 Jul, 2020 5:37 am just a question, would you be ok with an MD5/SHA1 of the correct ROM files on it?
The is no problem to include the MD5/SHA1, the thing is that there is not just ONE valid file. There are many versions of a same ROM and all should work
vbdasc
Posts: 37
Joined: Tue 21 Mar, 2017 10:53 am

Re: documentation rework

Post by vbdasc »

omarsis81 wrote: Fri 24 Jul, 2020 3:04 pm The is no problem to include the MD5/SHA1
Well, we should wait to hear the opinion of the principial author on this. Because for some copyright purists even this could be considered an infringement.
omarsis81 wrote: Fri 24 Jul, 2020 3:04 pm the thing is that there is not just ONE valid file. There are many versions of a same ROM and all should work
Nothing prevents the inclusion of multiple hashes in this case, I guess.
User avatar
omarsis81
Posts: 945
Joined: Thu 17 Dec, 2015 6:20 pm

Re: documentation rework

Post by omarsis81 »

I once posted a checksum and I had no problems, that's why I said that
Zup
Posts: 83
Joined: Mon 30 Nov, 2015 10:47 am

Re: documentation rework

Post by Zup »

omarsis81 wrote: Fri 24 Jul, 2020 3:04 pmThe is no problem to include the MD5/SHA1, the thing is that there is not just ONE valid file. There are many versions of a same ROM and all should work
Should != will.

The thing is that PCem programmers check their changes with a set of ROMs. Other ROMs for the same system may be untested and may or may not work, and some dumps on internet may be mislabelled, incomplete or corrupt. Having the hashes of known good ROMS for each system would help filter problems caused by bugs or incorrect ROMs.
User avatar
omarsis81
Posts: 945
Joined: Thu 17 Dec, 2015 6:20 pm

Re: documentation rework

Post by omarsis81 »

Like vbdasc said, many hashes for different revisions could be added and then next to each hash a statement saying that it works or it doesn't
User avatar
gen_angry
Posts: 127
Joined: Sat 25 Feb, 2017 6:48 am

Re: documentation rework

Post by gen_angry »

Spent some time today and finished it (proofreading pending). Just wanted to get everything from the text file on there first before I start adding anything extra (like the flags suggestion from earlier).

If anyone's bored enough to skim over it as well to catch errors, would be appreciated :) if not I'll do that within the next few days.

Sarah: I'll post a thread with the files in patches when I'm happy with it so it can be shown within the actual repo?
User avatar
leilei
Posts: 1039
Joined: Fri 25 Apr, 2014 4:47 pm

Re: documentation rework

Post by leilei »

Maybe rename or split "Pentium-based" to Socket 4 - Socket 5 - Socket 7?

Years for sound cards and video cards?
ENM23
Posts: 19
Joined: Mon 13 Jun, 2016 12:26 pm

Re: documentation rework

Post by ENM23 »

Good work so far, started something similar long time ago...

Maybe some info about shipped drives (HDD, Floppy, CD-Rom), Slots (ISA, PCI ...) , Controller (IDE, SCSI), shipped OS and as said before years for SCs and VCs.

The documentation should be included with the PCem release.
Post Reply