- - - -

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 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 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 -scruf-friends -mailing list. That way we can solve your problem together. -

- - - - - -

- - source -

- back -