Update Transferring-Roms.md

[GregariousJB]

Cleaning up some of the Engrish, clarifying some areas, and attempting to standardize a few repeated instructions. On a side note, I just noticed the completely separate "SSH" documentation page over at https://retropie.org.uk/docs/SSH/. Wondering if we should combine these two pages neatly into a new page, like "Remote Access" or something. Also seeing how smooth this pull request goes. I'm willing and able to pretty things up around here if help is needed.

[cmitu]

Thanks for the contribution.

I've left a few notes, but overall the changes are welcomed. About the SSH page, I'd leave that separate, since it's more than just about the ROM transfer.

One thing that I think it should be changed is re-arranging the options - File shares should be first, then USB and then SSH.

[cmitu]

Thank you !

[GregariousJB]

You're very welcome. Thank you for this awesome software.

[GregariousJB]

You're right about the Transferring Roms section being more than just SSH access, so combining those two pages wouldn't be prudent.

What about linking to the SSH page from within the SSH section in Transferring Roms? That would ensure one single area that contains relevant instruction and would prevent the need to update two pages when something changes in the SSH/SFTP documentation.

Trying to find a way to display the SSH page within the Transferring Roms page using variables or templates. Maybe using page.*. Tons of neat stuff here, though, like captions for images, and Admonitions could be used to make tips and warnings look nice, too.

[cmitu]

What about linking to the SSH page from within the SSH section in Transferring Roms? That would ensure one single area that contains relevant instruction and would prevent the need to update two pages when something changes in the SSH/SFTP documentation.

The SSH page is already under the 'Getting Starting' heading, so if the user wants to know more about it, it's kind of the next step. But I wouldn't mind adding a 'would you like to know more ?' link to the SSH page.

Trying to find a way to display the SSH page within the Transferring Roms page using variables or templates. Maybe using page.*. Tons of neat stuff here, though, like captions for images, and Admonitions could be used to make tips and warnings look nice, too.

We're trying to keep things simple - so they can be easily edited from Github by any user - and that's why we don't include a lot of MD extensions that require the users to know about it. In the past, the docs were a Github Wiki, so using these extensions would not show anything in the Wiki page.

In particular, the Admonitions plugin is really neat looking and I thought about including it, but the syntax is not straightforward and in order to see the results you'd need to install mkdocs and render/serve the docs.

[GregariousJB]

we don't include a lot of MD extensions

Darn. I assumed these were all pre-installed extensions already enabled.

the syntax is not straightforward

Seems fairly simple.

!!! note
This is a note

!!! warning
This is a warning

Something to consider is having a "How to Contribute" page, much like many other wikis do. I actually looked for one before I made my pull request just in case. It could go over Markdown syntax, MD syntax, and how to do pull requests. Some food for thought.

in order to see the results you'd need to install mkdocs and render/serve the docs.

I'm not sure what you mean here. Do you mean while editing a section, you wouldn't be able to preview something like an Admonition to see how it looks? I don't really have a good solution if that's the case. It would make editing a file via Github (or even in a nice external editor like VSCode) a bit of a challenge not being able to double-check your work. Looks like plenty of other people are interested in this, too.

Alright then, I'll concede. Better to keep it simple.

[cmitu]

Seems fairly simple.

!!! note
This is a note

!!! warning
This is a warning

Actually - that's the wrong syntax.
You need to (4 space ?) indent the block following the title for it to show correctly. You see what I mean ? That's not considering the situations where we would like to add code/tables/quotes into the admonition's text (which I'm not sure how well is supported).

Looks like plenty of other people are interested in this, too.

That's interesting. I'll tag that issue, thanks for bringing it up.

[HerbFargus]

Something to consider is having a "How to Contribute" page,

I had previously written up a rough style guide based on the commonmark flavour of markdown that plays nicer with the parser for mkdocs but I think it got lost in the migration to the repo. Not a bad idea though

[GregariousJB]

Not sure where else to discuss this stuff. I'm not seeing an official RetroPie Discord server.

Poor-man's Markdown note/warning could use blockquotes:

> **NOTE**
>
> Your Raspberry Pi needs to be connected to the same network (either via Ethernet or Wifi Dongle) as the computer you are accessing it from.

NOTE

Your Raspberry Pi needs to be connected to the same network (either via Ethernet or Wifi Dongle) as the computer you are accessing it from.

Curious, exactly which Material for Mkdocs extensions are being used?

[cmitu]

Not sure where else to discuss this stuff. I'm not seeing an official RetroPie Discord server.

You can use the forum, interested users can chime in also.

Curious, exactly which Material for Mkdocs extensions are being used?

Only one, listed in https://github.com/RetroPie/RetroPie-Docs/blob/master/mkdocs.yml.