diff options
Diffstat (limited to 'docs/scruf-howto.html')
-rw-r--r-- | docs/scruf-howto.html | 258 |
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.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> |