[Enhancement/Suggestion] I made a readme to include in Libretro Docs

[mrmatteastwood]

Hey @schellingb, I drafted a readme file for DOSBox Pure that could be included in Libretro Docs.

https://github.com/mrmatteastwood/docs/blob/master/docs/library/dosbox-pure.md

It is based on the existing DOSBox documentation and it's really just a first draft, I included everything from your readme, made some changes and additions, and left a few chunks of the original DOSBox document from the Libretro Docs in there because I don't know if they still apply or what should be changed about them.

I annotated the whole thing (look for the red squares) and I'm sure I got a bunch of stuff wrong, but it's a start and I'd be curious what you think. If you like this approach, I'll be more than happy to keep working on this documentation until we can finally submit it to the Libretro team, I'll just need your input because there's a bunch here that I simply don't know or understand.

Also, I'm a real GitHub n00b. I was able to make a fork of https://docs.libretro.com/ and then create that new .md file (dosbox-pure.md), but I'm not sure I'm doing everything right. Anyway, for now it looks like it works. Of course I'll be happy to give you access, just need to figure out how.

[mrmatteastwood]

Hey @schellingb, I added a section about MPU-401 emulation through MUNT to the readme and fixed an incorrect link at the end of the document.

[mrmatteastwood]

Hello @schellingb, I made some changes to my readme.md: I added the Generic Keyboard Bindings for port 1 (which you posted in bug #57), added a section about running CD-ROM games and a "Compatibility" section at the bottom with info re. Boppin (cf. bug #75).

I'm ready and more than willing to get this readme.md out there. Hit me up anytime, and we can go over this readme.md together and fix the missing bits. It would be awesome to finally have a proper document about DBP on the official libretro docs, but I'll need your insight to finish up the remaining parts.

Current status here: https://github.com/mrmatteastwood/docs/blob/master/docs/library/dosbox-pure.md

[mrmatteastwood]

Hey @schellingb I made a branch of my own repo to work on the DBP doc, and I made a large number of additional changes and extensions yesterday and today, including all generic keyboard mappings for all 4 ports. You can see the latest doc here:

https://github.com/mrmatteastwood/docs/blob/DOSBox-Pure-doc-WIP/docs/library/dosbox-pure.md

Hit me up anytime and we'll finish this up. As soon as it can go live on the official libretro docs, I'll be more than happy to become this document's constant maintainer.

[schellingb]

@mrmatteastwood Thanks so much for still working on this and not giving up!

If it's ok with you, I'll just list some things as I go through.

• For the official docs, links to screenshots should probably be to the libretro repository - i.e. https://raw.githubusercontent.com/libretro/dosbox-pure/main/images/startmenu.png
• Remove my name from the opening paragraph and just write the authors as it's written in the dosbox_pure_libretro.info file, with just the nickname. No need to stand out from other cores here :-)
• You'll find some other information in that INFO file you can copy over, like supported extensions. I'd preserve the order as it is in the INFO file because I ordered it by "priority" in regards to the core.
• You can add "(alternative extension to .ZIP)" behind the .dosz extension.
• License GPLv2 is correct (according to the INFO file :-))
• You can ✔ RetroArch Cheats maybe? Technically it is correct but maybe it's fine as is because the cheats database doesn't have any entries for DOS games.
• Geometry and timing:
  • The DOSBox Pure core's core provided FPS is dependent on the DOS application
  • The DOSBox Pure core's core provided sample rate is dependent on the 'Audio > Audio Sample Rate' core option
  • The DOSBox Pure core's base width is 320
  • The DOSBox Pure core's base height is 200
  • The DOSBox Pure core's max width is 1280
  • The DOSBox Pure core's max height is 1024
  • The DOSBox Pure core's core provided aspect ratio is dependent on the DOS application and the 'Video > Aspect Ratio Correction' core option
• Core options you maybe can copy out the information from the definition source file (they are completely different from the other DOSBox cores)
• Joypad section... uhh... it's a lot. Where should we start?

[mrmatteastwood]

Hey man, awesome to hear from you! I'll go through your notes over the upcoming weeks and report back here. Good stuff!

Re. core options: that definition source file is the exact source of the options and descriptions visible in RA, right? I was going to use those, yeah, so this is perfect.

[mrmatteastwood]

Hey @schellingb, I made most of the changes you listed in your notes above.

Added troubleshooting tips for smooth scrolling, updated geometry and timing, extensions, author name, tick for RetroArch Cheats support. Also linked the trailer on YouTube.

Not quite sure how to amend the links to screenshots...? Would you happen to have some time to fork my repo and make that change?

I'll get to the Core Options and the Joypad section asap.

[mrmatteastwood]

Hey @schellingb, as far as I'm concerned, this file is at 5-to-prime-time o'clock. https://github.com/mrmatteastwood/docs/blob/DOSBox-Pure-doc-WIP/docs/library/dosbox-pure.md

Can you give it a final glance, let me know if any other changes are required? If you're good with it, I'll remove the remaining notes and open a pull request for the main repo (once I figure out how :-)).

EDIT: oh, re. the Joypad section, not sure if that still requires changes...?

[mrmatteastwood]

Hey @schellingb, do you wanna wrap this one up and send it off to the Libretro team? This core rocks and I think it totally deserves its own readme doc on the Libretro documentation, and I'm sure we're almost there. It probably just requires a last glance from you and possibly a few small touch-ups here and there.

[mrmatteastwood]

Hi @schellingb! I'm about to go on vacation for 10 days and I'd be delighted to work together on this readme, add a section about the mapper, tidy it up and send it out to the RA team. You in?

[schellingb]

Let's do it! This time for real 😅 Instead of me doing a pull request on your repo or some other fancy procedure, I'd like to just go through what you have and write comments here on what I think should be amended if that's ok with you?

[mrmatteastwood]

Nice! Yeah, that sounds perfect. You can leave feedback here, then I'll make the changes and report here. Once it's all vetted and we're happy with it, I might need your help sending a pull request to the official RA repo. I'm still a total GitHub n00b...

[mrmatteastwood]

Updated the readme to include info about all new features in 0.9.0 and 0.9.1.

https://github.com/mrmatteastwood/docs/blob/DOSBox-Pure-doc-WIP/docs/library/dosbox-pure.md

[schellingb]

Here's some random comments :-)

• DOSBox Pure is fork is missing a a
• After the extensions .img/.ima/.vhd you can add .jrc and .tc (both PCjr bootable roms) which were added in 0.9.0
• And the extension .conf is now also bootable with 0.9.0 (booting a dosbox.conf file will mount the directory as C: and load/autoexec the conf file)
• As for RetroArch databases, DOS is the only relevant one. But as of now that database only has entries for .EXE files and not for .ZIP files so it's not that great but I think we can leave it written as is. I do still want to have ZIP files added to it. Some day...
• Maybe we should add ", but newer versions will load save states from old versions" after "Also, save states might not be compatible across different versions of DOSBox Pure" to avoid worry there. Or remove the whole sentence, it might be common sense that way. This also applies below to the "Core Options" chapter where dosbox_pure_savestate is documented.
• The core options have since changed to the new categorized format. So we should write Save States Support as Emulation -> Save States Support. We could add "Options" after the category name to match the full name listed in the options, but probably unnecessarily verbose.
• Maybe we can add the text from the README's "Booter games" paragraph to the "Directly run PC booter games from the start menu" chapter to flesh it out a bit. While probably not many users will use it, I'm quite happy how the feature turned out :-)
• Can we get rid of The DOSBox Pure core's library name is 'DOSBox-Pure'. and thus the whole "Directories" chapter? It's very useless :-)
• Also "Features currently not implemented" can maybe stay just on the github readme and doesn't need to be in the user documentary. These were technical thoughts I had when originally releasing the core and I don't think these will be added anytime soon (or ever).
• Btw. we maybe should check if that workaround for "Boppin'" still works as described... Before 0.9.0 the joystick ports were either enabled or disabled based on the port settings (as described). But now joystick ports are always enabled (just like they are always enabled/available on a real IBM PC with a soundcard). This is because Turrican 2 would crash when there is a soundcard but no joystick ports. So I worry Boppin' can now not be worked around anymore...
• Looking at the libretro docs page it looks like we can do in-document links just like on github by using #header-title as a link. So add some of those. For example .zip in "Extensions" could be .zip (see [Load games from ZIP](#load-games-from-zip)) or Rewind in "Features" could be [Rewind](#rewind-support), etc.

And I must say you have done an amazing job with this, compiling all that info from all kinds of places. It's become quite big, hasn't it? So thank you thank you again for doing this and keeping at it and helping out. I'm actually excited to see this go up on the official site now :-)

[mrmatteastwood]

Nice nice nice. Thanks for the in-depth feedback, and I'm glad you like the readme file so far! It's a lot of fun to work on it and I'm glad I get to contribute.

• DOSBox Pure is fork is missing a a > added
• After the extensions .img/.ima/.vhd you can add .jrc and .tc (both PCjr bootable roms) which were added in 0.9.0 > done
• And the extension .conf is now also bootable with 0.9.0 (booting a dosbox.conf file will mount the directory as C: and load/autoexec the conf file) > done
• Maybe we should add ", but newer versions will load save states from old versions" after "Also, save states might not be compatible across different versions of DOSBox Pure" to avoid worry there. Or remove the whole sentence, it might be common sense that way. This also applies below to the "Core Options" chapter where dosbox_pure_savestate is documented. > good point, removed the note in both places
• The core options have since changed to the new categorized format. So we should write Save States Support as Emulation -> Save States Support. We could add "Options" after the category name to match the full name listed in the options, but probably unnecessarily verbose. > I think I'm already following the categorized options system here. This option is listed below the headline "Emulation" already. Am I missing something?
• Maybe we can add the text from the README's "Booter games" paragraph to the "Directly run PC booter games from the start menu" chapter to flesh it out a bit. While probably not many users will use it, I'm quite happy how the feature turned out :-) > ahh, good, yes! I was thinking there should be more. Added it. Interesting, I never even heard of "PC booter games" before!
• Can we get rid of The DOSBox Pure core's library name is 'DOSBox-Pure'. and thus the whole "Directories" chapter? It's very useless :-) > done
• Also "Features currently not implemented" can maybe stay just on the github readme and doesn't need to be in the user documentary. These were technical thoughts I had when originally releasing the core and I don't think these will be added anytime soon (or ever). > agreed

More coming soon!

[mrmatteastwood]

Unfortunately, you were right about "Boppin'". Not sure how else to solve this one. If you have any ideas, I'm all ears and willing to test!

[mrmatteastwood]

Hey again @schellingb! I added the fix for Boppin' to the readme and finished going through the whole thing, adding in-document links where appropriate. One more thing I'm gonna do is read through the release notes of previous DBP releases, to see if there's anything that came out since, like, September that can still be added to the readme. Apart from that, I'd say we're good to go! Wanna vet it once more?

[schellingb]

Thanks for adding all those in-document links, nice!

Only thing worth mention would be how the core automatically executes "DOSBOX.BAT" instead of showing the start menu if it exists in the mounted ZIP or path. Maybe a small chapter above "Loading M3U8 files"?

Other than that I also think we're ready to submit it, looks good to me. I guess you'll open a PR on the original docs repo next? And then the docs homepage will automatically update once that PR gets merged?

Edit: I just looked through some docs and noticed on the Dolphin page it has a youtube video embedded. The video embed code for that can be seen in the source https://raw.githubusercontent.com/mrmatteastwood/docs/master/docs/library/dolphin.md. Maybe we should do that for the DOSBox Pure release trailer?

[mrmatteastwood]

Awesome! This is exciting! I added the bit, then did one last a/b of the core options section with your core_options.h. This is the pull request: https://github.com/libretro/docs/pull/734

I hope I did that right. Does it look right to you?