1 |
<html> |
2 |
<head> |
3 |
<meta name="author" content="Christian Schoenebeck"> |
4 |
<title>Uploading Docs</title> |
5 |
<meta name="description" content="Uploading articles for this site."> |
6 |
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
7 |
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
8 |
<style type="text/css"><!-- |
9 |
dir.new { |
10 |
color:#009c31; |
11 |
} |
12 |
|
13 |
file.new { |
14 |
color:#13c64b; |
15 |
} |
16 |
--></style> |
17 |
</head> |
18 |
<body> |
19 |
<p> |
20 |
This article is intended for people who already have an user account for |
21 |
our Subversion server. |
22 |
It provides a short introduction about how to upload and manage articles |
23 |
for this site. |
24 |
</p> |
25 |
|
26 |
<h3>Subversion Repository</h3> |
27 |
<p> |
28 |
The source HTML files of all articles on this site, as well as all template |
29 |
files which make up the general look of this site, are contained and |
30 |
managed by our regular Subversion server. You may also |
31 |
<a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/doc/">browse the source article files</a> |
32 |
with our SVN server's web frontend. |
33 |
</p> |
34 |
<p> |
35 |
So to start, first checkout the SVN repository of this site: |
36 |
</p> |
37 |
<code lang="none"> |
38 |
svn co https://svn.linuxsampler.org/svn/doc doc.ls.org |
39 |
</code> |
40 |
<p> |
41 |
Now you have downloaded this site's source files with a directory |
42 |
structure that should look like this: |
43 |
</p> |
44 |
<dir>doc.ls.org |
45 |
<dir>docbase</dir> |
46 |
<dir>tmpl |
47 |
<dir>css</dir> |
48 |
<dir>fonts</dir> |
49 |
<dir>js</dir> |
50 |
<dir>pix</dir> |
51 |
<file>index.html</file> |
52 |
</dir> |
53 |
</dir> |
54 |
<p> |
55 |
The <code>docbase</code> directory contains all articles of this site |
56 |
(the content), whereas the <code>tmpl</code> directory contains all files |
57 |
which make up the look of this site (layout). Most notably the |
58 |
<code>index.html</code> file, in the directory structure shown above, is |
59 |
the main template file for this site. |
60 |
</p> |
61 |
|
62 |
<h3>Modifying an Article</h3> |
63 |
<p> |
64 |
To modify an existing article, simply open the respective HTML file |
65 |
(which is located somewhere below the <code>docbase</code> directory) with a |
66 |
text editor of your choice. You can preview the article locally with your |
67 |
web browser while doing your modifications. After you are done with your |
68 |
changes, simply commit the modified articles to our Subversion repository: |
69 |
</p> |
70 |
<code> |
71 |
cd doc.ls.org |
72 |
svn commit |
73 |
</code> |
74 |
<p> |
75 |
Like with commits regarding all our software projects, you must |
76 |
always supply a comment with each one of your Subversion commits. |
77 |
Once your files are commited successfully, our system will process the |
78 |
files and rebuild this site automatically. Note that changes regarding |
79 |
articles are also displayed on our <a href="http://www.linuxsampler.org">frontsite</a>. |
80 |
The same rules apply like with our other software commits, that is a SVN |
81 |
comment that begins with a star character like: |
82 |
</p> |
83 |
<code lang="none"> |
84 |
* Changed article "Foo". |
85 |
</code> |
86 |
<p> |
87 |
Will cause the commit to be displayed in the change log on our |
88 |
<a href="http://www.linuxsampler.org">frontsite</a>. If you omit the star |
89 |
like: |
90 |
</p> |
91 |
<code lang="none"> |
92 |
- Changed article "Foo". |
93 |
</code> |
94 |
<p> |
95 |
Then your article changes will be a "silent" commit and it will not be |
96 |
displayed on the frontsite. Please only use such silent commits for trivial |
97 |
changes, i.e. when fixing typos and other very trivial things like that. |
98 |
</p> |
99 |
|
100 |
<h3>Error Detection</h3> |
101 |
<p> |
102 |
Our site's software will try to solve problems on its own as much as |
103 |
possible in order to avoid bothering you. However if your modifications |
104 |
introduced some kind of severe error which the software is not able to |
105 |
solve on its own, then you will automatically get an email concerning the |
106 |
problem introduced by you. In this case please resolve the issue manually |
107 |
as being told by the software and then commit your changes again. |
108 |
You will also get an automated email in this case once your new changes |
109 |
actually solved the problem(s) with a "everything is now back at normal" |
110 |
message. As long as there is a severe yet unresolved problem, the site's |
111 |
appearance will remain in the previous, last valid state. |
112 |
</p> |
113 |
|
114 |
<h3>Adding an Article</h3> |
115 |
<p> |
116 |
To add a new article for this site, simply add the new article's HTML |
117 |
file somewhere below the <code>docbase</code> directory. Please don't |
118 |
add the new file directly into the <code>docbase</code> directory, because |
119 |
in that particular directory there should always be only one HTML file |
120 |
(<code>root.html</code> - our site's front page). So rather create a |
121 |
new directory and add your new HTML file there, i.e. like this: |
122 |
</p> |
123 |
<dir>doc.ls.org |
124 |
<dir>docbase |
125 |
<dir class="new">my_new_article |
126 |
<file class="new">01_foo.html</file> |
127 |
<file class="new">some_picture.png</file> |
128 |
</dir> |
129 |
<file>root.html</file> |
130 |
</dir> |
131 |
<dir>tmpl</dir> |
132 |
</dir> |
133 |
<p> |
134 |
Neither the directory name <code>my_new_article</code>, nor the HTML |
135 |
file name <code>01_foo.html</code> will directly be exposed to the readers |
136 |
of this site. So the name of the directory is almost irrelevant regarding |
137 |
the precise URL name or article name. Only the directory structure |
138 |
(the tree) is relevant for the site, because it defines which article shall |
139 |
be located "under" which other article(s), which effectively defines its |
140 |
appearance in the navigation bar, as well as how the URL of the article |
141 |
is assembled. |
142 |
</p> |
143 |
<p> |
144 |
If you are writing an article that you want to be splitted into separate |
145 |
pages, or if you want to add articles that shall directly be associated with |
146 |
each other, then you can add them to the same directory like this: |
147 |
</p> |
148 |
<dir>doc.ls.org |
149 |
<dir>docbase |
150 |
<dir class="new">my_new_article |
151 |
<file class="new">01_foo.html</file> |
152 |
<file class="new">02_bar.html</file> |
153 |
<file class="new">03_some_more.html</file> |
154 |
<file class="new">some_picture.png</file> |
155 |
</dir> |
156 |
</dir> |
157 |
</dir> |
158 |
<p> |
159 |
Which will cause those articles to get "Next" and "Previous" buttons to |
160 |
browse between them conveniently. The prefixed numbers of the HTML |
161 |
files define the order in which they are linked with each other and |
162 |
appearing this way on our site. |
163 |
</p> |
164 |
<p> |
165 |
Once you are done, commit your new article(s) to our Subversion server: |
166 |
</p> |
167 |
<code> |
168 |
cd doc.ls.org/docbase |
169 |
svn add my_new_article |
170 |
svn commit |
171 |
</code> |
172 |
<p> |
173 |
So far you should only commit .html files and image files |
174 |
(.png, .jpg, .gif) to our Subversion server. All other files will be |
175 |
ignored. Please also make sure your images are not too large. |
176 |
</p> |
177 |
|
178 |
<h3>Changing the Look</h3> |
179 |
<p> |
180 |
If you just want to modify the look of your article, you may just add |
181 |
regular CSS code to your article's HTML source file. If you rather want to change |
182 |
the overall appearance of the entire website, then have a look at the previously |
183 |
mentioned <code>tmpl</code> directory. |
184 |
</p> |
185 |
<p> |
186 |
The <code>tmpl/index.html</code> file |
187 |
will be used by our site's software to generate all pages of this |
188 |
website, that is it takes that file as skeleton, and replaces its |
189 |
<code lang="html"><article></code> section with the |
190 |
respective content of the article's source HTML file. So that |
191 |
<code lang="none">tmpl/index.html</code> file defines the HTML code that will be generated |
192 |
for each page, which however is essentially just the data model of the page, |
193 |
not its actual appearance. Note that this file is a real HTML file, not |
194 |
a fragmented exotic file filled up with markers or something, like it is |
195 |
usually the case with template files of other systems. In other words: you can simply |
196 |
open <code>tmpl/index.html</code> with your web browser and immediately |
197 |
test your style changes locally before commiting them. |
198 |
</p> |
199 |
<p> |
200 |
The actual visual appearance (view) for the website is defined by the |
201 |
file <code>tmpl/css/main.css</code>. That's because this CSS file is |
202 |
currently linked in the <code lang="html"><head></code> section of |
203 |
our <code lang="none">tmpl/index.html</code> template file. So it is not |
204 |
hard coded in our software. |
205 |
This mentioned CSS file is taken verbatim as-is. That's because |
206 |
all files contained in subdirectories below the <code lang="none">tmpl</code> will |
207 |
simply be copied as they are. So open <code>tmpl/index.html</code> on |
208 |
your local machine with a web browser, modify the CSS files etc. until |
209 |
you are modified with the look, and finally commit your changes to our |
210 |
Subversion server. |
211 |
</p> |
212 |
|
213 |
<h3>What Next?</h3> |
214 |
<p> |
215 |
That's it! |
216 |
If there is something unclear, or if you encounter any kind of problem, |
217 |
please contact <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>. |
218 |
</p> |
219 |
|
220 |
</body> |
221 |
</html> |