ViewVC logotype

Contents of /doc/docbase/writing_docs/02_uploading_docs.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 2739 - (show annotations) (download) (as text)
Tue Apr 28 19:33:56 2015 UTC (8 years, 11 months ago) by schoenebeck
File MIME type: text/html
File size: 8199 byte(s)
* New article: "Uploading Articles".

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 }
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>
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>
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>
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>
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>
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">&lt;article&gt;</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>
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>
197 </body>
198 </html>

  ViewVC Help
Powered by ViewVC