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>
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.
    </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>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>. This CSS file is taken verbatim as-is.
      All files contained in subdirectories below the <code>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 modified with the 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			<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>