- - - -

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 -