/[svn]/doc/docbase/writing_docs/02_uploading_docs.html
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2753 - (show annotations) (download) (as text)
Wed Apr 29 11:42:26 2015 UTC (5 years, 6 months ago) by schoenebeck
File MIME type: text/html
File size: 9031 byte(s)
* Article "Uploading Docs":
  - Some more details about SVN commits added.

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">&lt;article&gt;</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>. This CSS file is taken verbatim as-is.
202 All files contained in subdirectories below the <code>tmpl</code> will
203 simply be copied as they are. So open <code>tmpl/index.html</code> on
204 your local machine with a web browser, modify the CSS files etc. until
205 you are modified with the look, and finally commit your changes to our
206 Subversion server.
207 </p>
208
209 <h3>What Next?</h3>
210 <p>
211 That's it!
212 If there is something unclear, or if you encounter any kind of problem,
213 please contact <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>.
214 </p>
215
216 </body>
217 </html>

  ViewVC Help
Powered by ViewVC