summaryrefslogtreecommitdiffstats
path: root/docs/scruf-howto.html
blob: 09eb543b066b2abba9d5e3f549e84155590abc15 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
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>