1 |
schoenebeck |
2739 |
<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> |
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. |
79 |
|
|
</p> |
80 |
|
|
|
81 |
|
|
<h3>Error Detection</h3> |
82 |
|
|
<p> |
83 |
|
|
Our site's software will try to solve problems on its own as much as |
84 |
|
|
possible in order to avoid bothering you. However if your modifications |
85 |
|
|
introduced some kind of severe error which the software is not able to |
86 |
|
|
solve on its own, then you will automatically get an email concerning the |
87 |
|
|
problem introduced by you. In this case please resolve the issue manually |
88 |
|
|
as being told by the software and then commit your changes again. |
89 |
|
|
You will also get an automated email in this case once your new changes |
90 |
|
|
actually solved the problem(s) with a "everything is now back at normal" |
91 |
|
|
message. As long as there is a severe yet unresolved problem, the site's |
92 |
|
|
appearance will remain in the previous, last valid state. |
93 |
|
|
</p> |
94 |
|
|
|
95 |
|
|
<h3>Adding an Article</h3> |
96 |
|
|
<p> |
97 |
|
|
To add a new article for this site, simply add the new article's HTML |
98 |
|
|
file somewhere below the <code>docbase</code> directory. Please don't |
99 |
|
|
add the new file directly into the <code>docbase</code> directory, because |
100 |
|
|
in that particular directory there should always be only one HTML file |
101 |
|
|
(<code>root.html</code> - our site's front page). So rather create a |
102 |
|
|
new directory and add your new HTML file there, i.e. like this: |
103 |
|
|
</p> |
104 |
|
|
<dir>doc.ls.org |
105 |
|
|
<dir>docbase |
106 |
|
|
<dir class="new">my_new_article |
107 |
|
|
<file class="new">01_foo.html</file> |
108 |
|
|
<file class="new">some_picture.png</file> |
109 |
|
|
</dir> |
110 |
|
|
<file>root.html</file> |
111 |
|
|
</dir> |
112 |
|
|
<dir>tmpl</dir> |
113 |
|
|
</dir> |
114 |
|
|
<p> |
115 |
|
|
Neither the directory name <code>my_new_article</code>, nor the HTML |
116 |
|
|
file name <code>01_foo.html</code> will directly be exposed to the readers |
117 |
|
|
of this site. So the name of the directory is almost irrelevant regarding |
118 |
|
|
the precise URL name or article name. Only the directory structure |
119 |
|
|
(the tree) is relevant for the site, because it defines which article shall |
120 |
|
|
be located "under" which other article(s), which effectively defines its |
121 |
|
|
appearance in the navigation bar, as well as how the URL of the article |
122 |
|
|
is assembled. |
123 |
|
|
</p> |
124 |
|
|
<p> |
125 |
|
|
If you are writing an article that you want to be splitted into separate |
126 |
|
|
pages, or if you want to add articles that shall directly be associated with |
127 |
|
|
each other, then you can add them to the same directory like this: |
128 |
|
|
</p> |
129 |
|
|
<dir>doc.ls.org |
130 |
|
|
<dir>docbase |
131 |
|
|
<dir class="new">my_new_article |
132 |
|
|
<file class="new">01_foo.html</file> |
133 |
|
|
<file class="new">02_bar.html</file> |
134 |
|
|
<file class="new">03_some_more.html</file> |
135 |
|
|
<file class="new">some_picture.png</file> |
136 |
|
|
</dir> |
137 |
|
|
</dir> |
138 |
|
|
</dir> |
139 |
|
|
<p> |
140 |
|
|
Which will cause those articles to get "Next" and "Previous" buttons to |
141 |
|
|
browse between them conveniently. The prefixed numbers of the HTML |
142 |
|
|
files define the order in which they are linked with each other and |
143 |
|
|
appearing this way on our site. |
144 |
|
|
</p> |
145 |
|
|
<p> |
146 |
|
|
Once you are done, commit your new article(s) to our Subversion server: |
147 |
|
|
</p> |
148 |
|
|
<code> |
149 |
|
|
cd doc.ls.org/docbase |
150 |
|
|
svn add my_new_article |
151 |
|
|
svn commit |
152 |
|
|
</code> |
153 |
|
|
<p> |
154 |
|
|
So far you should only commit .html files and image files |
155 |
|
|
(.png, .jpg, .gif) to our Subversion server. All other files will be |
156 |
|
|
ignored. Please also make sure your images are not too large. |
157 |
|
|
</p> |
158 |
|
|
|
159 |
|
|
<h3>Changing the Look</h3> |
160 |
|
|
<p> |
161 |
|
|
If you just want to modify the look of your article, you may just add |
162 |
|
|
regular CSS code to your article's HTML source file. If you rather want to change |
163 |
|
|
the overall appearance of the entire website, then have a look at the previously |
164 |
|
|
mentioned <code>tmpl</code> directory. |
165 |
|
|
</p> |
166 |
|
|
<p> |
167 |
|
|
The <code>tmpl/index.html</code> file |
168 |
|
|
will be used by our site's software to generate all pages of this |
169 |
|
|
website, that is it takes that file as skeleton, and replaces its |
170 |
|
|
<code lang="html"><article></code> section with the |
171 |
|
|
respective content of the article's source HTML file. So that |
172 |
|
|
<code>tmpl/index.html</code> file defines the HTML code that will be generated |
173 |
|
|
for each page, which however is essentially just the data model of the page, |
174 |
|
|
not its actual appearance. Note that this file is a real HTML file, not |
175 |
|
|
a fragmented exotic file filled up with markers or something, like it is |
176 |
|
|
usually the case with template files of other systems. In other words: you can simply |
177 |
|
|
open <code>tmpl/index.html</code> with your web browser and immediately |
178 |
|
|
test your style changes locally before commiting them. |
179 |
|
|
</p> |
180 |
|
|
<p> |
181 |
|
|
The actual visual appearance (view) for the website is defined by the |
182 |
|
|
file <code>tmpl/css/main.css</code>. This CSS file is taken verbatim as-is. |
183 |
|
|
All files contained in subdirectories below the <code>tmpl</code> will |
184 |
|
|
simply be copied as they are. So open <code>tmpl/index.html</code> on |
185 |
|
|
your local machine with a web browser, modify the CSS files etc. until |
186 |
|
|
you are modified with the look, and finally commit your changes to our |
187 |
|
|
Subversion server. |
188 |
|
|
</p> |
189 |
|
|
|
190 |
|
|
<h3>What Next?</h3> |
191 |
|
|
<p> |
192 |
|
|
That's it! |
193 |
|
|
If there is something unclear, or if you encounter any kind of problem, |
194 |
|
|
please contact <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>. |
195 |
|
|
</p> |
196 |
|
|
|
197 |
|
|
</body> |
198 |
|
|
</html> |