meta-title: scruf manual
meta-author: rsiddharth

==========
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
[[http://moinmo.in/HelpOnMoinWikiSyntax|MoinMoin's markup]].

To learn about the syntax and details about the ''scruffy'' markup,
take a look at the [[./scruffy-markup.html|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 [[http://www.debian.org/|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 [[http://openjdk.java.net/|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 read 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|style.css]] is valid CSS3.

====================
have problems?
====================

If there are/is any issue(s) with using scruf or understanding how it
works. Please subscribe & send an email to the
[[http://lists.nongnu.org/mailman/listinfo/scruf-friends|scruf-friends]]
mailing list. That way we can solve your problem together.

----------------------------------------------------------------------
a ''scruffy'' howto.
----------------------------------------------------------------------