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

Interested in keeping the Wiki tutorials in sync with the HTML tutorials? Some folks only like to update the HTML tutorials. Here's a clever, quick command you can run from /sys/html/tutorials to see updates from this year to files in HTML tutorials, that takes advantage of the fact that only files from the current year have hours:minutes in their timestamps. :

ls -l /sys/html/tutorials | grep :

If you need more than the current year, here's a kludgy-but-working one-liner you can run to see any updates since 2023:

sh

rlog -r *.html |perl -nle "print if /^(Work|date)/"|perl -pe "s/Working file://" |perl -pe "s/^date: (.*)author.*/\1/"|perl -pe "s/(^.*\/[0-9]*) .*/\1/" |perl -pe 'chomp; $_ .= " ". <>'| sed -e 's/\(^.*\) \(.*$\)/\2\1/'|awk '$1>2023'|sort -r

For the reverse way, if you want to update the HTML tutorials to match the wiki, there is a “Recent changes” link at the top of all wiki pages that goes to a page you can use to find recent changes.

1. 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
2. User peteyboy has run a converter on the existing (RCS) HTML tutorials, cleaned-up¹⁾ files, and dumped them into the SDF git instance here, at git.sdf.org

• You can look on the start or SDF basics page to find a file to convert (see that it is an external link in the wiki to http://sdf.org/?tutorials/)
• 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.

• in another new tab, open this link for the dokuwiki syntax
• make changes, using the preview to make sure the page looks good before saving

• 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> no formatting 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”²⁾, 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

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:

Ruby on Rails - traditional link (using RCS)

Notes