summaryrefslogtreecommitdiffstats
path: root/docs/scruf-howto.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/scruf-howto.html')
-rw-r--r--docs/scruf-howto.html258
1 files changed, 258 insertions, 0 deletions
diff --git a/docs/scruf-howto.html b/docs/scruf-howto.html
new file mode 100644
index 0000000..09eb543
--- /dev/null
+++ b/docs/scruf-howto.html
@@ -0,0 +1,258 @@
+<!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>