Creating a new document or tutorial for Qt.Py
This tutorial will show you :
After many hours of work, the portal is finally ready for use. If you'd now like
to contribute to the "Documents" section, this text will help you getting started.
While designing Qt.Py, care was taken to ensure contributors will have to deal
with layout issues only to a very small extend. The chances are high you won't have
to any layout. This is arcihved by extensive use of stylesheets, which allow you to
logically define your documents, instead of using graphical HTML-tags.
To be able to add a document, you don't have to understand much of the interiors,
but anyway, some things are required for your work to integrate nicely within the
environment.
Basically, every document, tutorial and article resides in an own subdir under the
document-root. And the document-root is a subdir of Qt.Py's HTML-root itself. Within your
own document dir, your article will contain all files, graphics and support files which are
required to view the it correctly. (Note : The style-sheets are an exception to this rule.
I'll tell about them later).
Fig. 1 gives a brief overview.
The document-root is highlighted, under it are three documents. "qt.py-newdoc", which
you are currently reading, is one of them. Think of "myTutorial" as the document you
want to add.
In order to start work, just download
template.zip and
extract it. A directory naming "template" will show up. Rename it to something
which fits to your document. The name of the dir is not too important, but it
should be unique. (If it is not, we just rename it). In it, you will find two files.
"index.html" and "document.css". "index.html" is the file you will be working with,
"documents.css" is a local copy of the global document-style. When uploading your
project, this file will be deleted (or at least ignored).
You may ask yourself "Why index.html ?". The answer is easy : Because a document
should consist of only a single page to read. Although it is easily possible to
split up your document into page 1 ... n, I strongly discourage it. (If you
really think it's getting too large, better make two documents of it, which
can be read separatly).
Now open "index.html" in your favourite editor. The file may look a bit chaotic,
but thats due to the examples and comments within.
Now we will discuss several parts of a document and what they are needed for. In
general, a every document, tutorial or article should at least consist of this :
A headline or title.
An abstract section.
The main content.
References, links and related stuff.
Information about the author.
Besides the facts given below, please consider reading the "Qt.Py extention and
modification guideline". It gives additional information to the points below
and some other hints for writing documents.
should give a user a brief, concentrated overview about the content. There should
not be any unnecessary word in it. Just pure information.
describes in a few sentences what this document
will teach. After lecture of this, the reader should be certain if
your document covers her area of interest.
Within the central document, you can almost do whatever you like. However, there
are some points you should understand : Keep your document free of major layout tags. HTML is a mixture of layout
and logical tags, which provide a good overall-set of features needed for building
homepages. But for writing documentation, we need a more specialized set of tags
which allow more logical formatting and less layouting. Qt.Py's document-stylesheet
already contains such of logical tags which you should use to mark paragraphs
of your document (e.g. sections, figures, title, author, ...). Together with
central stylesheets, this gurantees some common look across all published work.
give a brief overview about related material and work on which your document was
based on. Also, all links to files you already gave should go again in here.
Pretty self-explaining. Just your name, email, shoe-size in the author section.
Also, give a copyright notice with a date.
After you've written down everything you wanted, you may ask yourself : "Whats next ?".
The answer is easy : Just send it to us. Simply go to the document section and follow
the instructions given there. But before you do so, please check these points :
- Have you replaced the local stylesheet with the global one ?
Go to the top of the html-source and comment out the local on in order
to enable the local one (See Fig. 2)
- Did you include all files, graphics, ... ?
- Are all links working correctly ?
So, I hope this document has helped you, and I really appreciate your feedback.
-Marc
References
