Uploading Docs

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.

Subversion Repository

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 browse the source article files with our SVN server's web frontend.

So to start, first checkout the SVN repository of this site:

Now you have downloaded this site's source files with a directory structure that should look like this:

The docbase directory contains all articles of this site (the content), whereas the tmpl directory contains all files which make up the look of this site (layout). Most notably the index.html file, in the directory structure shown above, is the main template file for this site.

Modifying an Article

To modify an existing article, simply open the respective HTML file (which is located somewhere below the docbase 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:

• cd doc.ls.org
• svn commit

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 frontsite. The same rules apply like with our other software commits, that is a SVN comment that begins with a star character like:

Will cause the commit to be displayed in the change log on our frontsite. If you omit the star like:

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.

Error Detection

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.

Adding an Article

To add a new article for this site, simply add the new article's HTML file somewhere below the docbase directory. Please don't add the new file directly into the docbase directory, because in that particular directory there should always be only one HTML file (root.html - our site's front page). So rather create a new directory and add your new HTML file there, i.e. like this:

Neither the directory name my_new_article, nor the HTML file name 01_foo.html 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.

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:

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.

Once you are done, commit your new article(s) to our Subversion server:

• cd doc.ls.org/docbase
• svn add my_new_article
• svn commit

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.

Changing the Look

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 tmpl directory.

The tmpl/index.html 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 <article> section with the respective content of the article's source HTML file. So that tmpl/index.html 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 tmpl/index.html with your web browser and immediately test your style changes locally before commiting them.

The actual visual appearance (view) for the website is defined by the file tmpl/css/main.css. That's because this CSS file is currently linked in the <head> section of our tmpl/index.html 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 tmpl will simply be copied as they are. So open tmpl/index.html 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.

What Next?

That's it! If there is something unclear, or if you encounter any kind of problem, please contact Christian.

• Writing Docs
• LinuxSampler Documents