[Linuxsampler-devel] docs.linuxsampler.org

[Christian S. <sch...@li...>]

Hi!

Since documentation and website are currently in a horrible old condition, I 
thought about launching a new site for documentation, probably as new 
subdomain docs.linuxsampler.org (or under www.linuxsampler.org/docs/).

Flat layout: Here is a mockup as an overall layout suggestion for that 
documentation site:

http://download.linuxsampler.org/pix/screenshots/mockup_docs_linuxsampler_org.png

I am not the biggest fan of flat layout (especially since many companies 
already brought their layouts on "kindergarten flat" level), but in this case 
I though it makes sense. The suggested font used is a free one called
"Ek Mukta", a modern sans serif font, providing a large set of font weights 
(ultra thin, thin, normal, semi bold, bold, ultra bold) and is well readable 
for human beings. You can preview this font in various styles i.e. on Google 
Fonts.


Visual structure:

- On the very top there is a hard coded dark gray bar with global links to 
  important topics, i.e. links to the documentation entry points for our 
  various apps, links to other servers, etc.

- Just below the hard coded link bar, there is an auto generated light gray 
  navigation bar, showing the current overall tree location on the 
  documentation web server, which allows to jump back to some parent article.

- Main block to the right with white background; the current article.

- On the very left there is table of contents of the currently visible 
  article. The user may auto scroll the current article by clicking on an item 
  of that table of contents, and vice versa the table of contents 
  automatically highlights the currently visible paragraph when the user 
  scrolls the article on the right.

- Hard coded footer on the very bottom, copyright notice, and probably some 
  more links, etc.


File & Directory Structure:

My suggestion is to write the actual articles as stripped-down HTML input 
files, without "html" tag, without "body" tag, root tag would be an "article" 
tag, everything inside that root "article" tag would be regular html (and CSS) 
with all its possibilities. The html input files would be managed on svn and 
our build server would auto generate the actual (static) website by processing 
those input html files whenever somebody commits something new, thus auto 
generating especially navigation bar, table of contents, website header and 
footer for each page. Each input HTML file would be named "index.html" and 
thus being in its own directory on svn. The resulting input directory names 
and input directory structure would be taken to auto generate the navigation 
structure of the website.

Besides the actual articles files, there would be couple other input files 
defining the overall look of the website globally, separate from the 
individual articles.

An example input article file based on these suggestions might look like this:

<article title="Conditional Statements">
  <p>Conditional statements are bla bla bla.</p>

  <h3>A deeper view</h3>
  <p>Bla bla bla.</p>

  <h3>And even more</h3>
  <p>Bla bla bla. <a href="foo">Read more about topic foo ...</a></p>

  <h3>Starting the hack</h3>
  <p>
    Bla bla bla.
    <code lang="nksp">
on init
  declare $a := "bla"
  declare @h := "Hello "
  declare const @w := "world!"
  message(@h)
  message(@w)
end on
    </code>
    bla bla bla bla.
  </p>

  <h2>The next level</h2>
  <p>Bla bla bla.</p>

</article>

So table of contents of an article would be auto generated by reading the 
regular "h2" and "h3" html tags. Article name and thus website page title 
would be defined by the "title" attribute of the "article" tag.

Syntax highlighting for example code blocks would also be auto generated. The 
"lang" attribute of the "code" tag would be mandatory to give the build server 
an idea which programming language was meant for being able to produce correct 
syntax highlighting.

Opinions, suggestions and tomatoes appreciated!

CU
Christian