scruf manual

scruf

scruf is a dirty, but minimalistic, program that spits out valid HTML5 files from marked up plain text files.

scruffy markup

The markup that is understood by scruf is called scruffy. The scruffy markup is inspired from MoinMoin's markup.

To learn about the syntax and details about the scruffy markup, take a look at the documentation page of scruffy markup.

how scruf works

The way scruf works is darn straightforward. You give it a directory and it recursively checks for scruffy marked up files and converts them into valid HTML5.

In each directory that contains scruffy marked up files, scruf automatically creates an index.scruffy file and a corresponding index.html,to which it appends links to all the HTML5 files that it has converted.

scruf provides its own style sheet which is placed in each directory that has HTML5 files produced by scruf.

using scruf

At present, scruf is cursed to only run on GNU/Linux based operating systems.

scruf is written in Java, therefore, there is a strong possibility that it could work out of the box in Windows, Mac, etc. But, be aware that it was never tested in platforms other than GNU/Linux, so there is no assurance that it will work as it should on other platforms.

To be able to use scruf, the openjdk package is required, in order to compile and run scruf.

installing the jdk

On a Debian GNU/Linux based system, the JDK can be installed with:

 # apt-get update
 # apt-get install default-jdk

If the above install command does not work, do:

  # apt-cache search jdk		

to find the appropriate package name for the JDK and then install the package with:

 # apt-get install appropriate-package-name

For installing the JDK on other GNU/Linux systems, take a look at openjdk's homepage for more information.

compiling scruf

You must compile scruf's source files, before it can be run to eat your scruffy marked up files.

Extract the tar archive and cd to scruf's territory:

 $ tar -xvzf scruf-X.X.X.tar.gz
 $ cd scruf-X.X.X/

The 'X's represent the version number of the scruf package.

The compilation procedure is arduous at present, it will be made simpler and nicer in the future to come.

Here's how the source is compiled at present:

 $ javac scruf/*.java
 $ javac scruf/*/*.java
 $ javac scruf/*/*/*.java

By now, scruf is cooked and ready to be exploited by your sweet hands.

convert scruffy files to HTML5

To convert scruffy marked up files, cd to the directory where scruf is:

 $ cd /path/to/scruf-X.X.X/

and do:

 $ java scruf.Run /path/to/scruffy-files-directory/

scruf will convert the scruffy marked up files and place the generated HTML5 files in the same directory where the scruffy marked up files reside.

The HTML5 files, generated by scruf, must not be manually edited, if you wish to edit a HTML5 file, edit the corresponding scruffy marked up file and generate the HTML5 files again by doing:

 $ java scruf.Run

As is seen above, it is not required to give the path to the scruffy files directory every time. scruf is intelligent enough to remember the directory. So from the second time on, it is just enough to run the program.

When a directory is given to scruf, when it is invoked:

 $ java scruf.Run /path/to/directory

It stores the absolute path of the directory in ~/.scruf/list.

Every time, scruf is run:

 $ java scruf.Run

it checks all the directories is the list for new/modified scruffy marked up files and converts them into HTML5.

ignoring directories

As previously mentioned, scruf recursively checks the given directory to find scruffy marked up files. There will be times when it doesn't make sense to let scruf loiter in sub-directories. It is possible to tell scruf to ignore the respective sub-directories.

To do this, create a .ignored file in the respective directory and list all the sub-directories that has to be ignored. The sub-directories listed in .ignored should be line seperated.

For instance, if audio/, video/, images/ are the sub-directories, that are to be ignored by scruf in the respective directory. The .ignore file, in this case, will look like this:

audio/
video/
images/

Cascading Style Sheets(CSS)

scruf places style.css in each directory in which it finds a scruffy marked up file. Feel free to edit & modify the style sheet. but please remember not to change/remove the names of classes, it may mess up the formatting of all the HTML5 files that are dependent on the style sheet.

The style.css is valid CSS3.

have problems?

If there are/is any issue(s) with using scruf or understanding how it works, contact rsiddharth.