1 |
schoenebeck |
2732 |
<html> |
2 |
|
|
<head> |
3 |
|
|
<meta name="author" content="Christian Schoenebeck"> |
4 |
|
|
<title>Writing Docs</title> |
5 |
|
|
<meta name="description" content="Writing new articles for this site."> |
6 |
|
|
</head> |
7 |
|
|
<body> |
8 |
|
|
<p> |
9 |
|
|
This article provides a short introduction about how to write documents |
10 |
|
|
for this site. We appreciate any volunteers trying to help us writing |
11 |
|
|
documentation for LinuxSampler and friends. |
12 |
|
|
</p> |
13 |
|
|
|
14 |
|
|
<h3>At a Glance</h3> |
15 |
|
|
<p> |
16 |
|
|
There are plenty of documentation systems out there. Why did we need yet |
17 |
|
|
another one? Most of those systems require you to learn some kind of custom, |
18 |
|
|
exotic markup language to write documents with them. Then there are |
19 |
|
|
<i title="<u><b>W</b>hat <b>Y</b>ou <b>S</b>ee <b>I</b>s <b>W</b>hat <b>Y</b>ou <b>G</b>et:</u> A system that immediately shows you the result while creating content."> |
20 |
|
|
WYSIWG |
21 |
|
|
</i> systems which require to maintain user accounts for people who want to |
22 |
|
|
add or change content and are suffering under periodic security issues, |
23 |
|
|
which in turn require frequent software updates to avoid the site getting |
24 |
|
|
compromised. And last but not least; they don't deliver everything you |
25 |
|
|
need and are often hard to extend or to be customized. |
26 |
|
|
</p> |
27 |
|
|
<p> |
28 |
|
|
<img src="new_article.png" style="height:112px; margin-right:15px;"> |
29 |
|
|
This site is using one of the best, most flexible, and well known markup |
30 |
|
|
languages as basis for writing documents: |
31 |
|
|
<a href="http://en.wikipedia.org/wiki/HTML">HTML</a>. But obviously there |
32 |
|
|
are some caveats to use HTML as-is. Most notably it requires you to write |
33 |
|
|
a lot of monothonic, superfluous things again and again just to achieve |
34 |
|
|
simple things. And on the other hand it requires authors to invest a |
35 |
|
|
substantial amount of time learning the numerous required aspects of HTML |
36 |
|
|
and <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets">CSS</a>. |
37 |
|
|
Fortunately; you don't have to. You don't need to have any precognition |
38 |
|
|
of HTML or CSS to write articles for this site. |
39 |
|
|
</p> |
40 |
|
|
<p> |
41 |
|
|
Here are some of the features of our documentation system in overview: |
42 |
|
|
<ul> |
43 |
|
|
<li> |
44 |
|
|
Articles are created as plain and extremely simple HTML files, which |
45 |
|
|
do not neccessarily require any previous knowledge in HTML |
46 |
|
|
(or even CSS) by article authors. |
47 |
|
|
</li> |
48 |
|
|
<li> |
49 |
|
|
The article's HTML file can immediately be previewed on the author's |
50 |
|
|
local computer by just opening it with a browser. No upload or web |
51 |
|
|
application required while creating or editing articles. |
52 |
|
|
</li> |
53 |
|
|
<li> |
54 |
|
|
Once the article is ready, it can be submitted to our server, which |
55 |
|
|
will then be filled up automatically by our software to generate our |
56 |
|
|
documentation site. The software performs all redundant work that is |
57 |
|
|
usually required to build websites with regular HTML files. This |
58 |
|
|
automatic generation supports the following features: |
59 |
|
|
<ol> |
60 |
|
|
<li> |
61 |
|
|
Automatic generation of the site's article structure. The site's |
62 |
|
|
structure can very easily be changed, by just moving around the |
63 |
|
|
article source HTML files in the article source repository. No single |
64 |
|
|
article needs to be edited for any site structure changes. |
65 |
|
|
</li> |
66 |
|
|
<li> |
67 |
|
|
Automatic correction of links and image references in articles, |
68 |
|
|
i.e. on site structure changes, trivial input errors or file type |
69 |
|
|
changes. No user interventation required. |
70 |
|
|
</li> |
71 |
|
|
<li> |
72 |
|
|
Automatic syntax highlighting of source code snippets in articles, |
73 |
|
|
so the author can concentrate simply on the content and correctness |
74 |
|
|
of his source code snippets. The software |
75 |
|
|
generates the correct look of your source code examples for you. |
76 |
|
|
</li> |
77 |
|
|
<li> |
78 |
|
|
Automatic generation of site's navigation bar, article's table of |
79 |
|
|
contents and article section IDs for the entire website. |
80 |
|
|
</li> |
81 |
|
|
<li> |
82 |
|
|
Automated generation of tooltips for links to other articles and |
83 |
|
|
technical terms or abbreviations. |
84 |
|
|
</li> |
85 |
|
|
<li> |
86 |
|
|
Automatic detection of fundamental errors in articles. Our system |
87 |
|
|
tries to correct any kind of issues automatically as much and as far |
88 |
|
|
as possible, in order to avoid bothering article authors with any kind of trivial |
89 |
|
|
things. However there are cases where it simply cannot resolve |
90 |
|
|
issues with individual articles on its own, even not by "guessing". |
91 |
|
|
In this case it will notify the author(s) about the precise problem, |
92 |
|
|
so they are aware about it and asks them to do the manual correction. |
93 |
|
|
</li> |
94 |
|
|
<li> |
95 |
|
|
This site's software is written in native C++, it generates and |
96 |
|
|
updates the entire site extremely fast. And since it is only |
97 |
|
|
updating the site's files when some input article changed, it can |
98 |
|
|
also be run as unpriviliged user and/or in a sandbox environment. |
99 |
|
|
</li> |
100 |
|
|
</ol> |
101 |
|
|
</li> |
102 |
|
|
<li> |
103 |
|
|
The site's template is a regular, static HTML file. So you can edit and |
104 |
|
|
test the site's overall look with a regular browser. No need to comment |
105 |
|
|
in/out things just for changing the general look of the site. |
106 |
|
|
</li> |
107 |
|
|
<li> |
108 |
|
|
Extensible: all articles are still real HTML after all. So you can |
109 |
|
|
easily add any kind of HTML, CSS and Java Script on your own for |
110 |
|
|
individual articles of yours if really required. So it is not neccessarily |
111 |
|
|
required to change our site's software just to add some kind of customization |
112 |
|
|
for some of your articles. |
113 |
|
|
</li> |
114 |
|
|
</ul> |
115 |
|
|
</p> |
116 |
|
|
<p> |
117 |
|
|
Enough said, let's dive in and actually see how to create an article. |
118 |
|
|
</p> |
119 |
|
|
|
120 |
|
|
<h2>A Base Article</h2> |
121 |
|
|
<p> |
122 |
|
|
Creating a new article for this site is as simple as creating a new text |
123 |
|
|
file and adding following text: |
124 |
|
|
</p> |
125 |
|
|
<code l="html"> |
126 |
|
|
<h1>My First Article</h1> |
127 |
|
|
<p> |
128 |
|
|
This is the first paragraph. |
129 |
|
|
</p> |
130 |
|
|
</code> |
131 |
|
|
<p> |
132 |
|
|
This would already be sufficient to be a valid document and all the rest |
133 |
|
|
would automatically be added by our site's software for you. It is |
134 |
|
|
recommended though to start new documents always with following template |
135 |
|
|
instead: |
136 |
|
|
</p> |
137 |
|
|
<code> |
138 |
|
|
<html> |
139 |
|
|
<head> |
140 |
|
|
<title>??article-title??</title> |
141 |
|
|
<meta name="author" content="??author-name??"> |
142 |
|
|
<meta name="description" content="??short-description??"> |
143 |
|
|
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
144 |
|
|
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
145 |
|
|
</head> |
146 |
|
|
<body> |
147 |
|
|
<h1>??article-headline??</h1> |
148 |
|
|
<p> |
149 |
|
|
This is the first paragraph. |
150 |
|
|
</p> |
151 |
|
|
</body> |
152 |
|
|
</html> |
153 |
|
|
</code> |
154 |
|
|
<p> |
155 |
|
|
Add this to an empty text file and rename the file to a HTML file with |
156 |
|
|
arbitrary name like <code>my_first_article.html</code>. |
157 |
|
|
That template above has the advantage that you can simply open that file |
158 |
|
|
locally on your machine with your web browser and immediately preview how |
159 |
|
|
the article will look like on our website while you are writing the |
160 |
|
|
article. So you don't need to upload it somewhere for that purpose. |
161 |
|
|
</p> |
162 |
|
|
<p> |
163 |
|
|
Don't worry, you don't need to understand everything that's there. All you |
164 |
|
|
need to know is described next. |
165 |
|
|
</p> |
166 |
|
|
|
167 |
|
|
<h3>Article Short Description</h3> |
168 |
|
|
<p> |
169 |
|
|
You may provide a short description of your article with |
170 |
|
|
<code>??short-description??</code>. This is completely optional. It is used |
171 |
|
|
for example when your article is linked from another article. In that |
172 |
|
|
case the reader may i.e. move the mouse pointer over the link and a tooltip |
173 |
|
|
will popup with the document's title and the short description as summary |
174 |
|
|
of what that article is about. |
175 |
|
|
</p> |
176 |
|
|
|
177 |
|
|
<h3>Article Title</h3> |
178 |
|
|
<p> |
179 |
|
|
With <code>??article-title??</code> you provide the title of the article, |
180 |
|
|
which will be displayed in the browser's window title bar and it will also |
181 |
|
|
be displayed on our site's horizontal navigation bar, which you can find |
182 |
|
|
at the top of each page. It will also be used by our site to auto generate |
183 |
|
|
a directory structure for the generated website, thus it also has an |
184 |
|
|
impact on the final <i>URL</i> of your article. |
185 |
|
|
</p> |
186 |
|
|
<p> |
187 |
|
|
With <code>??article-headline??</code> you define the prominent headline |
188 |
|
|
shown at the very beginning of the article. |
189 |
|
|
</p> |
190 |
|
|
<p> |
191 |
|
|
In most cases <code>??article-title??</code> and |
192 |
|
|
<code>??article-headline??</code> will probably be the same text for one |
193 |
|
|
article. In that case you may also omit either one of the two. The |
194 |
|
|
software will then automatically add the missing headline or title for |
195 |
|
|
you. |
196 |
|
|
</p> |
197 |
|
|
<p> |
198 |
|
|
In some few cases you may want to have more control over the aspects of |
199 |
|
|
the article's title, its final URL path and what shall be displayed in |
200 |
|
|
the navigation bar. In this case you may use some additional optional tags |
201 |
|
|
in your document's head like this: |
202 |
|
|
</p> |
203 |
|
|
<code> |
204 |
|
|
<html> |
205 |
|
|
<head> |
206 |
|
|
<title>??article-title??</title> <!-- article's title --> |
207 |
|
|
|
208 |
|
|
<urlpath>??article-path??</urlpath> <!-- article's directory (in URL path) --> |
209 |
|
|
|
210 |
|
|
<navpath>??nav-bar-name??</navpath> <!-- article's name in navigation bar --> |
211 |
|
|
|
212 |
|
|
<meta name="author" content="John Smith"> |
213 |
|
|
<meta name="description" content="This is my first article."> |
214 |
|
|
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
215 |
|
|
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
216 |
|
|
</head> |
217 |
|
|
<body> |
218 |
|
|
<h1>??article-headline??</h1> |
219 |
|
|
<p> |
220 |
|
|
This is the first paragraph. |
221 |
|
|
</p> |
222 |
|
|
</body> |
223 |
|
|
</html> |
224 |
|
|
</code> |
225 |
|
|
<p> |
226 |
|
|
In this case, <code>??article-title??</code> is now only used for displaying the |
227 |
|
|
article's name in the browser's title bar and in case the reader |
228 |
|
|
bookmarks your article with his browser. |
229 |
|
|
<code>??article-path??</code> is the directory |
230 |
|
|
name where the final, generated article shall be place at. Accordingly |
231 |
|
|
this also changes the final URL to the article. And last but not least, |
232 |
|
|
<code>??nav-bar-name??</code> defines the name of your article as it shall |
233 |
|
|
be displayed on the site's navigation bar. As said, these additional tags |
234 |
|
|
are completely optional. In most cases you should be fine by just providing |
235 |
|
|
a <code><title></code> and/or <code><h1></code> with your |
236 |
|
|
article. |
237 |
|
|
</p> |
238 |
|
|
|
239 |
|
|
<h3>Article Authors</h3> |
240 |
|
|
<p> |
241 |
|
|
Also completely optional is providing <code>??author-name??</code> as |
242 |
|
|
name(s) of the person(s) who wrote the article. If you provide that information, |
243 |
|
|
then the name will be displayed in the footer section of the article on |
244 |
|
|
our site. Don't be shy and add your name to get credited for your work. |
245 |
|
|
If you change an already existing article, you may simply add your name |
246 |
|
|
by adding a comma like so: |
247 |
|
|
</p> |
248 |
|
|
<code> |
249 |
|
|
<meta name="author" content="John Doe, Bob Fox, Mary Smith"> |
250 |
|
|
</code> |
251 |
|
|
<p> |
252 |
|
|
The author information may also be useful for people to contact the person |
253 |
|
|
who wrote the original article in order to ask some questions about it. |
254 |
|
|
</p> |
255 |
|
|
|
256 |
|
|
<h2>Headlines</h2> |
257 |
|
|
<p> |
258 |
|
|
All headlines in your article are defined with regular HTML headline |
259 |
|
|
tags. The following three headline types are available: |
260 |
|
|
</p> |
261 |
|
|
<ol> |
262 |
|
|
<li><code><h1>??article-headline??</h1></code> Like described in the |
263 |
|
|
previous section, a <code><h1></code> headline is the most prominent |
264 |
|
|
headline of your article. It should only be used once; at the very |
265 |
|
|
beginning of your article to display the general topic of the article. |
266 |
|
|
</li> |
267 |
|
|
<li><code><h2>??sub-headline??</h2></code> This headline type is a bit |
268 |
|
|
less prominent than a <code><h1></code> headline. You may use |
269 |
|
|
<code><h2></code> headlines to introduce important sections |
270 |
|
|
of your article. |
271 |
|
|
</li> |
272 |
|
|
<li><code><h3>??sub-sub-headline??</h3></code> This is the least |
273 |
|
|
prominent headline type. You may use it to further subdivide your |
274 |
|
|
article in smaller sections. |
275 |
|
|
</li> |
276 |
|
|
</ol> |
277 |
|
|
<p> |
278 |
|
|
This is the corresponding look for each one of the three headline types: |
279 |
|
|
</p> |
280 |
|
|
<example> |
281 |
|
|
<h1>This is a <h1> headline</h1> |
282 |
|
|
<h2>This is a <h2> headline</h2> |
283 |
|
|
<h3>This is a <h3> headline</h3> |
284 |
|
|
</example> |
285 |
|
|
<p> |
286 |
|
|
It's completely up to you which one of those three headline types to use, |
287 |
|
|
how often you use them and where. All of them will be taken by the site's |
288 |
|
|
software to automatically generate a table of content of your Article, |
289 |
|
|
which will be shown at the left side next to your article on our site. |
290 |
|
|
</p> |
291 |
|
|
<p> |
292 |
|
|
Once your article is uploaded to our site, IDs for the individual |
293 |
|
|
headlines will automatically be generated for you. If for example you had |
294 |
|
|
somewhere in your article a headline called "Conclusion of Topic", then |
295 |
|
|
this particular paragraph of your article may be directly linked to from |
296 |
|
|
other articles or other sites with an URL like |
297 |
|
|
<code>http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic</code>. |
298 |
|
|
If you want to override this behavior, because you rather want to use your |
299 |
|
|
own ID for a paragraph of your article, then simply set the desired ID with |
300 |
|
|
your headline: |
301 |
|
|
</p> |
302 |
|
|
<code> |
303 |
|
|
<h3 id="my_conclusion">Conclusion of topic</h3> |
304 |
|
|
</code> |
305 |
|
|
|
306 |
|
|
<h2>Paragraphs</h2> |
307 |
|
|
<p> |
308 |
|
|
You should wrap each continous text block of your article in between |
309 |
|
|
a paragraph tag pair like: |
310 |
|
|
</p> |
311 |
|
|
<code> |
312 |
|
|
<p> |
313 |
|
|
This is a paragraph. All the text in a paragraph is combined to one continous |
314 |
|
|
text block. You may add as much text as you want to a paragraph of your article, |
315 |
|
|
but better separate you article into logical parts of separate paragraphs. So to start a |
316 |
|
|
new paragraph, wrap the next text block into a new pair of paragraph tags. |
317 |
|
|
</p> |
318 |
|
|
<p> |
319 |
|
|
This is the next paragraph. There will be an empty line between this paragraph and |
320 |
|
|
the previous and next paragraph, to separate paragraphs visually from each other. |
321 |
|
|
</p> |
322 |
|
|
</code> |
323 |
|
|
<p> |
324 |
|
|
Which would look like: |
325 |
|
|
</p> |
326 |
|
|
<example> |
327 |
|
|
<p> |
328 |
|
|
This is a paragraph. All the text in a paragraph is combined to one continous |
329 |
|
|
text block. You may add as much text as you want to a paragraph of your article, |
330 |
|
|
but better separate you article into logical parts of separate paragraphs. So to start a |
331 |
|
|
new paragraph, wrap the next text block into a new pair of paragraph tags. |
332 |
|
|
</p> |
333 |
|
|
<p> |
334 |
|
|
This is the next paragraph. There will be an empty line between this paragraph and |
335 |
|
|
the previous and next paragraph, to separate paragraphs visually from each other. |
336 |
|
|
</p> |
337 |
|
|
</example> |
338 |
|
|
<p> |
339 |
|
|
Wrapping paragraphs into <code><p>??text??</p></code> blocks not only causes |
340 |
|
|
trivial new lines in between them. This construct also allows you to easily |
341 |
|
|
define whether certain additional content like images and source code |
342 |
|
|
examples shall be shown directly embedded within the text block or shall |
343 |
|
|
rather be shown separately outside of text blocks, like described next. |
344 |
|
|
</p> |
345 |
|
|
|
346 |
|
|
<h2>Pictures</h2> |
347 |
|
|
<p> |
348 |
|
|
To display i.e. screen shots, figures and other kinds of images in your |
349 |
|
|
article, simply place the picture file in the directory where your |
350 |
|
|
current article's file is located at. Then add the image to your article |
351 |
|
|
with an <code><img src="some_picture.png"></code> HTML tag. There are two |
352 |
|
|
distinct ways to do that, like described below. |
353 |
|
|
</p> |
354 |
|
|
<h3>Stand-Alone Pictures</h3> |
355 |
|
|
<p> |
356 |
|
|
To place a picture on |
357 |
|
|
its own between two text paragraphs, simply place the <code><img></code> |
358 |
|
|
tag between the two paragraphs in your HTML file: |
359 |
|
|
</p> |
360 |
|
|
<code> |
361 |
|
|
<p> |
362 |
|
|
This is the first paragraph. Just before the picture. |
363 |
|
|
</p> |
364 |
|
|
|
365 |
|
|
<img src="some_picture.png" caption="??footnote??" title="??tooltip-text??"> |
366 |
|
|
|
367 |
|
|
<p> |
368 |
|
|
This is the next paragraph, just after the picture. |
369 |
|
|
</p> |
370 |
|
|
</code> |
371 |
|
|
<p> |
372 |
|
|
The optional <code>??footnote??</code> adds a footnote text just below the |
373 |
|
|
image and the optional <code>??tooltip-text??</code> defines a text which |
374 |
|
|
will popup if the reader points his mouse over the image. The previous |
375 |
|
|
example would look like this: |
376 |
|
|
</p> |
377 |
|
|
<example> |
378 |
|
|
<p> |
379 |
|
|
This is the first paragraph. Just before the picture. |
380 |
|
|
</p> |
381 |
|
|
<img src="a_picture.png" caption="Some Explanation" title="A tooltip text"> |
382 |
|
|
<p> |
383 |
|
|
This is the next paragraph, just after the picture. |
384 |
|
|
</p> |
385 |
|
|
</example> |
386 |
|
|
<p> |
387 |
|
|
You also don't have to care about the size of the image. If the image |
388 |
|
|
resolution is largen than the width of the article would currently require |
389 |
|
|
on the user's screen, then the image will automatically be downscaled to |
390 |
|
|
fit the width of the article. It is recommended though to keep the width |
391 |
|
|
of images approximately below 1200px, just to not waste too much repository space |
392 |
|
|
(that is disk space) and network bandwidth. |
393 |
|
|
</p> |
394 |
|
|
|
395 |
|
|
<h3>Embedded Pictures</h3> |
396 |
|
|
<p> |
397 |
|
|
Sometimes however it looks nicer to have a picture embedded directly inside a |
398 |
|
|
paragraph of text and let that text float around that picture, especially |
399 |
|
|
when using rather small images. To achieve that, simply place the image |
400 |
|
|
tag inside the paragraph of your HTML file like: |
401 |
|
|
</p> |
402 |
|
|
<code> |
403 |
|
|
<p> |
404 |
|
|
<img src="some_picture.png"> |
405 |
|
|
This is some text of a paragraph. In this particular case, this text will |
406 |
|
|
float around the picture. The rest of this text is just repeating, |
407 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
408 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
409 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
410 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
411 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
412 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
413 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
414 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
415 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating. |
416 |
|
|
</p> |
417 |
|
|
</code> |
418 |
|
|
<p> |
419 |
|
|
Which would look like this: |
420 |
|
|
</p> |
421 |
|
|
<example style="clear:both;"> |
422 |
|
|
<p> |
423 |
|
|
<img src="a_picture.png"> |
424 |
|
|
This is some text of a paragraph. In this particular case, this text will |
425 |
|
|
float around the picture. The rest of this text is just repeating, |
426 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
427 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
428 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
429 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
430 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
431 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
432 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
433 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating, |
434 |
|
|
repeating, repeating, repeating, repeating, repeating, repeating. |
435 |
|
|
</p> |
436 |
|
|
</example> |
437 |
|
|
<p> |
438 |
|
|
As you can see, no special knowledge in i.e. HTML or CSS required to achieve |
439 |
|
|
such things very easily. |
440 |
|
|
</p> |
441 |
|
|
|
442 |
|
|
<h3>Unique Pictures</h3> |
443 |
|
|
<p> |
444 |
|
|
Once your article and its picture(s) are uploaded to our server, our |
445 |
|
|
system will automatically check that all images on our entire site have |
446 |
|
|
unique and unambiguous file names, no matter at which directory they |
447 |
|
|
are stored to exactly. The "file name" that is checked in this case, is |
448 |
|
|
actually the picture's file name without its file type extension |
449 |
|
|
(i.e. without ".png", ".jpg", ".gif", etc. at its end). There are two reasons for this: |
450 |
|
|
<ol> |
451 |
|
|
<li><b>Site Structure Changes:</b> |
452 |
|
|
After a while, the structure on a website changes. Certain articles |
453 |
|
|
are moved to completely different directories and some article's may |
454 |
|
|
reference pictures that were already added and used by other articles before. |
455 |
|
|
Which makes sense of course, why saving the exact same picture 10 times |
456 |
|
|
under different image files if you can just reference that already existing image file from your new article? |
457 |
|
|
Now when those articles and/or the images move to different locations, |
458 |
|
|
the image references within such articles might turn to dead references. |
459 |
|
|
Our system automatically detects this and corrects the references in |
460 |
|
|
articles to any kind of image file automatically, without requiring |
461 |
|
|
any user intervention. So we can change the structure of the website |
462 |
|
|
at any time without having to update any article file. |
463 |
|
|
</li> |
464 |
|
|
<li><b>File Type Changes:</b> |
465 |
|
|
Sometimes it happens that a picture needs to be replaced with a |
466 |
|
|
picture in a different file format. For example the original picture |
467 |
|
|
was added in .jpeg format to have a very small file size, but later on |
468 |
|
|
some kind of transparency is required for the picture, which is not |
469 |
|
|
supported by JPEG. In this case the picture would i.e. be updated |
470 |
|
|
and replaced with a .png image file. Our system also detects this and |
471 |
|
|
automatically updates all references to that image file in all articles |
472 |
|
|
to the precise new name of the image file. Again, no user intervention |
473 |
|
|
required. |
474 |
|
|
</li> |
475 |
|
|
</ol> |
476 |
|
|
But for the system to be able to that automatically, it requires all |
477 |
|
|
image files to have unique file names, like described above. If you try |
478 |
|
|
to upload a new image file to our system which uses a file name that was |
479 |
|
|
already taken by another image, then you will automatically be notified by |
480 |
|
|
our system via email, asking you to rename one of the image files. |
481 |
|
|
</p> |
482 |
|
|
|
483 |
|
|
<h2>Source Code</h2> |
484 |
|
|
<p> |
485 |
|
|
You might need to post example source code in some of your articles. This |
486 |
|
|
is very simple to do. Just wrap your source code into a pair of |
487 |
|
|
<code><code></code> tags like this: |
488 |
|
|
</p> |
489 |
|
|
<code> |
490 |
|
|
<code> |
491 |
|
|
|
492 |
|
|
??source-code?? |
493 |
|
|
|
494 |
|
|
</code> |
495 |
|
|
</code> |
496 |
|
|
<p> |
497 |
|
|
Syntax highlighting is automatically generated for you, according to the |
498 |
|
|
programming language or markup language used by you. That way you don't |
499 |
|
|
have to waste time on how to display source code nicely, and rather |
500 |
|
|
concentrate on the content of your article. Like with images, you can |
501 |
|
|
decide in which context the source code shall appear in your article, |
502 |
|
|
as described next. |
503 |
|
|
</p> |
504 |
|
|
|
505 |
|
|
<h3>Stand-Alone Code</h3> |
506 |
|
|
<p> |
507 |
|
|
If you put your code block outside of paragraphs, that is between |
508 |
|
|
paragraph blocks in your HTML file, then the source code will also appear |
509 |
|
|
on its own between the paragraph blocks. Here is an example for the |
510 |
|
|
<a href="nksp.html">NKSP script language</a>. |
511 |
|
|
</p> |
512 |
|
|
<code> |
513 |
|
|
<p> |
514 |
|
|
Paragraph just before the source code block. |
515 |
|
|
</p> |
516 |
|
|
<code> |
517 |
|
|
on init |
518 |
|
|
@foo := "A message" |
519 |
|
|
message(@foo) |
520 |
|
|
end on |
521 |
|
|
</code> |
522 |
|
|
<p> |
523 |
|
|
Next paragraph just after the source code block. |
524 |
|
|
</p> |
525 |
|
|
</code> |
526 |
|
|
<p> |
527 |
|
|
Which would appear like: |
528 |
|
|
</p> |
529 |
|
|
<example> |
530 |
|
|
<p> |
531 |
|
|
Paragraph just before the source code block. |
532 |
|
|
</p> |
533 |
|
|
<code lang="nksp"> |
534 |
|
|
on init |
535 |
|
|
@foo := "A message" |
536 |
|
|
message(@foo) |
537 |
|
|
end on |
538 |
|
|
</code> |
539 |
|
|
<p> |
540 |
|
|
Next paragraph just after the source code block. |
541 |
|
|
</p> |
542 |
|
|
</example> |
543 |
|
|
<p> |
544 |
|
|
The source code automatically appears nicely in color and with line |
545 |
|
|
numbers between the two paragraphs. This site's software will also take |
546 |
|
|
care about removing white lines at the front and end of your source code |
547 |
|
|
blocks appropriately. |
548 |
|
|
</p> |
549 |
|
|
|
550 |
|
|
<h3>Embedded Code</h3> |
551 |
|
|
<p> |
552 |
|
|
In case you are mentioning a very small part of the source code in your |
553 |
|
|
text, then you probably might want that to be displayed actually as source code |
554 |
|
|
directly embedded into your paragraph. You might already guess how to |
555 |
|
|
do that: simply put the code block into the paragraph text block of your |
556 |
|
|
HTML file: |
557 |
|
|
</p> |
558 |
|
|
<code> |
559 |
|
|
<p> |
560 |
|
|
A variable is assigned with NKSP like this <code>$foo := 5</code>, in this |
561 |
|
|
case you are assigning <code>5</code> to the integer variable <code>$foo</code>. |
562 |
|
|
</p> |
563 |
|
|
</code> |
564 |
|
|
<p> |
565 |
|
|
And this would be the result: |
566 |
|
|
</p> |
567 |
|
|
<example> |
568 |
|
|
<p> |
569 |
|
|
A variable is assigned with NKSP like this <code lang="nksp">$foo := 5</code>, in this |
570 |
|
|
case you are assigning <code lang="nksp">5</code> to the integer variable <code lang="nksp">$foo</code>. |
571 |
|
|
</p> |
572 |
|
|
</example> |
573 |
|
|
<p> |
574 |
|
|
That looks now much more easier to read, doesn't it? |
575 |
|
|
</p> |
576 |
|
|
|
577 |
|
|
<note> |
578 |
|
|
Syntax highlighting of source code is automatically generated by our site's software |
579 |
|
|
once the document is uploaded to our server. So when you are just |
580 |
|
|
previewing your article with source code snippets on your local machine, |
581 |
|
|
then those source code snippets will yet be displayed monochrome, |
582 |
|
|
without any syntax highlighting. |
583 |
|
|
</note> |
584 |
|
|
|
585 |
|
|
<note> |
586 |
|
|
Automatic syntax highlighting is currently available for the |
587 |
|
|
<ul> |
588 |
|
|
<li>NKSP real-time instrument script language |
589 |
|
|
<li>HTML markup language</li> |
590 |
|
|
</ul> |
591 |
|
|
If you need another source code language, just tell |
592 |
|
|
<a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
593 |
|
|
and he will add the required module for any kind of language |
594 |
|
|
(even the most exotic one) on our server in short time. |
595 |
|
|
</note> |
596 |
|
|
|
597 |
|
|
<h3>Metaphors</h3> |
598 |
|
|
<p> |
599 |
|
|
You might have noticed, we have used a special kind of <code>??place-holder??</code> for |
600 |
|
|
human-readable portions in source code before, which shall outline to the reader |
601 |
|
|
that it is not actually "real" source code, but just reflecting its semantic meaning. |
602 |
|
|
Simply put the respective pseudo-code into a pair of two question marks, |
603 |
|
|
like so: |
604 |
|
|
</p> |
605 |
|
|
<code> |
606 |
|
|
<code> |
607 |
|
|
on init |
608 |
|
|
declare const $i = \?\?some-value\?\? |
609 |
|
|
|
610 |
|
|
message(\?\?text-string\?\?) |
611 |
|
|
end on |
612 |
|
|
</code> |
613 |
|
|
</code> |
614 |
|
|
<p> |
615 |
|
|
Which will look like this: |
616 |
|
|
</p> |
617 |
|
|
<example> |
618 |
|
|
<code lang="nksp"> |
619 |
|
|
on init |
620 |
|
|
declare const $i = ??some-value?? |
621 |
|
|
|
622 |
|
|
message(??text-string??) |
623 |
|
|
end on |
624 |
|
|
</code> |
625 |
|
|
</example> |
626 |
|
|
<p> |
627 |
|
|
These <i>metaphors</i> are especially useful in beginners tutorials for |
628 |
|
|
clearly separating real source code portions from pseudo-code portions, |
629 |
|
|
and to point the reader's eyes to the most important locations of your |
630 |
|
|
source code snippet. |
631 |
|
|
</p> |
632 |
|
|
|
633 |
|
|
<h2>Links and Article File Names</h2> |
634 |
|
|
<p> |
635 |
|
|
If you want to add links in your article to another article or to some |
636 |
|
|
other website, then you just use an ordinary HTML link tag pair: |
637 |
|
|
</p> |
638 |
|
|
<code> |
639 |
|
|
<p> |
640 |
|
|
This paragraph contains <a href="../nksp.html">a link to another article</a> |
641 |
|
|
and to <a href="http://www.linuxsampler.org">another website</a>. |
642 |
|
|
</p> |
643 |
|
|
</code> |
644 |
|
|
<example> |
645 |
|
|
<p> |
646 |
|
|
This paragraph contains <a href="../nksp.html">a link to another article</a> |
647 |
|
|
and to <a href="http://www.linuxsampler.org">another website</a>. |
648 |
|
|
</p> |
649 |
|
|
</example> |
650 |
|
|
<p> |
651 |
|
|
Concerning links to other websites, there is nothing special for you to know about. |
652 |
|
|
</p> |
653 |
|
|
<p> |
654 |
|
|
Regarding local links to another article however: these are monitored |
655 |
|
|
similar like references to image files (as <a href="#unique_pictures">described before</a>), that is |
656 |
|
|
our system automatically detects if the path of some of your local links to |
657 |
|
|
another article is incorrect, i.e. because the website structure changed |
658 |
|
|
in the meantime, and it will automatically correct the path to the correct |
659 |
|
|
location of the article for you, without requiring any user intervention. |
660 |
|
|
For this reason, all articles must have unique file names for the entire |
661 |
|
|
site, no matter in which directory the respective article's HTML file is |
662 |
|
|
located at exactly. |
663 |
|
|
</p> |
664 |
|
|
<p> |
665 |
|
|
An article file on our site usually has the following |
666 |
|
|
file name form: |
667 |
|
|
</p> |
668 |
|
|
<code> |
669 |
|
|
??number-prefix??_??unique-name??.html |
670 |
|
|
</code> |
671 |
|
|
<p> |
672 |
|
|
The <code>??number-prefix??</code> is optional. It allows us to control |
673 |
|
|
the order of articles on the same website structure level (i.e. |
674 |
|
|
concerning its location in the navigation bar). |
675 |
|
|
The <code>??unique-name??</code> portion of the file name though is actually the |
676 |
|
|
relevant part our site's software is looking at. This "root" of its file |
677 |
|
|
name must be globally unique among our entire site. If you add a new |
678 |
|
|
article to our site with a file name that is already taken by another |
679 |
|
|
article, then our system will automatically inform you via email to |
680 |
|
|
resolve this issue by renaming one of them. Also note that the file name |
681 |
|
|
just acts as internal ID while writing articles. The original file name |
682 |
|
|
of the input HTML file will not be directly exposed to readers on our |
683 |
|
|
documentation site. |
684 |
|
|
</p> |
685 |
|
|
|
686 |
|
|
<h2>Terms</h2> |
687 |
|
|
<p> |
688 |
|
|
Technical terms and abbreviations are often used in articles to reduce |
689 |
|
|
the amount of text for transmitting some kind of information about a |
690 |
|
|
certain topic to the reader. You might want to emphasize technical terms and abbreviations |
691 |
|
|
in your article, by wrapping the term into a pair of <code><i></code> HTML |
692 |
|
|
tags. On our site this will not only show the term in a special unified |
693 |
|
|
font style (currently italic), but it allows you also to define the |
694 |
|
|
meaning of the term <b>once</b>. Which goes like this: |
695 |
|
|
</p> |
696 |
|
|
|
697 |
|
|
<h3>Defining a Term</h3> |
698 |
|
|
<p> |
699 |
|
|
You may define a new term like this: |
700 |
|
|
</p> |
701 |
|
|
<code> |
702 |
|
|
<p> |
703 |
|
|
He left the bar and jumped right into his |
704 |
|
|
<i title="A very large vehicle.">Mega Liner</i> |
705 |
|
|
to follow the street right into sunset. |
706 |
|
|
</p> |
707 |
|
|
</code> |
708 |
|
|
<example> |
709 |
|
|
<p> |
710 |
|
|
He left the bar and jumped right into his |
711 |
|
|
<i title="A very large truck vehicle.">Mega Liner</i> |
712 |
|
|
to follow the street right into sunset. |
713 |
|
|
</p> |
714 |
|
|
</example> |
715 |
|
|
<p> |
716 |
|
|
Now when you point your mouse over the term, a popup will appear, |
717 |
|
|
describing the meaning of the term. |
718 |
|
|
</p> |
719 |
|
|
|
720 |
|
|
<h3>Referencing an already defined Term</h3> |
721 |
|
|
<p> |
722 |
|
|
Obviously you don't want to define |
723 |
|
|
the same term over and over again, just to provide the user the meaning of |
724 |
|
|
it at any occurence of the site. That's why our software does that |
725 |
|
|
automatically for you once your article is uploaded to our server. Now |
726 |
|
|
when you use the term at another place, i.e. in another article, then |
727 |
|
|
it will automatically have the same meaning attached to it: |
728 |
|
|
</p> |
729 |
|
|
<code> |
730 |
|
|
<p> |
731 |
|
|
Once again he was sitting behind the wheel of his <i>Mega Liner</i>, |
732 |
|
|
but things were different back then. |
733 |
|
|
</p> |
734 |
|
|
</code> |
735 |
|
|
<example> |
736 |
|
|
<p> |
737 |
|
|
Once again he was sitting behind the wheel of his <i>Mega Liner</i>, but |
738 |
|
|
things were different back then. |
739 |
|
|
</p> |
740 |
|
|
</example> |
741 |
|
|
<p> |
742 |
|
|
Point your mouse again over the term, and you will notice that the same |
743 |
|
|
term definition will popup as tooltip, like at its original location where |
744 |
|
|
it was defined before. |
745 |
|
|
<p> |
746 |
|
|
</p> |
747 |
|
|
Due to this fact, our site's software does not even allow you to define the |
748 |
|
|
same term more than once (at least not with a different meaning that is). |
749 |
|
|
It will scan all documents in our current pool and if somebody tries to |
750 |
|
|
re-declare an already existing term again with a different meaning, he |
751 |
|
|
will automatically be notified by our system via email and kindly asked |
752 |
|
|
to resolve the ambiguousness. |
753 |
|
|
</p> |
754 |
|
|
<note> |
755 |
|
|
Our system automatically handles redundant variants of terms. That means |
756 |
|
|
first of all, that all term names are stored, compared and looked up case insensitive, |
757 |
|
|
and the system automatically tries to auto complete i.e. plural forms |
758 |
|
|
of the same term. |
759 |
|
|
</note> |
760 |
|
|
|
761 |
|
|
<h2>Tables</h2> |
762 |
|
|
<p> |
763 |
|
|
Tables are written like ordinary HTML tables. That is: |
764 |
|
|
</p> |
765 |
|
|
<code> |
766 |
|
|
<table> |
767 |
|
|
<tr> |
768 |
|
|
<th>Name</th> <th>Description</th> |
769 |
|
|
</tr> |
770 |
|
|
<tr> |
771 |
|
|
<td>Foo</td> <td>Some text.</td> |
772 |
|
|
</tr> |
773 |
|
|
<tr> |
774 |
|
|
<td>Bar</td> <td>And more text.</td> |
775 |
|
|
</tr> |
776 |
|
|
<tr> |
777 |
|
|
<td>Thing</td> <td>And that's it.</td> |
778 |
|
|
</tr> |
779 |
|
|
</table> |
780 |
|
|
</code> |
781 |
|
|
<example> |
782 |
|
|
<table> |
783 |
|
|
<tr> |
784 |
|
|
<th>Name</th> <th>Description</th> |
785 |
|
|
</tr> |
786 |
|
|
<tr> |
787 |
|
|
<td>Foo</td> <td>Some text.</td> |
788 |
|
|
</tr> |
789 |
|
|
<tr> |
790 |
|
|
<td>Bar</td> <td>And more text.</td> |
791 |
|
|
</tr> |
792 |
|
|
<tr> |
793 |
|
|
<td>Thing</td> <td>And that's it.</td> |
794 |
|
|
</tr> |
795 |
|
|
</table> |
796 |
|
|
</example> |
797 |
|
|
<p> |
798 |
|
|
So <code><tr></code> wraps up individual rows of a table, |
799 |
|
|
<code><th></code> contains the individual cells of the table header, |
800 |
|
|
and <code><td></code> contains the individual cells of the table's |
801 |
|
|
body. |
802 |
|
|
</p> |
803 |
|
|
|
804 |
|
|
<h2>Note Boxes</h2> |
805 |
|
|
<p> |
806 |
|
|
Once in a while you need to inform the reader about noteworthy issues. |
807 |
|
|
For this purpose we are using a special <code><note></code> tag. |
808 |
|
|
</p> |
809 |
|
|
<h3>Regular Notes</h3> |
810 |
|
|
<p> |
811 |
|
|
To add regular notes to your article with low or normal importance, add |
812 |
|
|
the note like this: |
813 |
|
|
</p> |
814 |
|
|
<code> |
815 |
|
|
<note> |
816 |
|
|
This is an issue you need to know about. Please read this carefully to avoid |
817 |
|
|
making any mistakes. |
818 |
|
|
</note> |
819 |
|
|
</code> |
820 |
|
|
<example> |
821 |
|
|
<note> |
822 |
|
|
This is an issue you need to know about. Please read this carefully to avoid |
823 |
|
|
making any mistakes. |
824 |
|
|
</note> |
825 |
|
|
</example> |
826 |
|
|
<p> |
827 |
|
|
This is not a regular HTML tag defined in the HTML standard, but with |
828 |
|
|
modern browsers supporting CSS3, it should display just as intended. |
829 |
|
|
</p> |
830 |
|
|
|
831 |
|
|
<h3>Important Notes</h3> |
832 |
|
|
<p> |
833 |
|
|
If you need to inform the reader about a very important issue instead, |
834 |
|
|
then you might use the following slightly different form: |
835 |
|
|
</p> |
836 |
|
|
<code> |
837 |
|
|
<note class="important"> |
838 |
|
|
Now this is a very important issue you need to be aware of. If you ignore it, |
839 |
|
|
your task will fail. |
840 |
|
|
</note> |
841 |
|
|
</code> |
842 |
|
|
<example> |
843 |
|
|
<note class="important"> |
844 |
|
|
Now this is a very important issue you need to be aware of. If you ignore it, |
845 |
|
|
your task will fail. |
846 |
|
|
</note> |
847 |
|
|
</example> |
848 |
|
|
<p> |
849 |
|
|
The only thing that changed compared to the regular note, is the "class" |
850 |
|
|
attribute of the note tag. |
851 |
|
|
</p> |
852 |
|
|
|
853 |
|
|
<h2>Extensions</h2> |
854 |
|
|
<p> |
855 |
|
|
This is almost the end of this article. You are still seeking for features |
856 |
|
|
for one of your articles, that are not already covered by our system? |
857 |
|
|
Then either ask <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
858 |
|
|
whether that feature could be added, or ... extend your article on your |
859 |
|
|
own. It's real HTML after all! So you can add your own HTML, CSS and |
860 |
|
|
Java Script to your articles at any time! |
861 |
|
|
</p> |
862 |
|
|
|
863 |
|
|
<h2>What next?</h2> |
864 |
|
|
<p> |
865 |
|
|
You are at the end of our tour introducing our documentation system. |
866 |
|
|
You may now start writing your first article. Once you are done with it, |
867 |
|
|
simply |
868 |
|
|
<a href="http://www.linuxsampler.org/developers.html"> |
869 |
|
|
send your article to some of us |
870 |
|
|
</a>, or request an account to our Subversion repository, so you can |
871 |
|
|
manage articles of our documentation site on your own. |
872 |
|
|
</p> |
873 |
|
|
<p> |
874 |
|
|
Thanks for your support! |
875 |
|
|
</p> |
876 |
|
|
|
877 |
|
|
</body> |
878 |
|
|
</html> |