<!DOCTYPE html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="style.css" />
<meta name="author" content=" rsiddharth">
<title> scruf manual</title></head>
<body>
<article>
<h1> scruf manual </h1>
<h2> scruf </h2>
<p>
scruf is a dirty, but minimalistic, program that spits out valid HTML5
files from marked up plain text files.
</p>
<h3> scruffy markup </h3>
<p>
The markup that is understood by scruf is called <i>scruffy</i>. The
<i>scruffy</i> markup is inspired from
<a href="http://moinmo.in/HelpOnMoinWikiSyntax">MoinMoin's markup</a>.
</p>
<p>
To learn about the syntax and details about the <i>scruffy</i> markup,
take a look at the <a href="./scruffy-markup.html">documentation page</a> of
<i>scruffy</i> markup.
</p>
<h2> how scruf works </h2>
<p>
The way scruf works is darn straightforward. You give it a directory
and it recursively checks for <i>scruffy</i> marked up files and converts
them into valid HTML5.
</p>
<p>
In each directory that contains <i>scruffy</i> marked up files, scruf
automatically creates an <span class="monospace">index.scruffy</span> file and a corresponding
<span class="monospace">index.html</span>,to which it appends links to all the HTML5 files that it
has converted.
</p>
<p>
scruf provides its own style sheet which is placed in each directory
that has HTML5 files produced by scruf.
</p>
<h2> using scruf </h2>
<p>
At present, scruf is cursed to only run on GNU/Linux based operating
systems.
</p>
<p>
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 <i>will</i> work as it should on other platforms.
</p>
<p>
To be able to use scruf, the <span class="monospace">openjdk</span> package is required, in order to
compile and run scruf.
</p>
<h3> installing the jdk </h3>
<p>
On a <a href="http://www.debian.org/">Debian</a> GNU/Linux based system, the JDK
can be installed with:
</p>
<div class="code"><br /> # apt-get update<br /> # apt-get install default-jdk<br /></div>
<p>
If the above <span class="monospace">install</span> command does not work, do:
</p>
<div class="code"><br /> # apt-cache search jdk <br /></div>
<p>
to find the appropriate package name for the JDK and then install the
package with:
</p>
<div class="code"><br /> # apt-get install appropriate-package-name<br /></div>
<p>
For installing the JDK on other GNU/Linux systems, take a look at
openjdk's <a href="http://openjdk.java.net/">homepage</a> for more information.
</p>
<h3> compiling scruf </h3>
<p>
You must compile scruf's source files, before it can be run to eat
your <i>scruffy</i> marked up files.
</p>
<p>
Extract the tar archive and <span class="monospace">cd</span> to scruf's territory:
</p>
<div class="code"><br /> $ tar -xvzf scruf-X.X.X.tar.gz<br /> $ cd scruf-X.X.X/<br /></div>
<p>
The 'X's represent the version number of the scruf package.
</p>
<p>
The compilation procedure is arduous at present, it will be made
simpler and nicer in the future to come.
</p>
<p>
Here's how the source is compiled at present:
</p>
<div class="code"><br /> $ javac scruf/*.java<br /> $ javac scruf/*/*.java<br /> $ javac scruf/*/*/*.java<br /></div>
<p>
By now, scruf is cooked and read to be exploited by your sweet
hands.
</p>
<h3> convert <i>scruffy</i> files to HTML5 </h3>
<p>
To convert <i>scruffy</i> marked up files, <span class="monospace">cd</span> to the directory where
scruf is:
</p>
<div class="code"><br /> $ cd /path/to/scruf-X.X.X/<br /></div>
<p>
and do:
</p>
<div class="code"><br /> $ java scruf.Run /path/to/scruffy-files-directory/<br /></div>
<p>
scruf will convert the <i>scruffy</i> marked up files and place the
generated HTML5 files in the same directory where the <i>scruffy</i>
marked up files reside.
</p>
<p>
The HTML5 files, generated by scruf, <u>must not</u> be manually edited,
if you wish to edit a HTML5 file, edit the corresponding <i>scruffy</i> marked
up file and generate the HTML5 files again by doing:
</p>
<div class="code"><br /> $ java scruf.Run<br /></div>
<p>
As is seen above, it is not required to give the path to the <i>scruffy</i>
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.
</p>
<p>
When a directory is given to scruf, when it is invoked:
</p>
<div class="code"><br /> $ java scruf.Run /path/to/directory<br /></div>
<p>
It stores the absolute path of the directory in <span class="monospace">~/.scruf/list</span>.
</p>
<p>
Every time, scruf is run:
</p>
<div class="code"><br /> $ java scruf.Run<br /></div>
<p>
it checks all the directories is the <span class="monospace">list</span> for new/modified <i>scruffy</i>
marked up files and converts them into HTML5.
</p>
<h3> ignoring directories </h3>
<p>
As previously mentioned, scruf recursively checks the given directory
to find <i>scruffy</i> 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.
</p>
<p>
To do this, create a <span class="monospace">.ignored</span> file in the respective directory and
list all the sub-directories that has to be ignored. The
sub-directories listed in <span class="monospace">.ignored</span> should be line seperated.
</p>
<p>
For instance, if <span class="monospace">audio/</span>, <span class="monospace">video/</span>, <span class="monospace">images/</span> are the
sub-directories, that are to be ignored by scruf in the respective
directory. The <span class="monospace">.ignore</span> file, in this case, will look like this:
</p>
<div class="code"><br />audio/<br />video/<br />images/<br /></div>
<h2> Cascading Style Sheets(CSS) </h2>
<p>
scruf places <span class="monospace">style.css</span> in each directory in which it finds a <i>scruffy</i>
marked up file. Feel free to edit & modify the style sheet. but please
remember not to change/remove the <u>names</u> of <span class="monospace">classes</span>, it may
mess up the formatting of all the HTML5 files that are dependent on the
style sheet.
</p>
<p>
The <a href="./style.css">style.css</a> is valid CSS3.
</p>
<h2> have problems? </h2>
<p>
If there are/is any issue(s) with using scruf or understanding how it
works. Please subscribe & send an email to the
<a href="http://lists.nongnu.org/mailman/listinfo/scruf-friends">scruf-friends</a>
mailing list. That way we can solve your problem together.
</p>
<footer>a <i>scruffy</i> howto.</footer>
<div class="source">
<a href="./scruf-howto.scruffy">source</a>
</div>
<div class="back">
<a href="./"> back </a>
</div>
</article>
<div class="lastupdate">
Last Updated on: 21 December, 2012</div>
<div class="scruf">
<a href="http://nongnu.org/scruf/">powered by scruf</a>
</div>
</body>
</html>