summaryrefslogtreecommitdiffstats
path: root/README
blob: 724e6568dbe6297a27161c66c0430a7bed5f306e (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
scruf 
=====

scruf is a simple program that converts marked up files to
corresponding valid HTML5 files.

The markup that is understood by scruf is called the "scruffy"
markup. To learn about the scruffy markup look at
manual/scruffy-markup.html file.

To get the up to date information about scruf, visit its homepage[1].

[1]: http://nongnu.org/scruf/

License
=======

scruf is free software[2] and it is licensed under the GNU General
Public License version 3 or later.

The COPYING file contains the full text of the GNU General Public
License version 3.

[2]: http://www.gnu.org/philosophy/free-sw.html

The style sheet, style.css, in styling/ is dedicated to the public
domain.

Platform
========

At present scruf can be used in GNU/Linux based operating
systems. Since scruf is written in Java, it might work on other
platforms like Windows, Mac, etc.

scruf was not test in platforms other than GNU/Linux, so it might not
work as it should in platforms other than GNU/Linux, even if it
compiles successfully.

Dependencies
============

To compile and run scruf, the OpenJDK[3] is need. Instructions are
provided in manual/scruf-howto.html on how to install the JDK.

[3]: http://openjdk.java.net

Installation
============

The source has to be compiled with the `javac' command, with that, the
installation is done. For instruction on compiling the scruf source,
see manual/scruf-howto.html.

Overview of the scruf source
============================

This section is for folks who wish to read/explore/hack/study/etc the
source code.

* Run.java : This is entry point for scruf. It contains the `main'
  function starts the nuts & bolts of scruf.

* parser/ : This directory contains all the `Parsers' and
  related classes. 
  
  The 'Parser' interface is defined in Parser.java and all parsers
  implement this interface. 

  The functionality of a Parser is to convert a specific scruffy
  markup into corresponding HTML5 element. For instance, the `Link'
  parser converts scruffy marked up links into corresponding HTML5
  links; The `CodeBlocks' parsers looks for code blocks in the marked up
  file and converts the block into a HTML5 code block. 

  `ParserList' class contains a list of all parsers that is used to
  convert a scruffy markup file to valid HTML5.

* conversion/ : Contains classes responsible for traversing
  directories looking for scruffy marked up files & feeding the marked
  up files to a list of parsers to convert into HTML5

  `ConvertDirectory' class recursively traverses a directories & when
  it finds a scruffy marked up file, it gives it to the `ConvertFile'
  class to perform HTML5 conversion.

  `ConvertFile' gets a scruffy marked up file and feeds the file to a
  list of parsers to convert to HTML5 and writes the converted HTML5
  file to the disk.

  	+ ignore/ : This directory contains a class which help identify
  	sub-directories that are to be ignored.

* index/ : Contains the `IndexCreator' class which adds links to newly
  converted HTML5 files to the directory's `index.scruffy' file

  `index.scruffy' is created in directories that have scruffy marked
  up files and it contains a list of links to all the HTML5 files
  converted by scruf.

* io/ : Contains classes for reading/writing files.

* status/ : Contains the `PresentFile' class which has the details
  about the marked up file that is being converted to HTML5.

  The `DirectoryInfo' class has the `level' of the directory being
  traversed with respect to the `root' directory.

  The `root' directory is the top level directory given by the user to
  perform HTML5 conversion.

* styling/ : This directory contains the StyleChecker class which
  makes sure that every directory, that has a scruffy marked up file,
  contains a dedicated style sheet -- style.css.

  The style.css is the default style sheet used by scruf.

* docs/ directory: Contains documentation on how to install and use
  scruf.

Mailing List
============

All public discussion regarding the scruf project happens in the
scruf-friends[4] mailing list.

If you want help or have issues using scruf or wish to contribute to
the scruf project or desire to give vent to your thoughts about scruf,
the scruf-friends[4] list is the right place.

[4]: https://lists.nongnu.org/mailman/listinfo/scruf-friends

Report a Bug
============

Found scruf has gone bonkers or it is not working the way it has to?
Just file a bug report[5] about it. Please also provide your contact
information if it is required.

[5]: http://savannah.nongnu.org/bugs/?group=scruf&func=additem

Author
======

scruf is authored & maintained by rsiddharth
<rsiddharth@ninthfloor.org>.