+ + + +

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 +