summaryrefslogblamecommitdiffstats
path: root/docs/scruf-howto.html
blob: 09eb543b066b2abba9d5e3f549e84155590abc15 (plain) (tree)

































































































































































































































































                                                                                                                                                                                             
<!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&#46;scruffy</span> file and a corresponding
<span class="monospace">index&#46;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 /> &#35; apt&#45;get update<br /> &#35; apt&#45;get install default&#45;jdk<br /></div>		

<p>
If the above <span class="monospace">install</span> command does not work, do:
</p>

<div class="code"><br />  &#35; apt&#45;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 /> &#35; apt&#45;get install appropriate&#45;package&#45;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 /> &#36; tar &#45;xvzf scruf&#45;X&#46;X&#46;X&#46;tar&#46;gz<br /> &#36; cd scruf&#45;X&#46;X&#46;X&#47;<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 /> &#36; javac scruf&#47;&#42;&#46;java<br /> &#36; javac scruf&#47;&#42;&#47;&#42;&#46;java<br /> &#36; javac scruf&#47;&#42;&#47;&#42;&#47;&#42;&#46;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 /> &#36; cd &#47;path&#47;to&#47;scruf&#45;X&#46;X&#46;X&#47;<br /></div>

<p>
and do:
</p>

<div class="code"><br /> &#36; java scruf&#46;Run &#47;path&#47;to&#47;scruffy&#45;files&#45;directory&#47;<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 /> &#36; java scruf&#46;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 /> &#36; java scruf&#46;Run &#47;path&#47;to&#47;directory<br /></div>

<p>
It stores the absolute path of the directory in <span class="monospace">&#126;&#47;&#46;scruf&#47;list</span>. 
</p>

<p>
Every time, scruf is run:
</p>

<div class="code"><br /> &#36; java scruf&#46;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">&#46;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">&#46;ignored</span> should be line seperated.
</p>

<p>
For instance, if <span class="monospace">audio&#47;</span>, <span class="monospace">video&#47;</span>, <span class="monospace">images&#47;</span> are the
sub-directories, that are to be ignored by scruf in the respective
directory. The <span class="monospace">&#46;ignore</span> file, in this case, will look like this:
</p>

<div class="code"><br />audio&#47;<br />video&#47;<br />images&#47;<br /></div>

<h2> Cascading Style Sheets(CSS)  </h2>

<p>
scruf places <span class="monospace">style&#46;css</span> in each directory in which it finds a <i>scruffy</i>
marked up file. Feel free to edit &amp; 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 &amp; 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>