docbase/writing_docs/02_uploading_docs.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>Uploading Docs</title>
    <meta name="description" content="Uploading articles for this site.">
    <link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">
    <script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>
    <style type="text/css"><!--
dir.new {
    color:#009c31;
}

file.new {
    color:#13c64b;
}
  --></style>
  </head>
  <body>
    <p>
      This article is intended for people who already have an user account for
      our Subversion server.
      It provides a short introduction about how to upload and manage articles
      for this site.
    </p>

    <h3>Subversion Repository</h3>
    <p>
      The source HTML files of all articles on this site, as well as all template
      files which make up the general look of this site, are contained and
      managed by our regular Subversion server. You may also 
      <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/doc/">browse the source article files</a>
      with our SVN server's web frontend.
    </p>
    <p>
      So to start, first checkout the SVN repository of this site:
    </p>
    <code lang="none">
svn co https://svn.linuxsampler.org/svn/doc doc.ls.org
    </code>
    <p>
      Now you have downloaded this site's source files with a directory
      structure that should look like this:
    </p>
    <dir>doc.ls.org
      <dir>docbase</dir>
      <dir>tmpl
        <dir>css</dir>
        <dir>fonts</dir>
        <dir>js</dir>
        <dir>pix</dir>
        <file>index.html</file>
      </dir>
    </dir>
    <p>
      The <code>docbase</code> directory contains all articles of this site
      (the content), whereas the <code>tmpl</code> directory contains all files
      which make up the look of this site (layout). Most notably the
      <code>index.html</code> file, in the directory structure shown above, is
      the main template file for this site.
    </p>

    <h3>Modifying an Article</h3>
    <p>
      To modify an existing article, simply open the respective HTML file
      (which is located somewhere below the <code>docbase</code> directory) with a
      text editor of your choice. You can preview the article locally with your
      web browser while doing your modifications. After you are done with your
      changes, simply commit the modified articles to our Subversion repository:
    </p>
    <code>
cd doc.ls.org
svn commit
    </code>
    <p>
      Like with commits regarding all our software projects, you must
      always supply a comment with each one of your Subversion commits.
      Once your files are commited successfully, our system will process the
      files and rebuild this site automatically. Note that changes regarding
      articles are also displayed on our <a href="http://www.linuxsampler.org">frontsite</a>.
      The same rules apply like with our other software commits, that is a SVN
      comment that begins with a star character like:
    </p>
    <code lang="none">
* Changed article "Foo".
    </code>
    <p>
      Will cause the commit to be displayed in the change log on our
      <a href="http://www.linuxsampler.org">frontsite</a>. If you omit the star
      like:
    </p>
    <code lang="none">
- Changed article "Foo".
    </code>
    <p>
      Then your article changes will be a "silent" commit and it will not be
      displayed on the frontsite. Please only use such silent commits for trivial
      changes, i.e. when fixing typos and other very trivial things like that.
    </p>

    <h3>Error Detection</h3>
    <p>
      Our site's software will try to solve problems on its own as much as
      possible in order to avoid bothering you. However if your modifications
      introduced some kind of severe error which the software is not able to
      solve on its own, then you will automatically get an email concerning the
      problem introduced by you. In this case please resolve the issue manually
      as being told by the software and then commit your changes again.
      You will also get an automated email in this case once your new changes
      actually solved the problem(s) with a "everything is now back at normal"
      message. As long as there is a severe yet unresolved problem, the site's
      appearance will remain in the previous, last valid state.
    </p>

    <h3>Adding an Article</h3>
    <p>
      To add a new article for this site, simply add the new article's HTML
      file somewhere below the <code>docbase</code> directory. Please don't
      add the new file directly into the <code>docbase</code> directory, because
      in that particular directory there should always be only one HTML file
      (<code>root.html</code> - our site's front page). So rather create a
      new directory and add your new HTML file there, i.e. like this:
    </p>
    <dir>doc.ls.org
      <dir>docbase
        <dir class="new">my_new_article
          <file class="new">01_foo.html</file>
          <file class="new">some_picture.png</file>
        </dir>
        <file>root.html</file>
      </dir>
      <dir>tmpl</dir>
    </dir>
    <p>
      Neither the directory name <code>my_new_article</code>, nor the HTML
      file name <code>01_foo.html</code> will directly be exposed to the readers
      of this site. So the name of the directory is almost irrelevant regarding
      the precise URL name or article name. Only the directory structure
      (the tree) is relevant for the site, because it defines which article shall
      be located "under" which other article(s), which effectively defines its
      appearance in the navigation bar, as well as how the URL of the article
      is assembled.
    </p>
    <p>
      If you are writing an article that you want to be splitted into separate
      pages, or if you want to add articles that shall directly be associated with
      each other, then you can add them to the same directory like this:
    </p>
    <dir>doc.ls.org
      <dir>docbase
        <dir class="new">my_new_article
          <file class="new">01_foo.html</file>
          <file class="new">02_bar.html</file>
          <file class="new">03_some_more.html</file>
          <file class="new">some_picture.png</file>
        </dir>
      </dir>
    </dir>
    <p>
      Which will cause those articles to get "Next" and "Previous" buttons to
      browse between them conveniently. The prefixed numbers of the HTML
      files define the order in which they are linked with each other and
      appearing this way on our site.
    </p>
    <p>
      Once you are done, commit your new article(s) to our Subversion server:
    </p>
    <code>
cd doc.ls.org/docbase
svn add my_new_article
svn commit
    </code>
    <p>
      So far you should only commit .html files and image files
      (.png, .jpg, .gif) to our Subversion server. All other files will be
      ignored. Please also make sure your images are not too large.
    </p>

    <h3>Changing the Look</h3>
    <p>
      If you just want to modify the look of your article, you may just add
      regular CSS code to your article's HTML source file. If you rather want to change
      the overall appearance of the entire website, then have a look at the previously
      mentioned <code>tmpl</code> directory.
    </p>
    <p>
      The <code>tmpl/index.html</code> file
      will be used by our site's software to generate all pages of this
      website, that is it takes that file as skeleton, and replaces its
      <code lang="html">&lt;article&gt;</code> section with the
      respective content of the article's source HTML file. So that
      <code lang="none">tmpl/index.html</code> file defines the HTML code that will be generated
      for each page, which however is essentially just the data model of the page,
      not its actual appearance. Note that this file is a real HTML file, not
      a fragmented exotic file filled up with markers or something, like it is
      usually the case with template files of other systems. In other words: you can simply
      open <code>tmpl/index.html</code> with your web browser and immediately
      test your style changes locally before commiting them.
    </p>
    <p>
      The actual visual appearance (view) for the website is defined by the
      file <code>tmpl/css/main.css</code>. That's because this CSS file is
      currently linked in the <code lang="html">&lt;head&gt;</code> section of
      our <code lang="none">tmpl/index.html</code> template file. So it is not
      hard coded in our software.
      This mentioned CSS file is taken verbatim as-is. That's because
      all files contained in subdirectories below the <code lang="none">tmpl</code> will
      simply be copied as they are. So open <code>tmpl/index.html</code> on
      your local machine with a web browser, modify the CSS files etc. until
      you are satisfied with the new look, and finally commit your changes to our
      Subversion server.
    </p>
    
    <h3>What Next?</h3>
    <p>
      That's it!
      If there is something unclear, or if you encounter any kind of problem,
      please contact <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>.
    </p>

  </body>
</html>
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	schoenebeck	2753	<code lang="none">
38	schoenebeck	2739	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	schoenebeck	2753	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	schoenebeck	2739	</p>
83	schoenebeck	2753	<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	schoenebeck	2739
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	schoenebeck	2753	<code lang="none">tmpl/index.html</code> file defines the HTML code that will be generated
192	schoenebeck	2739	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	schoenebeck	2754	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	schoenebeck	2739	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	schoenebeck	2758	you are satisfied with the new look, and finally commit your changes to our
210	schoenebeck	2739	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>