+ + + +

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 +

+ + + +

the scruffy markup

+ +

+ scruffy is the markup that is understood by scruf. +

+ +

+All scruffy marked up documents must have a .scruffy extension +-- that is how scruf comes to know that a particular file is, indeed, +a scruffy document. +

+ +

+The following sections will get you acquainted with the scruffy +markup. +

+ +

meta things

+ +

+First things first. At the beginning of the scruffy document, it +is required to specify some meta things -- the document title & the +author of the document. +

+ +

+This is how it is done. +

+ +

meta-title: Title of Your Document
meta-author: Author

+ +

document date

+ +

+To specify the date of creation of the document, surround the date +with a pair of $$$. +

+ +

$$$ 1 January, 1984 $$$

+ +

+It can be made verbose too. +

+ +

$$$ Posted on 1 January, 1984 $$$

+ + +

headings

+ +

+The mark-up for specifying the heading is the clumsiest of all. Now is +the time to hate scruffy for what it is. +

+ +

+To specify a <h1> heading, surround the heading string with a pair +of 10 equals sign(=). +

+ +

==========
Heading 1
==========

+ +

+For a <h2> heading, the heading string is surrounded by a pair of +20 equals sign. +

+ +

====================
Heading 2
====================

+ +

+So the math is: +

+ +

no of equals signs = ((heading size) * 10)

+ +

+For <h3> (head size is 3), the number of equals signs is equal to +30. Therefore, a to get a <h3> heading, the heading string should +be surrounded by a pair of 30 equals signs. +

+ +

paragraphs

+ +

+Paragraphs are delimited by a blank line. +

+ +

foo is good at drinking.

bar loves to hack code.

+ +

+The above two lines are converted to: +

+ +

<p> foo is good at drinking.</p>

<p> bar loves to hack code.</p>

+ +

word decoration

+ +

+ Bold text is surrounded by three singles quotes('''). +

+ +

'''This text will be in bold'''

+ + +

+ Italic text is surrounded by two single quotes(''). +

+ +

''This text will be italicized''

+ +

+ Underlined text is surrounded by two underscores (__). +

+ +

__This text will be underlined__

+ +

+Text may be monopspaced too, it is done by surrounding the text with +` symbol. +

+ +

`monospaced text`

+ +

+If the beginning of the text, in a paragraph, is decorated, +then, please remember to leave a space before starting the +paragraph. +

+ +

''This paragraph is'' decorated at the beginning with italics,
so, a space is left before starting the paragraph.

+ +

code blocks

+ +

+When it is desired to illustrate code or show verbatim text, the text +or code is put around a pair of ###. +

+ +

###

#include <beer.h>

void main() {
beer lager;
lager.drink();
return;
}

###

+ +

+Text inside code blocks cannot be marked up, as all special +characters are converted into their corresponding HTML number inside a +code block. +

+ +

+All through this document, those grayscaled blocks of text are, +indeed, code blocks. +

+ +

block quote

+ +

+A block of text is blockquoted when it is surrounded by %%% +string. +

+ +

%%%

The is phrase is fain to be blockquoted by scruf.

%%%

+ +

links

+ +

+The markup for links is very similar to +MoinMoin's markup +for links: +

+ +

[[http://en.wikipedia.org/wiki/Special:Random|Wikipedia Random Article]]

+ +

+As seen above, the link block is surround by [[ & ]]. The +first part inside the link block is the link and the second part +(which is optional) is a description of the link. The two parts of the +link block is separated by a | (pipe) symbol. +

+ +

+The pipe symbol (|) is eliminated from the link block, if the +link description is not specified. +

+ +

+The HTML form of the above link block will look like: +

+ +

<a href="http://en.wikipedia.org/wiki/Special:Random"> Wikipedia Random Article </a>

+ +

images

+ +

+The markup for the image block looks like this: +

+ +

+As seen above, the image block is enclosed with {{ & }}. The +first part of the image block is the path to the location where +the image stored. The second part (which is optional) is a textual +description of the image. The textual description is what that is +shown when the image cannot be displayed in the browser(text-only +browsers, for instance). +

+ +

+The two parts of the image block is separated by the | (pipe) +symbol. The pipe symbol is eliminated, if the textual description of +the image is not specified. +

+ +

audio

+ +

+scruf uses HTML5 <audio> tag to embed audio. +

+ +

+The markup for embedding audio: +

+ +

+As seen above, the audio block is enclosed with {{ & +}}. Inside the braces, the audio block starts with audio: +followed by the path to the audio file. +

+ +

+At present, there is support for only Ogg Vorbis audio. +

+ +

footer

+ +

+The author's name and copyright information may be placed inside the +footer block. This block, as the name implies, is put at the end +of the document. +

+ +

----------------------------------------------------------------------
written by Audacius Scrooge. It is licensed under CC-BY-SA
----------------------------------------------------------------------

+ +

+The footer block is enclosed by a pair of seventy hyphens +(-). +

+ +

+In Emacs, the whopping seventy hyphens can be generated with a C-u 70 +-. +

+ +

have problems?

+ +

+If there are/is any issue(s) with understanding the scruffy +markup. Please subscribe & send an email to the +scruf-friends +mailing list. That way we can solve your problem together. +

+ +

+go back to the scruf-howto. +

+ + + + + +

+ + source +

+ back +