Converting SDF tutorials to the wiki
There is a lot of existing knowledge in the SDF HTML tutorials, one goal of this wiki is to make it easier and quicker to update tutorials. Here are some pointers in porting over tutorials to wiki markup
Translated HTML files
User pifty has run a converter on all the existing (
RCS)
HTML tutorials, and dumped them into the SDF git instance
here, at git.sdf.org
User peteyboy has run a converter on the existing (
RCS)
HTML tutorials,
cleaned-up1) files, and dumped them into the SDF git instance
here, at git.sdf.org
-
Edit the page with the link, and replace it with a link of what you'd like the tutorial wiki page to be named and use [[tutorial page]] to make a link to the new page
Save the page, and look at the red link text you just saved. Click that link
Dokuwiki will tell you that page doesn't exist, would you like to create it? Look for the new page icon below right, and click that
In a new tab or browser window, open up the link in the git project for the page you want to copy, copy all the text into the new wiki page tab
You could save that, but it's probably messy and needs cleanup, due to the ways the HTML tutorial writers had to work and the limitations of the converter.
It's better if you do some cleanup:
Here are some tips:
Many of the paragraphs have leading spaces in the converted text, remove them because in wiki that's a code block
Remove anchor markup in headings, they are probably all messed up. The wiki automatically makes TOCs, so the manual ones can go
Remove any manually generated TOCs, because above
Remove any
HTML escape codes, like
> < & dokuwiki markup doesn't need these escaped, and doesn't render them as expected by
HTML.
Add wiki escape for character strings that are used in wiki markup, for example // or [[ or {{, or whole URLs you don't want to be links (//, for example, is the Dokuwiki markup for
italics). To escape, surround the text in the editor with <nowiki> and </nowiki> tags,
HTML-style, like so:
The protocol in a url is separated from the path by a colon and two slashes, for example:
http:<nowiki>//</nowiki>sdf.org
This should render as you expect, meaning not switching italics on for the rest of the document:
The protocol in a url is separated from the path by a colon and two slashes, for example:
http://sdf.org
leading a line by two spaces renders the line as
“code”2), so you can replace delineation around code that is meant for user to type, such as quotes or some other markup, with two spaces, like so:
this is code
Reference to HTML tutorial you ported
Currently we are using the following convention to link to the source HTML tutorials, via a snippet at the end of the tutorial that looks like so in dokuwiki markup:
<Link to Tutorial> - traditional link (using <Wikipedia link to 'RCS' definition>)
For example, the markup looks like:
[[http://sdf.org/?tutorials/Ruby_on_Rails | Ruby on Rails]] - traditional link (using [[wp>Revision_Control_System|RCS]])
And the Example page would then include:
Notes